f744b797ef
* Update create-agent-skills to match 2026 official docs, add /triage-prs command - Rewrite SKILL.md to document that commands and skills are now merged - Add new frontmatter fields: disable-model-invocation, user-invocable, context, agent - Add invocation control table and dynamic context injection docs - Fix skill-structure.md: was incorrectly recommending XML tags over markdown headings - Update official-spec.md with complete 2026 specification - Add local /triage-prs command for PR triage workflow - Add PR triage plan document Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * [2.31.0] Reduce context token usage by 79%, include recent community contributions The plugin was consuming 316% of Claude Code's description character budget (~50,500 chars vs 16,000 limit), causing components to be silently excluded. Now at 65% (~10,400 chars) with all components visible. Changes: - Trim all 29 agent descriptions (move examples to body) - Add disable-model-invocation to 18 manual commands - Add disable-model-invocation to 6 manual skills - Include recent community contributions in changelog - Fix component counts (29 agents, 24 commands, 18 skills) Contributors: @trevin, @terryli, @robertomello, @zacwilliams, @aarnikoskela, @samxie, @davidalley Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Fix: keep disable-model-invocation off commands called by /lfg, rename xcode-test - Remove disable-model-invocation from test-browser, feature-video, resolve_todo_parallel — these are called programmatically by /lfg and /slfg - Rename xcode-test to test-xcode to match test-browser naming convention Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Fix: keep git-worktree skill auto-invocable (used by /workflows:work) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * feat(converter): support disable-model-invocation frontmatter Parse disable-model-invocation from command and skill frontmatter. Commands/skills with this flag are excluded from OpenCode command maps and Codex prompt/skill generation, matching Claude Code behavior where these components are user-only invocable. Bump converter version to 0.3.0. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
4.9 KiB
4.9 KiB
Official Skill Specification (2026)
Source: code.claude.com/docs/en/skills
Commands and Skills Are Merged
Custom slash commands have been merged into skills. A file at .claude/commands/review.md and a skill at .claude/skills/review/SKILL.md both create /review and work the same way. Existing .claude/commands/ files keep working. Skills add optional features: a directory for supporting files, frontmatter to control invocation, and automatic context loading.
If a skill and a command share the same name, the skill takes precedence.
SKILL.md File Structure
Every skill requires a SKILL.md file with YAML frontmatter followed by standard markdown instructions.
---
name: your-skill-name
description: What it does and when to use it
---
# Your Skill Name
## Instructions
Clear, step-by-step guidance.
## Examples
Concrete examples of using this skill.
Complete Frontmatter Reference
All fields are optional. Only description is recommended.
| Field | Required | Description |
|---|---|---|
name |
No | Display name. Lowercase letters, numbers, hyphens only (max 64 chars). Defaults to directory name if omitted. |
description |
Recommended | What it does AND when to use it (max 1024 chars). Claude uses this to decide when to apply the skill. |
argument-hint |
No | Hint shown during autocomplete. Example: [issue-number] or [filename] [format] |
disable-model-invocation |
No | Set true to prevent Claude from auto-loading. Use for manual workflows. Default: false |
user-invocable |
No | Set false to hide from / menu. Use for background knowledge. Default: true |
allowed-tools |
No | Tools Claude can use without permission prompts. Example: Read, Bash(git *) |
model |
No | Model to use: haiku, sonnet, or opus |
context |
No | Set fork to run in isolated subagent context |
agent |
No | Subagent type when context: fork. Options: Explore, Plan, general-purpose, or custom agent name |
hooks |
No | Hooks scoped to this skill's lifecycle |
Invocation Control
| Frontmatter | User can invoke | Claude can invoke | When loaded into context |
|---|---|---|---|
| (default) | Yes | Yes | Description always in context, full skill loads when invoked |
disable-model-invocation: true |
Yes | No | Description not in context, full skill loads when you invoke |
user-invocable: false |
No | Yes | Description always in context, full skill loads when invoked |
Skill Locations & Priority
Enterprise (highest priority) → Personal → Project → Plugin (lowest priority)
| Type | Path | Applies to |
|---|---|---|
| Enterprise | See managed settings | All users in organization |
| Personal | ~/.claude/skills/<name>/SKILL.md |
You, across all projects |
| Project | .claude/skills/<name>/SKILL.md |
Anyone working in repository |
| Plugin | <plugin>/skills/<name>/SKILL.md |
Where plugin is enabled |
Plugin skills use a plugin-name:skill-name namespace, so they cannot conflict with other levels.
How Skills Work
- Discovery: Claude loads only name and description at startup (2% of context window budget)
- Activation: When your request matches a skill's description, Claude loads the full content
- Execution: Claude follows the skill's instructions
String Substitutions
| Variable | Description |
|---|---|
$ARGUMENTS |
All arguments passed when invoking |
$ARGUMENTS[N] |
Specific argument by 0-based index |
$N |
Shorthand for $ARGUMENTS[N] |
${CLAUDE_SESSION_ID} |
Current session ID |
Dynamic Context Injection
The !`command` syntax runs shell commands before content is sent to Claude:
## Context
- Current branch: !`git branch --show-current`
- PR diff: !`gh pr diff`
Commands execute immediately and their output replaces the placeholder. Claude only sees the final result.
Progressive Disclosure
my-skill/
├── SKILL.md # Entry point (required)
├── reference.md # Detailed docs (loaded when needed)
├── examples.md # Usage examples (loaded when needed)
└── scripts/
└── helper.py # Utility script (executed, not loaded)
Keep SKILL.md under 500 lines. Link to supporting files:
For API details, see [reference.md](reference.md).
Running in a Subagent
Add context: fork to run in isolation:
---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---
Research $ARGUMENTS thoroughly...
The skill content becomes the subagent's prompt. It won't have access to conversation history.
Distribution
- Project skills: Commit
.claude/skills/to version control - Plugins: Add
skills/directory to plugin - Enterprise: Deploy organization-wide through managed settings