From tooling
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.
How this skill is triggered — by the user, by Claude, or both
Slash command
/tooling:npx-skills-conventionsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Best practices for creating skills compatible with `npx skills add`, skills.sh leaderboard, and skillkit, based on the Agent Skills specification and ecosystem analysis.
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.
npx claudepluginhub fabiensalles/claude-marketplace --plugin toolingReference for Agent Skills Open Standard. Guides authoring portable skills for Claude Code, Cursor, VS Code, and 20+ AI agents. Covers frontmatter schema, naming rules, directory structure, validation.
Guides skill file creation with naming conventions, directory structures (flat/nested/progressive), frontmatter fields, and invocation controls for Claude Code plugins and slash commands.
Guides authoring and validating Claude Code skills: metadata optimization, lean workflows, progressive disclosure, references, skillgrade evals.