skill-meta

Discover and load local Agent Skills on demand — a zero-dependency Python CLI + MCP server that unifies skill catalogs from DSH, Claude, Codex, and Magpie behind one lazy-loading facade. No skill summaries baked into your system prompt; search when needed, load what you use.

Part of the meta-tool family: pair it with mcp-meta (MCP lazy facade, 2 tools for N servers) — skill-meta does the same for skills (3 tools for N skill directories).

Why

Agent harnesses inject full skill catalogs into every turn. With 70+ skills that is thousands of tokens of descriptions repeated in every request, whether or not any skill is used. skill-meta collapses that to three small tool schemas (~1.1K chars) and loads full instructions only when a task actually needs them.

Related MCP server: Skill Jack MCP

Install

Requires Python 3.9+ (standard library only).

git clone https://github.com/monkey-sking/skill-meta.git
cd skill-meta
python3 -m pip install .

Or without installing:

PYTHONPATH=src python3 -m skill_meta list

CLI

skill-meta list                 # unified catalog across all host skill dirs
skill-meta list --json          # machine-readable
skill-meta search "ios design"  # keyword search, top 8
skill-meta search "lark 会议" --limit 3
skill-meta show ios-design      # print full SKILL.md content
skill-meta serve                # run the stdio MCP server

MCP

Register skill-meta serve as a stdio server in any MCP-capable host:

DSH (cordis patch)

- id: magpie-mcp-skill-meta
  command: python3
  args: [/path/to/skill-meta/venv/bin/skill-meta, serve]
  agents: [dsh]

Claude Code (/.claude.json) / Codex (/.codex/config.toml)

{ "mcpServers": { "skill-meta": { "command": "skill-meta", "args": ["serve"] } } }

[mcp_servers.skill-meta]
command = "skill-meta"
args = ["serve"]

How discovery works

The catalog scans these directories in order (first hit wins on duplicate folder names):

1. ~/.config/magpie/library/skills — Magpie shared library

2. ~/.dsh/skills — DeepSeek Harness

3. ~/.claude/skills — Claude Code

4. ~/.codex/skills — Codex CLI

5. ~/.agents/skills — cross-agent shared

Each skill is a directory containing SKILL.md with name/description frontmatter. skill_load returns the local path so agents can resolve bundled references/, scripts/, and assets/ next to the skill. No skills, personal content, credentials, or machine-specific paths are bundled in this repo.

Current limitations

• Search is keyword matching, not semantic retrieval. Whitespace-token scoring over name + description; Chinese phrase recall can be poor.

• Frontmatter parser is minimal. Simple one-line values only; YAML folded/literal descriptions can surface as > or >-.

• Catalog is cached until server restart; newly installed skills need a restart (or CLI re-run) to appear.

• JSON-RPC handling is minimal. Notifications, invalid arguments, and missing skills need stronger protocol handling; missing skills return text without isError.

• No measured end-to-end token-savings claim. Small schemas do not by themselves prove lower total task cost.

• serverInfo reports legacy version 1.0.0; the package starts at 0.1.0 (kept for compatibility review).

Verify

PYTHONPATH=src python3 -m unittest discover -s tests -v

Roadmap

1. Correct YAML frontmatter parsing (folded/literal blocks, quoted colons) — highest priority

2. Protocol hardening: argument validation, isError on failures, notification handling

3. Catalog refresh + configurable roots

4. Retrieval-quality measurement (zh/en) before considering an embedding dependency

5. Optional: adopt OpenSkills / Vercel skills for install/update/distribution instead of building our own

See docs/comparison.md for the full alternatives analysis and proposed improvements.

License

MIT — see LICENSE.