How-to: add a skill

Install a skill from the npm marketplace, place it in the right area folder, register it, and validate.

Steps

# 1. Install via marketplace
npx skills add <owner/repo@skill> -y

# 2. Move from default install location into the correct area folder
mv .agents/skills/<name> <area>/.agents/skills/<name>

# 3. Sync registry _meta
python scripts/sync_registry.py

# 4. Regenerate full inventory
python scripts/gen_registry_full.py

# 5. Validate
make audit

Promoting to a curated tier

If the skill has ≥100 installs and you want it tiered, add an entry under the matching section in docs/reference/registries/_skills-registry.yaml:

silver:
  - id: <name>
    npm_package: <owner/repo>
    primary_area: <area>
    installs: 1234
    tier: silver
    last_verified: 2026-05-24
    status: active
    quality_score: 0.72
    source_org: <owner>

Then re-run python scripts/sync_registry.py and make audit.

Tier thresholds

Tier	Installs	Notes
Platinum	≥100K OR official	manually curated
Gold	10K–100K	high-confidence
Silver	1K–10K	provenance-validated
Bronze	100–1K	provenance-validated
Experimental	<100	not curated

Common audit failures

Error	Fix
curated_orphan	Skill is in registry but no SKILL.md on disk. Re-install or remove the entry.
unknown_area	primary_area points to a folder that doesn't exist. Create the folder under root with .agents/skills/.
unknown_sub_area	Add the sub_area to docs/reference/registries/CAPABILITY-GRAPH.yaml under the matching top-level area first.
tier_mismatch	Installs don't match the tier threshold. Either re-classify or pass official: true.