Skill Registry
Skill registry indexes let a team share local Skill packages without requiring remote downloads or a plugin marketplace. The current implementation is intentionally local-first: an index resolves a skill directory that already exists beside the index file or at an absolute path.
Local Index File
Use skills.index.toml as the conventional file name:
schema_version = 1
name = "team-skills"
description = "Shared skills for this repository."
[[skills]]
name = "mcp-basic"
version = "1.0.0"
path = "skills/mcp-basic"
manifest = "SKILL.md"
manifest_sha256 = "sha256:<optional manifest digest>"
aliases = ["mcp-demo"]
channel = "stable"
Fields:
schema_version: required compatibility marker. Version1is the only supported schema. Future incompatible changes must increment this value.name: human-readable index name shown by CLI commands.description: optional index description.skills: non-empty list of skill entries.skills[].name: canonical skill name. It must match the loaded manifestskill.name.skills[].version: semantic version. It must match the loaded manifest version.skills[].path: skill directory. Relative paths are resolved from the index file directory.skills[].manifest: optional manifest path relative to the skill directory. When omitted, Yanshi detectsskill.tomlfirst, thenSKILL.md.skills[].manifest_sha256: optional SHA-256 lock for the manifest file. The value can be raw hex or prefixed withsha256:.skills[].aliases: optional alternate names accepted byresolveandinstall. Aliases share the same uniqueness namespace as canonical names.skills[].channel: optional distribution channel such asstable,beta, or an internal rollout ring.
Compatibility Policy
Schema version 1 is local-path based and has no network source fields. Tools
must reject unsupported schema_version values rather than guessing. Optional
fields can be added to schema version 1 only when older clients can safely
ignore them.
The canonical identity is name + version. Aliases are lookup conveniences, not
separate packages. A release process should update the manifest version and the
index entry version together.
Manifest Locking
manifest_sha256 is a lightweight integrity check for the manifest selected by
manifest or manifest auto-detection. Use it when:
- an organization wants reviewable changes to Skill instructions, tools, MCP servers, or permissions;
- a shared index points at a directory that may change over time;
- a release branch needs to pin a known manifest while allowing non-manifest files such as examples or references to evolve separately.
The current lock covers only the manifest file, not the full directory tree. It is not a supply-chain signature and does not replace code review for scripts, MCP servers, or referenced knowledge files.
Local Workflow
Validate and inspect an index:
cargo run -p yanshi-cli -- skill index validate yanshi-skills/examples/skills.index.toml
cargo run -p yanshi-cli -- skill index list yanshi-skills/examples/skills.index.toml
cargo run -p yanshi-cli -- skill index resolve yanshi-skills/examples/skills.index.toml mcp-demo
Install a resolved skill into a local skills directory:
cargo run -p yanshi-cli -- skill install yanshi-skills/examples/skills.index.toml mcp-demo \
--dir /tmp/yanshi-skills
cargo run -p yanshi-cli -- skill validate /tmp/yanshi-skills/mcp-basic
cargo run -p yanshi-cli -- skill list-tools /tmp/yanshi-skills/mcp-basic
skill install copies the resolved local directory to <target>/<skill-name>.
It refuses to overwrite an existing directory unless --force is passed.
Upgrade Model
The local upgrade path is explicit:
- Update the Skill manifest and files.
- Bump the manifest version.
- Update the index entry version.
- Recompute
manifest_sha256when the index uses a lock. - Run
skill index validate. - Reinstall with
skill install ... --forcewhen the destination should be replaced.
There is no automatic background upgrade in the current model.
Remote Registry Boundary
Future remote registry or Git install support should extend this local model without changing local semantics:
- keep
resolvereturning a concrete skill directory and manifest path before install; - download or clone into a cache first, then reuse the same validation and copy path used by local install;
- add source fields such as
git,rev,subdir, orarchive_urlonly under a compatible schema plan; - require explicit trust and overwrite decisions instead of silently replacing installed skills;
- keep remote network access out of
skill index validateunless the user asks for a remote validation mode.
This preserves the current no-network CI path while leaving room for Git-backed or Skill-catalog-backed distribution.
Marketplace Manifest
A marketplace manifest is a Skill catalog that groups one or more registry
indexes into a browsable list. It does not replace skills.index.toml; instead it points at local,
organization, or future remote indexes and lets the CLI show install commands
that still use yanshi skill install <index_file> <skill>.
Use marketplace.toml as the conventional file name:
schema_version = 1
name = "team-marketplace"
description = "Curated skills approved for this team."
homepage = "https://example.com/yanshi/skills"
[[indexes]]
name = "team"
kind = "organization"
source = "skills.index.toml"
description = "Repository-local team skills."
trust = "reviewed"
[[featured]]
skill = "mcp-basic"
index = "team"
reason = "Minimal Skill that exposes an MCP server."
Marketplace fields:
schema_version: required compatibility marker. Version1is supported.name: human-readable marketplace name.description: optional marketplace description.homepage: optional web page for humans.indexes[].name: unique index identifier within the marketplace.indexes[].kind:local,organization, orremote. Local validation loadslocalandorganization;remoteis declared but not fetched.indexes[].source: path to askills.index.tomlfor local/organization indexes. Relative paths are resolved from the marketplace file directory.indexes[].trust: optional trust label such asreviewed,internal, orlocal-example.featured[]: optional curated skill references for UI or docs.
CLI flow:
cargo run -p yanshi-cli -- skill marketplace validate yanshi-skills/examples/marketplace.toml
cargo run -p yanshi-cli -- skill marketplace list yanshi-skills/examples/marketplace.toml
cargo run -p yanshi-cli -- skill marketplace resolve yanshi-skills/examples/marketplace.toml mcp-demo
marketplace resolve prints the exact yanshi skill install ... command.
The install path remains unchanged, so marketplace browsing does not add a new
trust or overwrite model. This is not a general plugin marketplace; it catalogs
Skills only.