ACTIVATE when creating SKILL.md files, writing frontmatter (name/description/version), structuring skill packages for discovery, or publishing to the Agent Skills ecosystem. ACTIVATE for 'SKILL.md', 'npx skills', 'skillkit', 'skill frontmatter', 'skill discovery'. Covers: SKILL.md frontmatter schema (name constraints, description as routing mechanism), progressive disclosure (metadata/body/references), directory structure, discovery mechanics (npx skills add, skills.sh, Claude Code), installation scopes, validation checklist. DO NOT use for: Claude plugin structure (see claude-plugin-conventions), general markdown writing.
From toolingnpx claudepluginhub fabiensalles/claude-marketplace --plugin toolingThis skill uses the workspace's default tool permissions.
references/skills-ecosystem-reference.mdGuides Next.js Cache Components and Partial Prerendering (PPR) with cacheComponents enabled. Implements 'use cache', cacheLife(), cacheTag(), revalidateTag(), static/dynamic optimization, and cache debugging.
Migrates code, prompts, and API calls from Claude Sonnet 4.0/4.5 or Opus 4.1 to Opus 4.5, updating model strings on Anthropic, AWS, GCP, Azure platforms.
Analyzes BMad project state from catalog CSV, configs, artifacts, and query to recommend next skills or answer questions. Useful for help requests, 'what next', or starting BMad.
Best practices for creating skills compatible with npx skills add, skills.sh leaderboard, and skillkit, based on the Agent Skills specification and ecosystem analysis.
| Field | Required | Constraints |
|---|---|---|
name | Yes | Max 64 chars, [a-z0-9-] only, no leading/trailing/consecutive hyphens, must match parent directory name |
description | Yes | Max 1024 chars, no angle brackets, single-line string |
license | No | SPDX identifier (MIT, Apache-2.0) |
compatibility | No | Max 500 chars, platform/dependency requirements |
metadata | No | Arbitrary string->string key-value map |
allowed-tools | No | Space-delimited pre-approved tools |
| Field | Description |
|---|---|
disable-model-invocation | true prevents Claude from auto-loading (manual /name only) |
user-invocable | false hides from / menu |
context | fork to run in isolated subagent |
agent | Subagent type for context: fork (Explore, Plan, general-purpose) |
model | Model override when active |
php-8.3/ <- directory name
└── SKILL.md
name: php-8.3 <- must match exactly
The description is the primary routing mechanism for both skills.sh indexing and Claude activation. Write it as activation triggers.
Rules:
< or >)skill-name/
├── SKILL.md # Core instructions (<2000 words)
├── references/ # Detailed docs (loaded on demand)
│ └── patterns.md
└── examples/ # Working examples
└── sample.sh
Skills use 3-level loading for context efficiency:
Keep SKILL.md under 2000 words. Move detailed content to references/.
npx skills add)The CLI searches these directories in order: skills/, .claude/skills/, .agents/skills/, and 30+ agent-specific paths.
Skills appear automatically when users install them via npx skills add. No registration step needed.
| Scope | Path | Command |
|---|---|---|
| Project | .claude/skills/ | npx skills add repo |
| Personal | ~/.claude/skills/ | npx skills add repo --global |
| Plugin | <plugin>/skills/ | claude plugin install |
When looking up CLI commands, environment variables, SkillKit compatibility, or the validation checklist, read
references/skills-ecosystem-reference.mdfor the complete reference.
When writing descriptions or body text, read
references/skills-ecosystem-reference.mdfor good/bad examples and writing style rules.