yotta-skills

What it is

Installing the whole YottaMeta family used to mean running npx for each skill one by one. 元阁 turns it into a single command: it reads a built-in manifest (27 published skills), downloads each from its own npm package, places it into the target skills directory, and prints a summary (success / skipped / failed).

元阁 is also the family orchestration planner: given a task, check the orchestration table first — which skills to combine, in what order, and why — then install exactly those. The decision table ships in the package as references/orchestration.md and is summarized in SKILL.md.

• List - see the whole family: slug, Chinese name, package, version and a one-line description.
• Orchestration routing - --route turns a task summary into a candidate combination, call order, per-skill roles, confidence, evidence, installed/missing status, and an install command; it only suggests installation and never installs automatically. An optional local provider may add or re-order installed skills within the allow-list and return confidence / reasons / summary / alternatives (no behavior change when unconfigured; see references/provider-protocol.md).
• M1 memory adjudication - decide-memory returns read-only promote / hold / demote suggestions, scores and signal details. Scoring is performed by a user-configured local provider (capability m1.adjudicate). It is read-only by default; --promote writes only a local recommendation file and never writes memory or deletes anything. usage is off by default and records only structured signals after the user enables it.
• Install — install everything (or a subset) into an agent's default user-level directory or any directory.
• Update — incremental update: add missing skills, upgrade version-skewed ones.
• Update check / auto-update — update --check compares installed skill versions against the npm registry and reports; update --check --scheduled is the weekly background entry with a local cache and jitter, so it stays offline until due; update --auto upgrades the installed YottaMeta family to the latest (non-family skills are never auto-updated).
• Works without npm — fetching and extraction default to built-in Node channels (npm / system tar are fallbacks only); update --installed-only adopts only skills already installed on the machine and never backfills or errors on missing ones.
• Doctor / rollback — doctor checks the installed skill directory, version, manifest, registry and custom doctor script without modifying it; --dir may point to a skills container or directly to a single skill package. rollback validates a snapshot and restores the latest install or update.
• Runtime hook adapter — manifests declare six lifecycle requirements; hook capabilities / evaluate / bind / unbind probe host support, apply deterministic decisions, record evidence, and never overstate audit-only hosts as enforced.
• Idempotent — a skill already at the manifest version is skipped; re-running is safe.
• Pre-install gate — family installs read the package manifest, bootstrap yotta-verify (元信) when it is missing, then scan each package. DO NOT INSTALL blocks; caution/review continue with visible risk. Old versions are snapshotted before replacement.
• Inventory / re-index - scan the skill directories on this machine and keep a local registry (~/.yottaskills/registry.json); set YOTTA_SKILLS_REGISTRY_FILE to isolate the registry per agent; self-contained, no other skills required. Newly installed skills are discovered automatically: install / update re-index the registry afterwards, and --reindex re-scans on demand. An optional yotta-skills MCP (on-demand, not resident) exposes list_installed_skills / describe_skill / reindex / route_request / decide_memory; see SKILL.md for the config.
• No silent writes - 元阁 only suggests. Installing skills, adding a client mcpServers entry, and writing an agent's global memory each require explicit user confirmation beforehand; declining never blocks the plain CLI workflow.

Boundaries: it only downloads, places, gates and summarizes — it does not develop skill content, does not bundle any skill body, does not use -g global installs, and does not silently write host configuration or agent global memory. Besides the target directory, it keeps its registry, snapshots, install evidence and update-check cache under ~/.yottaskills.

Quick start

Primary flow (Hub as the main path; the installation itself is agent-agnostic):

# 1) See the hosts and skill directories on this machine (states: available / orphan / missing / marker-only)
npx -y @yottameta/yotta-skills hub hosts

# 2) Install into the Hub source of truth (default ~/.yottaskills/hub; no agent needed)
npx -y @yottameta/yotta-skills hub install

# 3) Distribute to every verified host (Windows junction / macOS·Linux symlink)
npx -y @yottameta/yotta-skills hub link --all

# 4) Manage from the local panel (host matrix / links & health / adoption / rollback)
npx -y @yottameta/yotta-skills view

Standalone install (run the engine as an independent CLI, no agent required):

npx -y @yottameta/yotta-skills install-self                    # default: ~/.yottaskills/yotta-skills
npx -y @yottameta/yotta-skills install-self --dir ~/tools/yotta-skills
npx -y @yottameta/yotta-skills where                           # running CLI / standalone installs / Hub location

Direct install into a specific agent (compatibility path):

# List the whole family (no network, no changes)
npx -y @yottameta/yotta-skills --list

# Install everything into an agent's default user-level skills dir
npx -y @yottameta/yotta-skills install --agent codex

# Install everything into any directory (each skill lands in <dir>/<slug>)
npx -y @yottameta/yotta-skills install --dir ~/my-skills

# Install only selected skills
npx -y @yottameta/yotta-skills install yotta-memory yotta-verify --dir ~/my-skills

# Incrementally update installed skills
npx -y @yottameta/yotta-skills update --agent codex

# Check for updates manually (read-only, no changes)
npx -y @yottameta/yotta-skills update --check

# Weekly background entry (stays offline until due; writes ~/.yottaskills/update-check.json)
npx -y @yottameta/yotta-skills update --check --scheduled

# Check and auto-update the installed YottaMeta family (pre-install gate applies; non-family skills untouched)
npx -y @yottameta/yotta-skills update --auto

# Adopt only the family skills already installed on this machine (no backfill)
npx -y @yottameta/yotta-skills update --installed-only --dir ~/my-skills

# Read-only health check (optionally with --slug / --json)
npx -y @yottameta/yotta-skills doctor --dir ~/my-skills --slug yotta-memory

# List snapshots; restore the latest install or update
npx -y @yottameta/yotta-skills rollback --list --dir ~/my-skills
npx -y @yottameta/yotta-skills rollback --slug yotta-memory --dir ~/my-skills

# Inspect host hook capability and evaluate one manifest event
npx -y @yottameta/yotta-skills hook capabilities --host codex --json
npx -y @yottameta/yotta-skills hook evaluate --host codex --event before_send --manifest ./skill-manifest.json --json

# Preview what would be installed (no network, no changes)
npx -y @yottameta/yotta-skills --dry-run

# Route a task to a combination, call order, and missing-skill install suggestion
npx -y @yottameta/yotta-skills --route "Review this code carefully before release"

# Inspect / enable local structured usage signals (off by default)
npx -y @yottameta/yotta-skills usage status
npx -y @yottameta/yotta-skills usage enable

# Read-only M1 memory adjudication; --promote writes only a local recommendation file
npx -y @yottameta/yotta-skills decide-memory --explain
npx -y @yottameta/yotta-skills decide-memory --promote --json

# Inventory installed skills on this machine (self-contained scan, no other skills needed)
npx -y @yottameta/yotta-skills --inventory

# Re-index the registry (on demand; install / update re-index automatically)
npx -y @yottameta/yotta-skills --reindex

# Discover installed agents and their skill directories (filesystem-first; no memory registry)
npx -y @yottameta/yotta-skills hub hosts

# Install once into the local Hub, then link to every verified host (default scope)
npx -y @yottameta/yotta-skills hub install
npx -y @yottameta/yotta-skills hub adopt --scan
npx -y @yottameta/yotta-skills hub adopt --apply
npx -y @yottameta/yotta-skills hub link --all
# Opt in to auto-discovered directories (lock / data bridges are never linked)
npx -y @yottameta/yotta-skills hub link --all --include-discovered
npx -y @yottameta/yotta-skills hub status
npx -y @yottameta/yotta-skills hub doctor

Requirements: Node.js 18+, npm, and system tar (built into Windows 10+ / macOS / most Linux distributions).

Commands & options

Calling npx -y @yottameta/yotta-skills <skill> without a subcommand is equivalent to install <skill>.

Supported agent keys (17): claude cursor codex gemini goose amp opencode windsurf workbuddy kiro trae trae-cn qwen comate codebuddy kimi agents. For agents not in the preset list, point --dir at their skills directory (.agents/skills is not a universal directory).

Version strategy

• Default pin: npm pack <pkg>@<exact manifest version> — fully reproducible, no silent drift onto a floating version.
• --range (opt-in): npm pack <pkg>@<major>.x — the latest patch of the same major, for users who explicitly want to follow patch releases.
• "Already at the latest" is determined by comparing the frontmatter version in <dir>/<slug>/SKILL.md with the manifest; matching versions are skipped.

Installation

Two layers first: yotta-skills (元阁) is a family installer, not a skill itself — it ships no skill bodies. It pulls each of the 27 published yotta-* skills from its own npm package into your target directory, so getting 元阁 is not the same as having the skills. After you have the installer, run install once to actually place the whole family. A single skill (e.g. @yottameta/yotta-memory) is its own npm package and installs by itself; 元阁 is the install everything at once manager, so its install path is different.

Pick any of the four methods below; the order is the recommended priority. The package always comes from npm (GitHub can be slow without a proxy; npm supports mirrors). Methods 2/3 only fetch the installer; method 4 places only the installer skill into an agent's skills directory — in each case you still run install to bring the whole family.

Method 1: npm one-liner (recommended)

# Optional China mirror: npm config set registry https://registry.npmmirror.com
npx -y @yottameta/yotta-skills install --agent <agent-name>      # install the whole family to the agent's default user-level skills dir
npx -y @yottameta/yotta-skills install --dir <your-skills-dir>   # install the whole family to a directory (e.g. ~/.codex/skills)

• npx fetches the latest yotta-skills automatically, so there is no separate installation step; this is the only method that both gets the installer and installs the family in one command.
• --agent <name> installs to that agent's default user-level directory; --list shows each agent's default directory.
• --dir <path> installs to the given directory; for agents not in the preset list, point --dir at their skills directory.
• If the mirror has not synced the new package (404): add --registry=https://registry.npmjs.org/ (a proxy may be needed in China), or wait for the mirror cache.

Method 2: git clone (developers / git available)

git clone https://github.com/YottaMeta/yotta-skills.git <your-skills-dir>/yotta-skills
cd <your-skills-dir>/yotta-skills
node bin/yotta-skills.js install --dir <your-skills-dir>

• Cloning only fetches the installer; --list only prints the manifest and installs nothing. Run install to place the whole family into the target directory.

Method 3: GitHub Download ZIP (manual / no git)

On the GitHub repository YottaMeta/yotta-skills, click Code → Download ZIP, unzip it, then run node bin/yotta-skills.js install --dir <your-skills-dir>. Copying the yotta-skills folder into an agent's skills directory only makes the installer skill itself callable (it has its own SKILL.md) — it does not bring the 27 skills; run install for that.

Method 4: install.sh (multi-agent one-liner script)

bash install.sh --agent <name>   # install the master installer skill to the agent's default user-level directory
bash install.sh --dir <path>     # install the master installer skill to the given directory
bash install.sh --list           # list agents -> default directories

• install.sh places the 元阁 installer skill itself so an agent can invoke the family installer. To install the 27 skills, run node bin/yotta-skills.js install --agent <name> (or --dir <path>).

Method 5: OpenClaw (host-native commands)

openclaw skills install @yottameta/yotta-skills   # install (with ClawHub security audit)
openclaw skills update @yottameta/yotta-skills    # update

• OpenClaw uses the ~/.openclaw/skills directory, which --inventory / --reindex recognize (including the OPENCLAW_STATE_DIR override).
• Host-native commands keep ClawHub's security-audit card and update tracking (openclaw skills update only covers ClawHub-tracked installs).

Method 1 uses the npm registry (npmmirror / npmjs) and does not depend on GitHub; Methods 2/3 use GitHub and may fail without a proxy in China.

Included skills

The full 27-skill manifest with Chinese names, package names, versions and descriptions is in references/skill-list.md (the machine-readable source is skills.json). Family coverage: Security & Guardrails (12), Quality & Engineering (4), Memory & Context (3), Writing & Expression (1), Workflow (1), Entry & Guidance (1), Compliance & Trust (1), Education & Learning (4).

How it works

For each skill in the manifest: npm pack <pkg>@<spec> into a temp directory → tar -xzf → read the package manifest → run the yotta-verify pre-install gate (bootstrap yotta-verify first when missing) → snapshot the old version and stage the new one → atomically replace <dest>/<slug> → summary report. After install / update finishes, the local skill registry is re-indexed automatically so newly installed skills show up in --inventory / --reindex (disable with --no-reindex). Details: references/install-flow.md; beginner tutorial (Chinese): references/tutorial.md.

Development & validation

# Run the test suite from the skill directory
npm test

The tests cover --list, install into a temp directory with assertions, idempotency, --pin, update, error paths, and yotta-verify scan integration (with a fake npm).

参考文档

• 常见问题：references/faq.md
• 复杂场景走查：references/walkthroughs.md

License

MIT © YottaMeta — see LICENSE.