antoskill

A package manager for Agent Skills.

Discover the right skills for your project, vet them with a safety scan, and pin them across Claude Code and Codex — with you in the loop for every install.

English · 简体中文

AntoSkills is an MCP server that brings package-manager discipline to Agent Skills. You ask your agent "recommend skills for this project"; it fingerprints your stack, ranks high-quality skills from a curated index, shows you each one alongside a static safety scan, and — only after you approve — installs them at a pinned commit into both .claude/skills/ and .agents/skills/.

detect stack  →  recommend matches  →  preview + safety scan  →  you approve  →  pinned install

Because Agent Skills are a shared open standard, one SKILL.md runs in both Claude Code and Codex. AntoSkills handles the parts the standard leaves out: finding the right skills, vetting them, and installing them reproducibly across tools.

Contents

• Why AntoSkills
• A typical session
• Highlights
• Safety model
• Install
• Usage & MCP tools
• Configuration
• How it works
• Team workflow
• Development
• Roadmap
• Contributing

Why AntoSkills

Skills are powerful but tedious to manage by hand: you hunt across repos, you can't tell which ones are any good, each tool installs them to a different path, and nothing records what you actually installed. AntoSkills turns that into a short conversation — and pins the result, so your teammates and CI get byte-for-byte the same skills.

Without AntoSkills	With AntoSkills
Hunt across GitHub repos by hand	Ranked, project-matched recommendations
Guess whether a skill is safe to run	Static safety scan before every install
Copy files into each tool's path manually	One install → Claude Code and Codex
"Works on my machine" skill drift	skills.lock pins an immutable SHA + hash

A typical session

"Recommend skills for this project, then install the ones for testing."

You ▸ recommend skills for this project

  Project tags: typescript, react, vitest

  • anthropic-frontend-design (score 88) — Produce distinctive, production-grade frontend UI
      matched: react, frontend; repo: anthropics/skills
  • cypress-author (score 81) — Author Cypress end-to-end tests (official Cypress AI toolkit)
      matched: testing, e2e; repo: cypress-io/ai-toolkit
  • api-test-suite-builder (score 74) — Generate comprehensive API test suites
      matched: testing, api; repo: alirezarezvani/claude-skills

You ▸ preview cypress-author

  cypress-author @ a1b2c3d4e5 (cypress-io/ai-toolkit)
  SKILL.md: Cypress Author — Author Cypress end-to-end tests
  Files (3): SKILL.md, scripts/scaffold.md, references/patterns.md
  Risk score: 0 — no red flags

You ▸ install it

  Installed into /your/project:
  ✓ cypress-author @ a1b2c3d4e5 → [claude,codex] (junction)

Read-only steps (detect, recommend, preview) need no approval; the install is your gate.

Highlights

• Project-matched — fingerprints your languages/frameworks and ranks skills by relevance plus quality signals (stars, recency, maintenance).
• Pinned & reproducible — every install records an immutable commit SHA + content hash in skills.lock; sync rebuilds the exact same skills for teammates and CI.
• Vetted before install — a static safety scan flags executable payloads, network egress, shell-outs, secret access, install hooks, and obfuscation; high-risk skills are refused unless you explicitly acknowledge them.
• Cross-tool — installs into both Claude Code (.claude/skills/) and Codex (.agents/skills/) from a single source of truth.
• Content-addressed store — each skill version is stored once in ~/.antoskill/store/, deduped, integrity-checked, and usable offline if upstream disappears.
• Token-friendly — a large candidate index, but a small installed set: the per-project install count is capped so the agent's skill list never bloats its context.

Safety model

Skills can ship executable scripts, so AntoSkills treats every install like a dependency you'd add to a lockfile:

• A static safety scan runs before install and is surfaced to you — executable payloads, network egress, shell-outs, secret/env access, install hooks, obfuscation, and overly broad permissions. High-risk skills are refused unless you explicitly acknowledge the risk.
• Installs are pinned by SHA + content hash and re-verified on every sync.
• The source is allow-listed through the index — the agent can only install indexed ids, never an arbitrary URL.

The scan is heuristic: it informs your decision, it doesn't replace it. Review before you approve.

Install

Requires Node ≥ 20. For a full walkthrough — GitHub tokens, every config option, team/CI setup, and troubleshooting — see the Setup & Usage guide.

[!IMPORTANT] Not yet published to npm. The npx -y antoskill snippets below are the documented post-publish path — they will fail until the package is published. Until then, install from source (full details in Setup guide §5):

git clone https://github.com/YforC/AntoSkills.git && cd AntoSkills
npm install && npm run build
claude mcp add antoskill -- node ./dist/index.js   # Codex: point config.toml at dist/index.js

Claude Code

claude mcp add antoskill -- npx -y antoskill

Or in .mcp.json:

{
  "mcpServers": {
    "antoskill": { "command": "npx", "args": ["-y", "antoskill"] }
  }
}

Codex

In ~/.codex/config.toml:

[mcp_servers.antoskill]
command = "npx"
args = ["-y", "antoskill"]

Tip: set a GITHUB_TOKEN env var to avoid GitHub API rate limits when fetching skills.

Usage & MCP tools

Just talk to your agent in plain language:

"Recommend skills for this project, then install the ones for testing."

Under the hood it exposes these MCP tools. Read tools are safe to auto-approve; the write tools are your confirmation gate.

Tool	Kind	What it does
detect_project	read	Fingerprints languages/frameworks in the project
recommend_skills	read	Ranks matching skills with quality signals + why they matched
preview_skill	read	Shows a skill's SKILL.md, files, and safety scan at a pinned SHA
list_installed	read	Lists installed skills from skills.lock
doctor	read	Diagnoses targets, store, broken links, lock drift
list_profiles	read	Lists defined skill profiles and which is active
install_skills	write	Pins + installs selected skills (refuses high-risk unless acknowledged)
remove_skill	write	Removes a skill and its links
sync	write	Rebuilds links from skills.lock (reproducible / offline)
update_skill	write	Moves a skill to a newer SHA after a fresh scan
define_profile	write	Creates/replaces a named group of skills
activate_profile	write	Switches the installed set to a profile (installs its skills, removes the rest)

Configuration

Env var	Purpose
GITHUB_TOKEN	Raise GitHub API rate limits for fetching skills (and the index, if hosted on GitHub)
ANTOSKILL_INDEX_URL	Use an online/custom skill index instead of the bundled one
ANTOSKILL_HOME	Override the store location (default ~/.antoskill)
ANTOSKILL_MAX_INSTALL	Cap how many skills may be installed per project (default 8 — a token-budget guard)

Online index

The skill index ships bundled in the package, but you can point AntoSkills at an online index so it always reflects the latest curated list without reinstalling. Host skills.json anywhere that serves raw JSON — for example this repo's own file:

ANTOSKILL_INDEX_URL=https://raw.githubusercontent.com/YforC/AntoSkills/main/index/skills.json

Set it when registering the server, e.g. for Claude Code:

claude mcp add antoskill \
  -e ANTOSKILL_INDEX_URL=https://raw.githubusercontent.com/YforC/AntoSkills/main/index/skills.json \
  -- npx -y antoskill

Now updating the index is just a git push — every user picks up the new list on their next recommend_skills call. (Install still pins each skill to an immutable commit SHA, so a changing index never changes what's already installed.)

Why the installed set stays small

Claude Code and Codex load every installed skill's name + description into the agent's context at startup, and that budget is capped (~2% of context / 8000 chars in Codex). Past it, descriptions get truncated and skills get dropped. So AntoSkills' model is a large candidate index but a small installed set: install_skills caps the per-project count (ANTOSKILL_MAX_INSTALL, default 8), and the big index lives behind the MCP tools — never sitting in the agent's context.

Profiles — switch between groups instead of installing everything

When you want many skills available but not all loaded at once, define profiles — named groups you switch between. Activating a profile installs its skills and removes the managed skills not in it, so the project always holds just one group and the agent only loads that group.

> "Define a frontend profile with web-artifacts-builder, frontend-design and cypress-author."
> "Now activate the backend profile."   # installs that group, removes the rest

Definitions live in a project-level antoskill.profiles.json (commit it to share with a team):

{
  "active": "frontend",
  "profiles": {
    "frontend": ["anthropic-frontend-design", "anthropic-web-artifacts-builder", "cypress-author"],
    "backend":  ["database-schema-designer", "api-test-suite-builder", "n8n-code-python"]
  }
}

Tools: list_profiles (read), define_profile (write), activate_profile (write).

How it works

   ╭────────────────────────────────────────────────────────────────────────────╮
   │   index/skills.json   ·   curated pointers: repo · path · tags · signals     │
   ╰────────────────────────────────────────────────────────────────────────────╯
                                          │
  ═══ DISCOVERY · live ═══════════════════╪═══════════════════════════════════════
                                          ▼
     detect_project  ──►  recommend_skills  ──►  preview_skill
       fingerprint          rank + score           resolve ref → SHA  ·  safety scan
                                          │
                                  ╭───────┴────────╮
                                  │   you approve   │  ◄── human gate
                                  ╰───────┬────────╯
                                          ▼
  ═══ INSTALL · pinned ═══════════════════╪═══════════════════════════════════════
                                          ▼
                                   install_skills
                                          │
              ╭───────────────────────────┼───────────────────────────╮
              ▼                           ▼                           ▼
        skills.lock           ~/.antoskill/store/<hash>       .claude/skills/<name>
        pinned SHA + hash      content-addressed, shared       .agents/skills/<name>
        commit to git          offline-resilient               junction · symlink · copy

• Discovery is live, install is pinned. Recommendations reflect the latest upstream; install resolves the ref to an immutable commit SHA and records it.
• The store doubles as offline resilience. If an upstream repo disappears, sync still rebuilds from the pinned SHA already in your store.
• Links, not copies (when possible). Directory junctions on Windows (no admin needed), symlinks elsewhere, and a copy fallback when linking isn't permitted.

The codebase is a pure core library (src/core/) with a thin MCP adapter (src/mcp/), so a standalone CLI can reuse the same logic later.

Team workflow

Commit skills.lock. Teammates (or CI) run sync to materialize the exact same skills. The content-addressed store and per-project links are regenerated on demand and stay out of git.

Development

npm install
npm run build
npm test          # unit tests
npm run smoke     # offline full-lifecycle + MCP handshake checks
npm run dev       # run the server over stdio for local testing

Roadmap

• Hosted index with an automated quality-signal crawler
• Publisher signing / verification
• A standalone CLI (the core is already a pure library)
• Per-repo diversity in recommendations
• AST-based scanning

Contributing

Contributions welcome — new high-quality skills for the index, better tag inference, additional target tools. Start with the contributing guide; to submit a skill to the index, see docs/INDEX.md. Or just open an issue or PR.

License

MIT