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>
This commit is contained in:
Kieran Klaassen
193
.claude/commands/triage-prs.md
Normal file
193
.claude/commands/triage-prs.md
Normal file
@@ -0,0 +1,193 @@
|
||||
---
|
||||
name: triage-prs
|
||||
description: Triage all open PRs with parallel agents, label, group, and review one-by-one
|
||||
argument-hint: "[optional: repo owner/name or GitHub PRs URL]"
|
||||
disable-model-invocation: true
|
||||
allowed-tools: Bash(gh *), Bash(git log *)
|
||||
---
|
||||
|
||||
# Triage Open Pull Requests
|
||||
|
||||
Review, label, and act on all open PRs for a repository using parallel review agents. Produces a grouped triage report, applies labels, cross-references with issues, and walks through each PR for merge/comment decisions.
|
||||
|
||||
## Step 0: Detect Repository
|
||||
|
||||
Detect repo context:
|
||||
- Current repo: !`gh repo view --json nameWithOwner -q .nameWithOwner 2>/dev/null || echo "no repo detected"`
|
||||
- Current branch: !`git branch --show-current 2>/dev/null`
|
||||
|
||||
If `$ARGUMENTS` contains a GitHub URL or `owner/repo`, use that instead. Confirm the repo with the user if ambiguous.
|
||||
|
||||
## Step 1: Gather Context (Parallel)
|
||||
|
||||
Run these in parallel:
|
||||
|
||||
1. **List all open PRs:**
|
||||
```bash
|
||||
gh pr list --repo OWNER/REPO --state open --limit 50
|
||||
```
|
||||
|
||||
2. **List all open issues:**
|
||||
```bash
|
||||
gh issue list --repo OWNER/REPO --state open --limit 50
|
||||
```
|
||||
|
||||
3. **List existing labels:**
|
||||
```bash
|
||||
gh label list --repo OWNER/REPO --limit 50
|
||||
```
|
||||
|
||||
4. **Check recent merges** (to detect duplicate/superseded PRs):
|
||||
```bash
|
||||
git log --oneline -20 main
|
||||
```
|
||||
|
||||
## Step 2: Batch PRs by Theme
|
||||
|
||||
Group PRs into review batches of 4-6 based on apparent type:
|
||||
|
||||
- **Bug fixes** - titles with `fix`, `bug`, error descriptions
|
||||
- **Features** - titles with `feat`, `add`, new functionality
|
||||
- **Documentation** - titles with `docs`, `readme`, terminology
|
||||
- **Configuration/Setup** - titles with `config`, `setup`, `install`
|
||||
- **Stale/Old** - PRs older than 30 days
|
||||
|
||||
## Step 3: Parallel Review (Team of Agents)
|
||||
|
||||
Spawn one review agent per batch using the Task tool. Each agent should:
|
||||
|
||||
For each PR in their batch:
|
||||
1. Run `gh pr view --repo OWNER/REPO <number> --json title,body,files,additions,deletions,author,createdAt`
|
||||
2. Run `gh pr diff --repo OWNER/REPO <number>` (pipe to `head -200` for large diffs)
|
||||
3. Determine:
|
||||
- **Description:** 1-2 sentence summary of the change
|
||||
- **Label:** Which existing repo label fits best
|
||||
- **Action:** merge / request changes / close / needs discussion
|
||||
- **Related PRs:** Any PRs in this or other batches that touch the same files or feature
|
||||
- **Quality notes:** Code quality, test coverage, staleness concerns
|
||||
|
||||
Instruct each agent to:
|
||||
- Flag PRs that touch the same files (potential merge conflicts)
|
||||
- Flag PRs that duplicate recently merged work
|
||||
- Flag PRs that are part of a group solving the same problem differently
|
||||
- Report findings as a markdown table
|
||||
- Send findings back via message when done
|
||||
|
||||
## Step 4: Cross-Reference Issues
|
||||
|
||||
After all agents report, match issues to PRs:
|
||||
|
||||
- Check if any PR title/body mentions `Fixes #X` or `Closes #X`
|
||||
- Check if any issue title matches a PR's topic
|
||||
- Look for duplicate issues (same bug reported twice)
|
||||
|
||||
Build a mapping table:
|
||||
```
|
||||
| Issue | PR | Relationship |
|
||||
|-------|-----|--------------|
|
||||
| #158 | #159 | PR fixes issue |
|
||||
```
|
||||
|
||||
## Step 5: Identify Themes
|
||||
|
||||
Group all issues into themes (3-6 themes):
|
||||
- Count issues per theme
|
||||
- Note which themes have PRs addressing them and which don't
|
||||
- Flag themes with competing/overlapping PRs
|
||||
|
||||
## Step 6: Compile Triage Report
|
||||
|
||||
Present a single report with:
|
||||
|
||||
1. **Summary stats:** X open PRs, Y open issues, Z themes
|
||||
2. **PR groups** with recommended actions:
|
||||
- Group name and related PRs
|
||||
- Per-PR: #, title, author, description, label, action
|
||||
3. **Issue-to-PR mapping**
|
||||
4. **Themes across issues**
|
||||
5. **Suggested cleanup:** spam issues, duplicates, stale items
|
||||
|
||||
## Step 7: Apply Labels
|
||||
|
||||
After presenting the report, ask user:
|
||||
|
||||
> "Apply these labels to all PRs on GitHub?"
|
||||
|
||||
If yes, run `gh pr edit --repo OWNER/REPO <number> --add-label "<label>"` for each PR.
|
||||
|
||||
## Step 8: One-by-One Review
|
||||
|
||||
Use **AskUserQuestion** to ask:
|
||||
|
||||
> "Ready to walk through PRs one-by-one for merge/comment decisions?"
|
||||
|
||||
Then for each PR, ordered by priority (bug fixes first, then docs, then features, then stale):
|
||||
|
||||
### Show the PR:
|
||||
|
||||
```
|
||||
### PR #<number> - <title>
|
||||
Author: <author> | Files: <count> | +<additions>/-<deletions> | <age>
|
||||
Label: <label>
|
||||
|
||||
<1-2 sentence description>
|
||||
|
||||
Fixes: <linked issues if any>
|
||||
Related: <related PRs if any>
|
||||
```
|
||||
|
||||
Show the diff (trimmed to key changes if large).
|
||||
|
||||
### Ask for decision:
|
||||
|
||||
Use **AskUserQuestion**:
|
||||
- **Merge** - Merge this PR now
|
||||
- **Comment & skip** - Leave a comment explaining why not merging, keep open
|
||||
- **Close** - Close with a comment
|
||||
- **Skip** - Move to next without action
|
||||
|
||||
### Execute decision:
|
||||
|
||||
- **Merge:** `gh pr merge --repo OWNER/REPO <number> --squash`
|
||||
- If PR fixes an issue, close the issue too
|
||||
- **Comment & skip:** `gh pr comment --repo OWNER/REPO <number> --body "<comment>"`
|
||||
- Ask user what to say, or generate a grateful + specific comment
|
||||
- **Close:** `gh pr close --repo OWNER/REPO <number> --comment "<reason>"`
|
||||
- **Skip:** Move on
|
||||
|
||||
## Step 9: Post-Merge Cleanup
|
||||
|
||||
After all PRs are reviewed:
|
||||
|
||||
1. **Close resolved issues** that were fixed by merged PRs
|
||||
2. **Close spam/off-topic issues** (confirm with user first)
|
||||
3. **Summary of actions taken:**
|
||||
```
|
||||
## Triage Complete
|
||||
|
||||
Merged: X PRs
|
||||
Commented: Y PRs
|
||||
Closed: Z PRs
|
||||
Skipped: W PRs
|
||||
|
||||
Issues closed: A
|
||||
Labels applied: B
|
||||
```
|
||||
|
||||
## Step 10: Post-Triage Options
|
||||
|
||||
Use **AskUserQuestion**:
|
||||
|
||||
1. **Run `/release-docs`** - Update documentation site if components changed
|
||||
2. **Run `/changelog`** - Generate changelog for merged PRs
|
||||
3. **Commit any local changes** - If version bumps needed
|
||||
4. **Done** - Wrap up
|
||||
|
||||
## Important Notes
|
||||
|
||||
- **DO NOT merge without user approval** for each PR
|
||||
- **DO NOT force push or destructive actions**
|
||||
- Comments on declined PRs should be grateful and constructive
|
||||
- When PRs conflict with each other, note this and suggest merge order
|
||||
- When multiple PRs solve the same problem differently, flag for user to pick one
|
||||
- Use Haiku model for review agents to save cost (they're doing read-only analysis)
|
||||
128
docs/plans/2026-02-08-feat-pr-triage-and-merge-plan.md
Normal file
128
docs/plans/2026-02-08-feat-pr-triage-and-merge-plan.md
Normal file
@@ -0,0 +1,128 @@
|
||||
---
|
||||
title: PR Triage, Review & Merge
|
||||
type: feat
|
||||
date: 2026-02-08
|
||||
---
|
||||
|
||||
# PR Triage, Review & Merge
|
||||
|
||||
## Overview
|
||||
|
||||
Review all 17 open PRs one-by-one. Merge the ones that look good, leave constructive comments on the ones we won't take (keeping them open for contributors to address). Close duplicates/spam.
|
||||
|
||||
## Approach
|
||||
|
||||
Show the diff for each PR, get a go/no-go, then either merge or comment. PRs are ordered by priority group.
|
||||
|
||||
## Group 1: Bug Fixes (high confidence merges)
|
||||
|
||||
### PR #159 - fix(git-worktree): detect worktrees where .git is a file
|
||||
- **Author:** dalley | **Files:** 1 | **+2/-2**
|
||||
- **What:** Changes `-d` to `-e` check in `worktree-manager.sh` so `list` and `cleanup` detect worktrees (`.git` is a file in worktrees, not a dir)
|
||||
- **Fixes:** Issue #158
|
||||
- **Action:** Review diff → merge
|
||||
|
||||
### PR #144 - Remove confirmation prompt when creating git worktrees
|
||||
- **Author:** XSAM | **Files:** 1 | **+0/-8**
|
||||
- **What:** Removes interactive `read -r` confirmation that breaks Claude's ability to create worktrees
|
||||
- **Related:** Same file as #159 (merge #159 first)
|
||||
- **Action:** Review diff → merge
|
||||
|
||||
### PR #150 - fix(compound): prevent subagents from writing intermediary files
|
||||
- **Author:** tmchow | **Files:** 1 | **+64/-27**
|
||||
- **What:** Restructures `/workflows:compound` into 2-phase orchestration to prevent subagents from writing temp files
|
||||
- **Action:** Review diff → merge
|
||||
|
||||
### PR #148 - Fix: resolve_pr_parallel uses non-existent scripts
|
||||
- **Author:** ajrobertsonio | **Files:** 1 | **+20/-7**
|
||||
- **What:** Replaces references to non-existent `bin/get-pr-comments` with standard `gh` CLI commands
|
||||
- **Fixes:** Issues #147, #54
|
||||
- **Action:** Review diff → merge
|
||||
|
||||
## Group 2: Documentation (clean, low-risk)
|
||||
|
||||
### PR #133 - Fix terminology: third person → passive voice
|
||||
- **Author:** FauxReal9999 | **Files:** 13 | docs-only
|
||||
- **What:** Corrects "third person" to "passive voice" across docs (accurate fix)
|
||||
- **Action:** Review diff → merge
|
||||
|
||||
### PR #108 - Note new repository URL
|
||||
- **Author:** akx | **Files:** 5 | docs-only
|
||||
- **What:** Updates URLs from `kieranklaassen/compound-engineering-plugin` to `EveryInc/compound-engineering-plugin`
|
||||
- **Action:** Review diff → merge
|
||||
|
||||
### PR #113 - docs: add brainstorm command to workflow documentation
|
||||
- **Author:** tmchow | docs-only
|
||||
- **What:** Adds brainstorming skill and learnings-researcher agent to README, fixes component counts
|
||||
- **Action:** Review diff → merge
|
||||
|
||||
### PR #80 - docs: Add LSP prioritization guidance
|
||||
- **Author:** kevinold | **Files:** 1 | docs-only
|
||||
- **What:** Adds docs showing users how to customize agent behavior via project CLAUDE.md to prioritize LSP
|
||||
- **Action:** Review diff → merge
|
||||
|
||||
## Group 3: Enhancements (likely merge)
|
||||
|
||||
### PR #119 - fix: backup existing config files before overwriting
|
||||
- **Author:** jzw | **Files:** 5 | **+90/-3** | has tests
|
||||
- **What:** Adds `backupFile()` utility to create timestamped backups before overwriting Codex/OpenCode configs
|
||||
- **Fixes:** Issue #125
|
||||
- **Action:** Review diff → merge
|
||||
|
||||
### PR #112 - feat(skills): add document-review skill
|
||||
- **Author:** tmchow | enhancement
|
||||
- **What:** Adds document-review skill for brainstorm/plan refinement, renames `/plan_review` → `/technical_review`
|
||||
- **Note:** Breaking rename - needs review
|
||||
- **Action:** Review diff → decide
|
||||
|
||||
## Group 4: Needs Discussion (comment and leave open)
|
||||
|
||||
### PR #157 - Rewrite workflows:review with context-managed map-reduce
|
||||
- **Author:** Drewx-Design | large rewrite
|
||||
- **What:** Complete rewrite of review command with file-based map-reduce architecture
|
||||
- **Comment:** Acknowledge quality, note it's a big change that needs dedicated review session
|
||||
|
||||
### PR #131 - feat: add vmark-mcp plugin
|
||||
- **Author:** xiaolai | new plugin
|
||||
- **What:** Adds entirely new VMark markdown editor plugin to marketplace
|
||||
- **Comment:** Ask for more context on fit with marketplace scope
|
||||
|
||||
### PR #124 - feat(commands): add /compound-engineering-setup
|
||||
- **Author:** internal | config
|
||||
- **What:** Interactive setup command for configuring review agents per project
|
||||
- **Comment:** Note overlap with #103, needs unified config strategy
|
||||
|
||||
### PR #123 - feat: Add sync command for Claude Code personal config
|
||||
- **Author:** terry-li-hm | config
|
||||
- **What:** Sync personal Claude config across machines/editors
|
||||
- **Comment:** Note overlap with #124 and #103, needs unified config strategy
|
||||
|
||||
### PR #103 - Add /compound:configure with persistent user preferences
|
||||
- **Author:** aviflombaum | **+36,866** lines
|
||||
- **What:** Massive architectural change adding persistent config with build system
|
||||
- **Comment:** Too large, suggest breaking into smaller PRs
|
||||
|
||||
## Group 5: Close
|
||||
|
||||
### PR #122 - [EXPERIMENTAL] add /slfg and /swarm-status
|
||||
- **Label:** duplicate
|
||||
- **What:** Already merged in v2.30.0 (commit e4ff6a8)
|
||||
- **Action:** Comment explaining it's been superseded, close
|
||||
|
||||
### PR #68 - Improve all 13 skills to 90%+ grades
|
||||
- **Label:** wontfix
|
||||
- **What:** Massive stale PR (Jan 6), based on 13 skills when we now have 16+
|
||||
- **Action:** Comment thanking contributor, suggest fresh PR against current main, close
|
||||
|
||||
## Post-Merge Cleanup
|
||||
|
||||
After merging:
|
||||
- [ ] Close issues fixed by merged PRs (#158, #147, #54, #125)
|
||||
- [ ] Close spam issues (#98, #56)
|
||||
- [ ] Run `/release-docs` to update documentation site with new component counts
|
||||
- [ ] Bump version in plugin.json if needed
|
||||
|
||||
## References
|
||||
|
||||
- PR list: https://github.com/EveryInc/compound-engineering-plugin/pulls
|
||||
- Issues: https://github.com/EveryInc/compound-engineering-plugin/issues
|
||||
@@ -1,21 +1,35 @@
|
||||
---
|
||||
name: creating-agent-skills
|
||||
description: Expert guidance for creating, writing, and refining Claude Code Skills. Use when working with SKILL.md files, authoring new skills, improving existing skills, or understanding skill structure and best practices.
|
||||
name: create-agent-skills
|
||||
description: Expert guidance for creating Claude Code skills and slash commands. This skill should be used when working with SKILL.md files, authoring new skills, improving existing skills, creating slash commands, or understanding skill structure and best practices.
|
||||
---
|
||||
|
||||
# Creating Agent Skills
|
||||
# Creating Skills & Commands
|
||||
|
||||
This skill teaches how to create effective Claude Code Skills following Anthropic's official specification.
|
||||
This skill teaches how to create effective Claude Code skills following the official specification from [code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills).
|
||||
|
||||
## Core Principles
|
||||
## Commands and Skills Are Now The Same Thing
|
||||
|
||||
### 1. Skills Are Prompts
|
||||
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.
|
||||
|
||||
All prompting best practices apply. Be clear, be direct. Assume Claude is smart - only add context Claude doesn't have.
|
||||
**If a skill and a command share the same name, the skill takes precedence.**
|
||||
|
||||
### 2. Standard Markdown Format
|
||||
## When To Create What
|
||||
|
||||
Use YAML frontmatter + markdown body. **No XML tags** - use standard markdown headings.
|
||||
**Use a command file** (`commands/name.md`) when:
|
||||
- Simple, single-file workflow
|
||||
- No supporting files needed
|
||||
- Task-oriented action (deploy, commit, triage)
|
||||
|
||||
**Use a skill directory** (`skills/name/SKILL.md`) when:
|
||||
- Need supporting reference files, scripts, or templates
|
||||
- Background knowledge Claude should auto-load
|
||||
- Complex enough to benefit from progressive disclosure
|
||||
|
||||
Both use identical YAML frontmatter and markdown content format.
|
||||
|
||||
## Standard Markdown Format
|
||||
|
||||
Use YAML frontmatter + markdown body with **standard markdown headings**. Keep it clean and direct.
|
||||
|
||||
```markdown
|
||||
---
|
||||
@@ -35,25 +49,113 @@ Step-by-step procedures...
|
||||
Concrete usage examples...
|
||||
```
|
||||
|
||||
### 3. Progressive Disclosure
|
||||
## Frontmatter Reference
|
||||
|
||||
Keep SKILL.md under 500 lines. Split detailed content into reference files. Load only what's needed.
|
||||
All fields are optional. Only `description` is recommended.
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `name` | No | Display name. Lowercase letters, numbers, hyphens (max 64 chars). Defaults to directory name. |
|
||||
| `description` | Recommended | What it does AND when to use it. Claude uses this for auto-discovery. Max 1024 chars. |
|
||||
| `argument-hint` | No | Hint shown during autocomplete. Example: `[issue-number]` |
|
||||
| `disable-model-invocation` | No | Set `true` to prevent Claude auto-loading. Use for manual workflows like `/deploy`, `/commit`. 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. Options: `haiku`, `sonnet`, `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. |
|
||||
|
||||
### Invocation Control
|
||||
|
||||
| Frontmatter | User can invoke | Claude can invoke | When loaded |
|
||||
|-------------|----------------|-------------------|-------------|
|
||||
| (default) | Yes | Yes | Description always in context, full content loads when invoked |
|
||||
| `disable-model-invocation: true` | Yes | No | Description not in context, loads only when user invokes |
|
||||
| `user-invocable: false` | No | Yes | Description always in context, loads when relevant |
|
||||
|
||||
**Use `disable-model-invocation: true`** for workflows with side effects: `/deploy`, `/commit`, `/triage-prs`, `/send-slack-message`. You don't want Claude deciding to deploy because your code looks ready.
|
||||
|
||||
**Use `user-invocable: false`** for background knowledge that isn't a meaningful user action: coding conventions, domain context, legacy system docs.
|
||||
|
||||
## Dynamic Features
|
||||
|
||||
### Arguments
|
||||
|
||||
Use `$ARGUMENTS` placeholder for user input. If not present in content, arguments are appended automatically.
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: fix-issue
|
||||
description: Fix a GitHub issue
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
Fix GitHub issue $ARGUMENTS following our coding standards.
|
||||
```
|
||||
|
||||
Access individual args: `$ARGUMENTS[0]` or shorthand `$0`, `$1`, `$2`.
|
||||
|
||||
### Dynamic Context Injection
|
||||
|
||||
The `` !`command` `` syntax runs shell commands before content is sent to Claude:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: pr-summary
|
||||
description: Summarize changes in a pull request
|
||||
context: fork
|
||||
agent: Explore
|
||||
---
|
||||
|
||||
## Context
|
||||
- PR diff: !`gh pr diff`
|
||||
- Changed files: !`gh pr diff --name-only`
|
||||
|
||||
Summarize this pull request...
|
||||
```
|
||||
|
||||
### Running in a Subagent
|
||||
|
||||
Add `context: fork` to run in isolation. The skill content becomes the subagent's prompt. It won't have conversation history.
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: deep-research
|
||||
description: Research a topic thoroughly
|
||||
context: fork
|
||||
agent: Explore
|
||||
---
|
||||
|
||||
Research $ARGUMENTS thoroughly:
|
||||
1. Find relevant files
|
||||
2. Analyze the code
|
||||
3. Summarize findings
|
||||
```
|
||||
|
||||
## Progressive Disclosure
|
||||
|
||||
Keep SKILL.md under 500 lines. Split detailed content into reference files:
|
||||
|
||||
```
|
||||
my-skill/
|
||||
├── SKILL.md # Entry point (required)
|
||||
├── SKILL.md # Entry point (required, overview + navigation)
|
||||
├── reference.md # Detailed docs (loaded when needed)
|
||||
├── examples.md # Usage examples
|
||||
└── scripts/ # Utility scripts (executed, not loaded)
|
||||
├── examples.md # Usage examples (loaded when needed)
|
||||
└── scripts/
|
||||
└── helper.py # Utility script (executed, not loaded)
|
||||
```
|
||||
|
||||
### 4. Effective Descriptions
|
||||
Link from SKILL.md: `For API details, see [reference.md](reference.md).`
|
||||
|
||||
The description field enables skill discovery. Include both what the skill does AND when to use it. Write in third person.
|
||||
Keep references **one level deep** from SKILL.md. Avoid nested chains.
|
||||
|
||||
## Effective Descriptions
|
||||
|
||||
The description enables skill discovery. Include both **what** it does and **when** to use it.
|
||||
|
||||
**Good:**
|
||||
```yaml
|
||||
description: Extracts text and tables from PDF files, fills forms, merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
|
||||
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
|
||||
```
|
||||
|
||||
**Bad:**
|
||||
@@ -61,239 +163,113 @@ description: Extracts text and tables from PDF files, fills forms, merges docume
|
||||
description: Helps with documents
|
||||
```
|
||||
|
||||
## Skill Structure
|
||||
|
||||
### Required Frontmatter
|
||||
|
||||
| Field | Required | Max Length | Description |
|
||||
|-------|----------|------------|-------------|
|
||||
| `name` | Yes | 64 chars | Lowercase letters, numbers, hyphens only |
|
||||
| `description` | Yes | 1024 chars | What it does AND when to use it |
|
||||
| `allowed-tools` | No | - | Tools Claude can use without asking |
|
||||
| `model` | No | - | Specific model to use |
|
||||
|
||||
### Naming Conventions
|
||||
|
||||
Use **gerund form** (verb + -ing) for skill names:
|
||||
|
||||
- `processing-pdfs`
|
||||
- `analyzing-spreadsheets`
|
||||
- `generating-commit-messages`
|
||||
- `reviewing-code`
|
||||
|
||||
Avoid: `helper`, `utils`, `tools`, `anthropic-*`, `claude-*`
|
||||
|
||||
### Body Structure
|
||||
|
||||
Use standard markdown headings:
|
||||
|
||||
```markdown
|
||||
# Skill Name
|
||||
|
||||
## Quick Start
|
||||
Fastest path to value...
|
||||
|
||||
## Instructions
|
||||
Core guidance Claude follows...
|
||||
|
||||
## Examples
|
||||
Input/output pairs showing expected behavior...
|
||||
|
||||
## Advanced Features
|
||||
Additional capabilities (link to reference files)...
|
||||
|
||||
## Guidelines
|
||||
Rules and constraints...
|
||||
```
|
||||
|
||||
## What Would You Like To Do?
|
||||
|
||||
1. **Create new skill** - Build from scratch
|
||||
2. **Audit existing skill** - Check against best practices
|
||||
3. **Add component** - Add workflow/reference/example
|
||||
4. **Get guidance** - Understand skill design
|
||||
2. **Create new command** - Build a slash command
|
||||
3. **Audit existing skill** - Check against best practices
|
||||
4. **Add component** - Add workflow/reference/example
|
||||
5. **Get guidance** - Understand skill design
|
||||
|
||||
## Creating a New Skill
|
||||
## Creating a New Skill or Command
|
||||
|
||||
### Step 1: Choose Type
|
||||
|
||||
**Simple skill (single file):**
|
||||
- Under 500 lines
|
||||
- Self-contained guidance
|
||||
- No complex workflows
|
||||
Ask: Is this a manual workflow (deploy, commit, triage) or background knowledge (conventions, patterns)?
|
||||
|
||||
**Progressive disclosure skill (multiple files):**
|
||||
- SKILL.md as overview
|
||||
- Reference files for detailed docs
|
||||
- Scripts for utilities
|
||||
- **Manual workflow** → command with `disable-model-invocation: true`
|
||||
- **Background knowledge** → skill without `disable-model-invocation`
|
||||
- **Complex with supporting files** → skill directory
|
||||
|
||||
### Step 2: Create SKILL.md
|
||||
### Step 2: Create the File
|
||||
|
||||
**Command:**
|
||||
```markdown
|
||||
---
|
||||
name: your-skill-name
|
||||
description: [What it does]. Use when [trigger conditions].
|
||||
name: my-command
|
||||
description: What this command does
|
||||
argument-hint: [expected arguments]
|
||||
disable-model-invocation: true
|
||||
allowed-tools: Bash(gh *), Read
|
||||
---
|
||||
|
||||
# Your Skill Name
|
||||
# Command Title
|
||||
|
||||
## Quick Start
|
||||
## Workflow
|
||||
|
||||
[Immediate actionable example]
|
||||
### Step 1: Gather Context
|
||||
...
|
||||
|
||||
```[language]
|
||||
[Code example]
|
||||
### Step 2: Execute
|
||||
...
|
||||
|
||||
## Success Criteria
|
||||
- [ ] Expected outcome 1
|
||||
- [ ] Expected outcome 2
|
||||
```
|
||||
|
||||
## Instructions
|
||||
**Skill:**
|
||||
```markdown
|
||||
---
|
||||
name: my-skill
|
||||
description: What it does. Use when [trigger conditions].
|
||||
---
|
||||
|
||||
# Skill Title
|
||||
|
||||
## Quick Start
|
||||
[Immediate actionable example]
|
||||
|
||||
## Instructions
|
||||
[Core guidance]
|
||||
|
||||
## Examples
|
||||
|
||||
**Example 1:**
|
||||
Input: [description]
|
||||
Output:
|
||||
```
|
||||
[result]
|
||||
```
|
||||
|
||||
## Guidelines
|
||||
|
||||
- [Constraint 1]
|
||||
- [Constraint 2]
|
||||
[Concrete input/output pairs]
|
||||
```
|
||||
|
||||
### Step 3: Add Reference Files (If Needed)
|
||||
|
||||
Link from SKILL.md to detailed content:
|
||||
|
||||
```markdown
|
||||
For API reference, see [REFERENCE.md](REFERENCE.md).
|
||||
For form filling guide, see [FORMS.md](FORMS.md).
|
||||
For API reference, see [reference.md](reference.md).
|
||||
For form filling guide, see [forms.md](forms.md).
|
||||
```
|
||||
|
||||
Keep references **one level deep** from SKILL.md.
|
||||
|
||||
### Step 4: Add Scripts (If Needed)
|
||||
|
||||
Scripts execute without loading into context:
|
||||
|
||||
```markdown
|
||||
## Utility Scripts
|
||||
|
||||
Extract fields:
|
||||
```bash
|
||||
python scripts/analyze.py input.pdf > fields.json
|
||||
```
|
||||
```
|
||||
|
||||
### Step 5: Test With Real Usage
|
||||
### Step 4: Test With Real Usage
|
||||
|
||||
1. Test with actual tasks, not test scenarios
|
||||
2. Observe where Claude struggles
|
||||
3. Refine based on real behavior
|
||||
4. Test with Haiku, Sonnet, and Opus
|
||||
2. Invoke directly with `/skill-name` to verify
|
||||
3. Check auto-triggering by asking something that matches the description
|
||||
4. Refine based on real behavior
|
||||
|
||||
## Auditing Existing Skills
|
||||
|
||||
Check against this rubric:
|
||||
## Audit Checklist
|
||||
|
||||
- [ ] Valid YAML frontmatter (name + description)
|
||||
- [ ] Description includes trigger keywords
|
||||
- [ ] Description includes trigger keywords and is specific
|
||||
- [ ] Uses standard markdown headings (not XML tags)
|
||||
- [ ] SKILL.md under 500 lines
|
||||
- [ ] References one level deep
|
||||
- [ ] `disable-model-invocation: true` if it has side effects
|
||||
- [ ] `allowed-tools` set if specific tools needed
|
||||
- [ ] References one level deep, properly linked
|
||||
- [ ] Examples are concrete, not abstract
|
||||
- [ ] Consistent terminology
|
||||
- [ ] No time-sensitive information
|
||||
- [ ] Scripts handle errors explicitly
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Template Pattern
|
||||
|
||||
Provide output templates for consistent results:
|
||||
|
||||
```markdown
|
||||
## Report Template
|
||||
|
||||
```markdown
|
||||
# [Analysis Title]
|
||||
|
||||
## Executive Summary
|
||||
[One paragraph overview]
|
||||
|
||||
## Key Findings
|
||||
- Finding 1
|
||||
- Finding 2
|
||||
|
||||
## Recommendations
|
||||
1. [Action item]
|
||||
2. [Action item]
|
||||
```
|
||||
```
|
||||
|
||||
### Workflow Pattern
|
||||
|
||||
For complex multi-step tasks:
|
||||
|
||||
```markdown
|
||||
## Migration Workflow
|
||||
|
||||
Copy this checklist:
|
||||
|
||||
```
|
||||
- [ ] Step 1: Backup database
|
||||
- [ ] Step 2: Run migration script
|
||||
- [ ] Step 3: Validate output
|
||||
- [ ] Step 4: Update configuration
|
||||
```
|
||||
|
||||
**Step 1: Backup database**
|
||||
Run: `./scripts/backup.sh`
|
||||
...
|
||||
```
|
||||
|
||||
### Conditional Pattern
|
||||
|
||||
Guide through decision points:
|
||||
|
||||
```markdown
|
||||
## Choose Your Approach
|
||||
|
||||
**Creating new content?** Follow "Creation workflow" below.
|
||||
**Editing existing?** Follow "Editing workflow" below.
|
||||
```
|
||||
- [ ] Tested with real usage
|
||||
|
||||
## Anti-Patterns to Avoid
|
||||
|
||||
- **XML tags in body** - Use markdown headings instead
|
||||
- **XML tags in body** - Use standard markdown headings
|
||||
- **Vague descriptions** - Be specific with trigger keywords
|
||||
- **Deep nesting** - Keep references one level from SKILL.md
|
||||
- **Missing invocation control** - Side-effect workflows need `disable-model-invocation: true`
|
||||
- **Too many options** - Provide a default with escape hatch
|
||||
- **Windows paths** - Always use forward slashes
|
||||
- **Punting to Claude** - Scripts should handle errors
|
||||
- **Time-sensitive info** - Use "old patterns" section instead
|
||||
- **Punting to Claude** - Scripts should handle errors explicitly
|
||||
|
||||
## Reference Files
|
||||
|
||||
For detailed guidance, see:
|
||||
|
||||
- [official-spec.md](references/official-spec.md) - Anthropic's official skill specification
|
||||
- [official-spec.md](references/official-spec.md) - Official skill specification
|
||||
- [best-practices.md](references/best-practices.md) - Skill authoring best practices
|
||||
|
||||
## Success Criteria
|
||||
## Sources
|
||||
|
||||
A well-structured skill:
|
||||
- Has valid YAML frontmatter with descriptive name and description
|
||||
- Uses standard markdown headings (not XML tags)
|
||||
- Keeps SKILL.md under 500 lines
|
||||
- Links to reference files for detailed content
|
||||
- Includes concrete examples with input/output pairs
|
||||
- Has been tested with real usage
|
||||
|
||||
Sources:
|
||||
- [Agent Skills - Claude Code Docs](https://code.claude.com/docs/en/skills)
|
||||
- [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
|
||||
- [Extend Claude with skills - Official Docs](https://code.claude.com/docs/en/skills)
|
||||
- [GitHub - anthropics/skills](https://github.com/anthropics/skills)
|
||||
|
||||
@@ -1,36 +1,56 @@
|
||||
# Anthropic Official Skill Specification
|
||||
# Official Skill Specification (2026)
|
||||
|
||||
Source: [code.claude.com/docs/en/skills](https://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 Markdown instructions.
|
||||
|
||||
### Basic Format
|
||||
Every skill requires a `SKILL.md` file with YAML frontmatter followed by standard markdown instructions.
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: your-skill-name
|
||||
description: Brief description of what this Skill does and when to use it
|
||||
description: What it does and when to use it
|
||||
---
|
||||
|
||||
# Your Skill Name
|
||||
|
||||
## Instructions
|
||||
Provide clear, step-by-step guidance for Claude.
|
||||
Clear, step-by-step guidance.
|
||||
|
||||
## Examples
|
||||
Show concrete examples of using this Skill.
|
||||
Concrete examples of using this skill.
|
||||
```
|
||||
|
||||
## Required Frontmatter Fields
|
||||
## Complete Frontmatter Reference
|
||||
|
||||
All fields are optional. Only `description` is recommended.
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `name` | Yes | Skill name using lowercase letters, numbers, and hyphens only (max 64 characters). Should match the directory name. |
|
||||
| `description` | Yes | What the Skill does and when to use it (max 1024 characters). Claude uses this to decide when to apply the Skill. |
|
||||
| `allowed-tools` | No | Tools Claude can use without asking permission when this Skill is active. Example: `Read, Grep, Glob` |
|
||||
| `model` | No | Specific model to use when this Skill is active (e.g., `claude-sonnet-4-20250514`). Defaults to the conversation's model. |
|
||||
| `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
|
||||
|
||||
@@ -40,146 +60,75 @@ Enterprise (highest priority) → Personal → Project → Plugin (lowest priori
|
||||
|
||||
| Type | Path | Applies to |
|
||||
|------|------|-----------|
|
||||
| **Enterprise** | See managed settings | All users in organization |
|
||||
| **Personal** | `~/.claude/skills/` | You, across all projects |
|
||||
| **Project** | `.claude/skills/` | Anyone working in repository |
|
||||
| **Plugin** | Bundled with plugins | Anyone with plugin installed |
|
||||
| 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
|
||||
|
||||
1. **Discovery**: Claude loads only name and description at startup
|
||||
2. **Activation**: When your request matches a Skill's description, Claude asks for confirmation
|
||||
3. **Execution**: Claude follows the Skill's instructions and loads referenced files
|
||||
1. **Discovery**: Claude loads only name and description at startup (2% of context window budget)
|
||||
2. **Activation**: When your request matches a skill's description, Claude loads the full content
|
||||
3. **Execution**: Claude follows the skill's instructions
|
||||
|
||||
**Key Principle**: Skills are **model-invoked** — Claude automatically decides which Skills to use based on your request.
|
||||
## String Substitutions
|
||||
|
||||
## Progressive Disclosure Pattern
|
||||
| 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 |
|
||||
|
||||
Keep `SKILL.md` under 500 lines by linking to supporting files:
|
||||
## Dynamic Context Injection
|
||||
|
||||
The `` !`command` `` syntax runs shell commands before content is sent to Claude:
|
||||
|
||||
```markdown
|
||||
## 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 (required - overview and navigation)
|
||||
├── reference.md (detailed API docs - loaded when needed)
|
||||
├── examples.md (usage examples - loaded when needed)
|
||||
├── 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)
|
||||
└── helper.py # Utility script (executed, not loaded)
|
||||
```
|
||||
|
||||
### Example SKILL.md with References
|
||||
|
||||
Keep SKILL.md under 500 lines. Link to supporting files:
|
||||
```markdown
|
||||
---
|
||||
name: pdf-processing
|
||||
description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction. Requires pypdf and pdfplumber packages.
|
||||
allowed-tools: Read, Bash(python:*)
|
||||
---
|
||||
|
||||
# PDF Processing
|
||||
|
||||
## Quick start
|
||||
|
||||
Extract text:
|
||||
```python
|
||||
import pdfplumber
|
||||
with pdfplumber.open("doc.pdf") as pdf:
|
||||
text = pdf.pages[0].extract_text()
|
||||
For API details, see [reference.md](reference.md).
|
||||
```
|
||||
|
||||
For form filling, see [FORMS.md](FORMS.md).
|
||||
For detailed API reference, see [REFERENCE.md](REFERENCE.md).
|
||||
## Running in a Subagent
|
||||
|
||||
## Requirements
|
||||
|
||||
Packages must be installed:
|
||||
```bash
|
||||
pip install pypdf pdfplumber
|
||||
```
|
||||
```
|
||||
|
||||
## Restricting Tool Access
|
||||
Add `context: fork` to run in isolation:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: reading-files-safely
|
||||
description: Read files without making changes. Use when you need read-only file access.
|
||||
allowed-tools: Read, Grep, Glob
|
||||
---
|
||||
```
|
||||
|
||||
Benefits:
|
||||
- Read-only Skills that shouldn't modify files
|
||||
- Limited scope for specific tasks
|
||||
- Security-sensitive workflows
|
||||
|
||||
## Writing Effective Descriptions
|
||||
|
||||
The `description` field enables Skill discovery and should include both what the Skill does and when to use it.
|
||||
|
||||
**Always write in third person.** The description is injected into the system prompt.
|
||||
|
||||
- **Good:** "Processes Excel files and generates reports"
|
||||
- **Avoid:** "I can help you process Excel files"
|
||||
- **Avoid:** "You can use this to process Excel files"
|
||||
|
||||
**Be specific and include key terms:**
|
||||
|
||||
```yaml
|
||||
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
|
||||
```
|
||||
|
||||
**Avoid vague descriptions:**
|
||||
|
||||
```yaml
|
||||
description: Helps with documents # Too vague!
|
||||
```
|
||||
|
||||
## Complete Example: Commit Message Generator
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: generating-commit-messages
|
||||
description: Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes.
|
||||
name: deep-research
|
||||
description: Research a topic thoroughly
|
||||
context: fork
|
||||
agent: Explore
|
||||
---
|
||||
|
||||
# Generating Commit Messages
|
||||
|
||||
## Instructions
|
||||
|
||||
1. Run `git diff --staged` to see changes
|
||||
2. I'll suggest a commit message with:
|
||||
- Summary under 50 characters
|
||||
- Detailed description
|
||||
- Affected components
|
||||
|
||||
## Best practices
|
||||
|
||||
- Use present tense
|
||||
- Explain what and why, not how
|
||||
Research $ARGUMENTS thoroughly...
|
||||
```
|
||||
|
||||
## Complete Example: Code Explanation Skill
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: explaining-code
|
||||
description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
|
||||
---
|
||||
|
||||
# Explaining Code
|
||||
|
||||
When explaining code, always include:
|
||||
|
||||
1. **Start with an analogy**: Compare the code to something from everyday life
|
||||
2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
|
||||
3. **Walk through the code**: Explain step-by-step what happens
|
||||
4. **Highlight a gotcha**: What's a common misconception?
|
||||
|
||||
Keep explanations conversational. For complex concepts, use multiple analogies.
|
||||
```
|
||||
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 with Skill folders
|
||||
- **Project skills**: Commit `.claude/skills/` to version control
|
||||
- **Plugins**: Add `skills/` directory to plugin
|
||||
- **Enterprise**: Deploy organization-wide through managed settings
|
||||
|
||||
@@ -1,372 +1,152 @@
|
||||
<overview>
|
||||
Skills have three structural components: YAML frontmatter (metadata), pure XML body structure (content organization), and progressive disclosure (file organization). This reference defines requirements and best practices for each component.
|
||||
</overview>
|
||||
# Skill Structure Reference
|
||||
|
||||
<xml_structure_requirements>
|
||||
<critical_rule>
|
||||
**Remove ALL markdown headings (#, ##, ###) from skill body content.** Replace with semantic XML tags. Keep markdown formatting WITHIN content (bold, italic, lists, code blocks, links).
|
||||
</critical_rule>
|
||||
Skills have three structural components: YAML frontmatter (metadata), standard markdown body (content), and progressive disclosure (file organization).
|
||||
|
||||
<required_tags>
|
||||
Every skill MUST have these three tags:
|
||||
## Body Format
|
||||
|
||||
- **`<objective>`** - What the skill does and why it matters (1-3 paragraphs)
|
||||
- **`<quick_start>`** - Immediate, actionable guidance (minimal working example)
|
||||
- **`<success_criteria>`** or **`<when_successful>`** - How to know it worked
|
||||
</required_tags>
|
||||
Use **standard markdown headings** for structure. Keep markdown formatting within content (bold, italic, lists, code blocks, links).
|
||||
|
||||
<conditional_tags>
|
||||
Add based on skill complexity and domain requirements:
|
||||
```markdown
|
||||
---
|
||||
name: my-skill
|
||||
description: What it does and when to use it
|
||||
---
|
||||
|
||||
- **`<context>`** - Background/situational information
|
||||
- **`<workflow>` or `<process>`** - Step-by-step procedures
|
||||
- **`<advanced_features>`** - Deep-dive topics (progressive disclosure)
|
||||
- **`<validation>`** - How to verify outputs
|
||||
- **`<examples>`** - Multi-shot learning
|
||||
- **`<anti_patterns>`** - Common mistakes to avoid
|
||||
- **`<security_checklist>`** - Non-negotiable security patterns
|
||||
- **`<testing>`** - Testing workflows
|
||||
- **`<common_patterns>`** - Code examples and recipes
|
||||
- **`<reference_guides>` or `<detailed_references>`** - Links to reference files
|
||||
# Skill Name
|
||||
|
||||
See [use-xml-tags.md](use-xml-tags.md) for detailed guidance on each tag.
|
||||
</conditional_tags>
|
||||
## Quick Start
|
||||
Immediate actionable guidance...
|
||||
|
||||
<tag_selection_intelligence>
|
||||
**Simple skills** (single domain, straightforward):
|
||||
- Required tags only
|
||||
- Example: Text extraction, file format conversion
|
||||
## Instructions
|
||||
Step-by-step procedures...
|
||||
|
||||
**Medium skills** (multiple patterns, some complexity):
|
||||
- Required tags + workflow/examples as needed
|
||||
- Example: Document processing with steps, API integration
|
||||
## Examples
|
||||
Concrete usage examples...
|
||||
|
||||
**Complex skills** (multiple domains, security, APIs):
|
||||
- Required tags + conditional tags as appropriate
|
||||
- Example: Payment processing, authentication systems, multi-step workflows
|
||||
</tag_selection_intelligence>
|
||||
|
||||
<xml_nesting>
|
||||
Properly nest XML tags for hierarchical content:
|
||||
|
||||
```xml
|
||||
<examples>
|
||||
<example number="1">
|
||||
<input>User input</input>
|
||||
<output>Expected output</output>
|
||||
</example>
|
||||
</examples>
|
||||
## Guidelines
|
||||
Rules and constraints...
|
||||
```
|
||||
|
||||
Always close tags:
|
||||
```xml
|
||||
<objective>
|
||||
Content here
|
||||
</objective>
|
||||
```
|
||||
</xml_nesting>
|
||||
## Recommended Sections
|
||||
|
||||
<tag_naming_conventions>
|
||||
Use descriptive, semantic names:
|
||||
- `<workflow>` not `<steps>`
|
||||
- `<success_criteria>` not `<done>`
|
||||
- `<anti_patterns>` not `<dont_do>`
|
||||
Every skill should have:
|
||||
|
||||
Be consistent within your skill. If you use `<workflow>`, don't also use `<process>` for the same purpose (unless they serve different roles).
|
||||
</tag_naming_conventions>
|
||||
</xml_structure_requirements>
|
||||
- **Quick Start** - Immediate, actionable guidance (minimal working example)
|
||||
- **Instructions** - Core step-by-step guidance
|
||||
- **Success Criteria** - How to know it worked
|
||||
|
||||
Add based on complexity:
|
||||
|
||||
- **Context** - Background/situational information
|
||||
- **Workflow** - Multi-step procedures
|
||||
- **Examples** - Concrete input/output pairs
|
||||
- **Advanced Features** - Deep-dive topics (link to reference files)
|
||||
- **Anti-Patterns** - Common mistakes to avoid
|
||||
- **Guidelines** - Rules and constraints
|
||||
|
||||
## YAML Frontmatter
|
||||
|
||||
### Required/Recommended Fields
|
||||
|
||||
<yaml_requirements>
|
||||
<required_fields>
|
||||
```yaml
|
||||
---
|
||||
name: skill-name-here
|
||||
description: What it does and when to use it (third person, specific triggers)
|
||||
description: What it does and when to use it (specific triggers included)
|
||||
---
|
||||
```
|
||||
</required_fields>
|
||||
|
||||
<name_field>
|
||||
**Validation rules**:
|
||||
### Name Field
|
||||
|
||||
**Validation rules:**
|
||||
- Maximum 64 characters
|
||||
- Lowercase letters, numbers, hyphens only
|
||||
- No XML tags
|
||||
- Must match directory name
|
||||
- No reserved words: "anthropic", "claude"
|
||||
- Must match directory name exactly
|
||||
|
||||
**Examples**:
|
||||
- ✅ `process-pdfs`
|
||||
- ✅ `manage-facebook-ads`
|
||||
- ✅ `setup-stripe-payments`
|
||||
- ❌ `PDF_Processor` (uppercase)
|
||||
- ❌ `helper` (vague)
|
||||
- ❌ `claude-helper` (reserved word)
|
||||
</name_field>
|
||||
**Examples:**
|
||||
- `triage-prs`
|
||||
- `deploy-production`
|
||||
- `review-code`
|
||||
- `setup-stripe-payments`
|
||||
|
||||
<description_field>
|
||||
**Validation rules**:
|
||||
- Non-empty, maximum 1024 characters
|
||||
- No XML tags
|
||||
- Third person (never first or second person)
|
||||
**Avoid:** `helper`, `utils`, `tools`, generic names
|
||||
|
||||
### Description Field
|
||||
|
||||
**Validation rules:**
|
||||
- Maximum 1024 characters
|
||||
- Include what it does AND when to use it
|
||||
- Third person voice
|
||||
|
||||
**Critical rule**: Always write in third person.
|
||||
- ✅ "Processes Excel files and generates reports"
|
||||
- ❌ "I can help you process Excel files"
|
||||
- ❌ "You can use this to process Excel files"
|
||||
|
||||
**Structure**: Include both capabilities and triggers.
|
||||
|
||||
**Effective examples**:
|
||||
**Good:**
|
||||
```yaml
|
||||
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
|
||||
```
|
||||
|
||||
```yaml
|
||||
description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.
|
||||
```
|
||||
|
||||
```yaml
|
||||
description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.
|
||||
```
|
||||
|
||||
**Avoid**:
|
||||
**Bad:**
|
||||
```yaml
|
||||
description: Helps with documents
|
||||
```
|
||||
|
||||
```yaml
|
||||
description: Processes data
|
||||
### Optional Fields
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `argument-hint` | Usage hints. Example: `[issue-number]` |
|
||||
| `disable-model-invocation` | `true` to prevent auto-loading. Use for side-effect workflows. |
|
||||
| `user-invocable` | `false` to hide from `/` menu. Use for background knowledge. |
|
||||
| `allowed-tools` | Tools without permission prompts. Example: `Read, Bash(git *)` |
|
||||
| `model` | `haiku`, `sonnet`, or `opus` |
|
||||
| `context` | `fork` for isolated subagent execution |
|
||||
| `agent` | Subagent type: `Explore`, `Plan`, `general-purpose`, or custom |
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
Use descriptive names that indicate purpose:
|
||||
|
||||
| Pattern | Examples |
|
||||
|---------|----------|
|
||||
| Action-oriented | `triage-prs`, `deploy-production`, `review-code` |
|
||||
| Domain-specific | `setup-stripe-payments`, `manage-facebook-ads` |
|
||||
| Descriptive | `git-worktree`, `frontend-design`, `dhh-rails-style` |
|
||||
|
||||
## Progressive Disclosure
|
||||
|
||||
Keep SKILL.md under 500 lines. Split into reference files:
|
||||
|
||||
```
|
||||
my-skill/
|
||||
├── SKILL.md # Entry point (required, overview + navigation)
|
||||
├── reference.md # Detailed docs (loaded when needed)
|
||||
├── examples.md # Usage examples (loaded when needed)
|
||||
└── scripts/
|
||||
└── helper.py # Utility script (executed, not loaded)
|
||||
```
|
||||
</description_field>
|
||||
</yaml_requirements>
|
||||
|
||||
<naming_conventions>
|
||||
Use **verb-noun convention** for skill names:
|
||||
|
||||
<pattern name="create">
|
||||
Building/authoring tools
|
||||
|
||||
Examples: `create-agent-skills`, `create-hooks`, `create-landing-pages`
|
||||
</pattern>
|
||||
|
||||
<pattern name="manage">
|
||||
Managing external services or resources
|
||||
|
||||
Examples: `manage-facebook-ads`, `manage-zoom`, `manage-stripe`, `manage-supabase`
|
||||
</pattern>
|
||||
|
||||
<pattern name="setup">
|
||||
Configuration/integration tasks
|
||||
|
||||
Examples: `setup-stripe-payments`, `setup-meta-tracking`
|
||||
</pattern>
|
||||
|
||||
<pattern name="generate">
|
||||
Generation tasks
|
||||
|
||||
Examples: `generate-ai-images`
|
||||
</pattern>
|
||||
|
||||
<avoid_patterns>
|
||||
- Vague: `helper`, `utils`, `tools`
|
||||
- Generic: `documents`, `data`, `files`
|
||||
- Reserved words: `anthropic-helper`, `claude-tools`
|
||||
- Inconsistent: Directory `facebook-ads` but name `facebook-ads-manager`
|
||||
</avoid_patterns>
|
||||
</naming_conventions>
|
||||
|
||||
<progressive_disclosure>
|
||||
<principle>
|
||||
SKILL.md serves as an overview that points to detailed materials as needed. This keeps context window usage efficient.
|
||||
</principle>
|
||||
|
||||
<practical_guidance>
|
||||
- Keep SKILL.md body under 500 lines
|
||||
- Split content into separate files when approaching this limit
|
||||
**Rules:**
|
||||
- Keep references one level deep from SKILL.md
|
||||
- Add table of contents to reference files over 100 lines
|
||||
</practical_guidance>
|
||||
- Use forward slashes in paths: `scripts/helper.py`
|
||||
- Name files descriptively: `form_validation_rules.md` not `doc2.md`
|
||||
|
||||
<pattern name="high_level_guide">
|
||||
Quick start in SKILL.md, details in reference files:
|
||||
## Validation Checklist
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: pdf-processing
|
||||
description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
|
||||
---
|
||||
Before finalizing:
|
||||
|
||||
<objective>
|
||||
Extract text and tables from PDF files, fill forms, and merge documents using Python libraries.
|
||||
</objective>
|
||||
- [ ] YAML frontmatter valid (name matches directory, description specific)
|
||||
- [ ] Uses standard markdown headings (not XML tags)
|
||||
- [ ] Has Quick Start, Instructions, and Success Criteria sections
|
||||
- [ ] `disable-model-invocation: true` if skill has side effects
|
||||
- [ ] SKILL.md under 500 lines
|
||||
- [ ] Reference files linked properly from SKILL.md
|
||||
- [ ] File paths use forward slashes
|
||||
- [ ] Tested with real usage
|
||||
|
||||
<quick_start>
|
||||
Extract text with pdfplumber:
|
||||
## Anti-Patterns
|
||||
|
||||
```python
|
||||
import pdfplumber
|
||||
with pdfplumber.open("file.pdf") as pdf:
|
||||
text = pdf.pages[0].extract_text()
|
||||
```
|
||||
</quick_start>
|
||||
|
||||
<advanced_features>
|
||||
**Form filling**: See [forms.md](forms.md)
|
||||
**API reference**: See [reference.md](reference.md)
|
||||
</advanced_features>
|
||||
```
|
||||
|
||||
Claude loads forms.md or reference.md only when needed.
|
||||
</pattern>
|
||||
|
||||
<pattern name="domain_organization">
|
||||
For skills with multiple domains, organize by domain to avoid loading irrelevant context:
|
||||
|
||||
```
|
||||
bigquery-skill/
|
||||
├── SKILL.md (overview and navigation)
|
||||
└── reference/
|
||||
├── finance.md (revenue, billing metrics)
|
||||
├── sales.md (opportunities, pipeline)
|
||||
├── product.md (API usage, features)
|
||||
└── marketing.md (campaigns, attribution)
|
||||
```
|
||||
|
||||
When user asks about revenue, Claude reads only finance.md. Other files stay on filesystem consuming zero tokens.
|
||||
</pattern>
|
||||
|
||||
<pattern name="conditional_details">
|
||||
Show basic content in SKILL.md, link to advanced in reference files:
|
||||
|
||||
```xml
|
||||
<objective>
|
||||
Process DOCX files with creation and editing capabilities.
|
||||
</objective>
|
||||
|
||||
<quick_start>
|
||||
<creating_documents>
|
||||
Use docx-js for new documents. See [docx-js.md](docx-js.md).
|
||||
</creating_documents>
|
||||
|
||||
<editing_documents>
|
||||
For simple edits, modify XML directly.
|
||||
|
||||
**For tracked changes**: See [redlining.md](redlining.md)
|
||||
**For OOXML details**: See [ooxml.md](ooxml.md)
|
||||
</editing_documents>
|
||||
</quick_start>
|
||||
```
|
||||
|
||||
Claude reads redlining.md or ooxml.md only when the user needs those features.
|
||||
</pattern>
|
||||
|
||||
<critical_rules>
|
||||
**Keep references one level deep**: All reference files should link directly from SKILL.md. Avoid nested references (SKILL.md → advanced.md → details.md) as Claude may only partially read deeply nested files.
|
||||
|
||||
**Add table of contents to long files**: For reference files over 100 lines, include a table of contents at the top.
|
||||
|
||||
**Use pure XML in reference files**: Reference files should also use pure XML structure (no markdown headings in body).
|
||||
</critical_rules>
|
||||
</progressive_disclosure>
|
||||
|
||||
<file_organization>
|
||||
<filesystem_navigation>
|
||||
Claude navigates your skill directory using bash commands:
|
||||
|
||||
- Use forward slashes: `reference/guide.md` (not `reference\guide.md`)
|
||||
- Name files descriptively: `form_validation_rules.md` (not `doc2.md`)
|
||||
- Organize by domain: `reference/finance.md`, `reference/sales.md`
|
||||
</filesystem_navigation>
|
||||
|
||||
<directory_structure>
|
||||
Typical skill structure:
|
||||
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md (main entry point, pure XML structure)
|
||||
├── references/ (optional, for progressive disclosure)
|
||||
│ ├── guide-1.md (pure XML structure)
|
||||
│ ├── guide-2.md (pure XML structure)
|
||||
│ └── examples.md (pure XML structure)
|
||||
└── scripts/ (optional, for utility scripts)
|
||||
├── validate.py
|
||||
└── process.py
|
||||
```
|
||||
</directory_structure>
|
||||
</file_organization>
|
||||
|
||||
<anti_patterns>
|
||||
<pitfall name="markdown_headings_in_body">
|
||||
❌ Do NOT use markdown headings in skill body:
|
||||
|
||||
```markdown
|
||||
# PDF Processing
|
||||
|
||||
## Quick start
|
||||
Extract text...
|
||||
|
||||
## Advanced features
|
||||
Form filling...
|
||||
```
|
||||
|
||||
✅ Use pure XML structure:
|
||||
|
||||
```xml
|
||||
<objective>
|
||||
PDF processing with text extraction, form filling, and merging.
|
||||
</objective>
|
||||
|
||||
<quick_start>
|
||||
Extract text...
|
||||
</quick_start>
|
||||
|
||||
<advanced_features>
|
||||
Form filling...
|
||||
</advanced_features>
|
||||
```
|
||||
</pitfall>
|
||||
|
||||
<pitfall name="vague_descriptions">
|
||||
- ❌ "Helps with documents"
|
||||
- ✅ "Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction."
|
||||
</pitfall>
|
||||
|
||||
<pitfall name="inconsistent_pov">
|
||||
- ❌ "I can help you process Excel files"
|
||||
- ✅ "Processes Excel files and generates reports"
|
||||
</pitfall>
|
||||
|
||||
<pitfall name="wrong_naming_convention">
|
||||
- ❌ Directory: `facebook-ads`, Name: `facebook-ads-manager`
|
||||
- ✅ Directory: `manage-facebook-ads`, Name: `manage-facebook-ads`
|
||||
- ❌ Directory: `stripe-integration`, Name: `stripe`
|
||||
- ✅ Directory: `setup-stripe-payments`, Name: `setup-stripe-payments`
|
||||
</pitfall>
|
||||
|
||||
<pitfall name="deeply_nested_references">
|
||||
Keep references one level deep from SKILL.md. Claude may only partially read nested files (SKILL.md → advanced.md → details.md).
|
||||
</pitfall>
|
||||
|
||||
<pitfall name="windows_paths">
|
||||
Always use forward slashes: `scripts/helper.py` (not `scripts\helper.py`)
|
||||
</pitfall>
|
||||
|
||||
<pitfall name="missing_required_tags">
|
||||
Every skill must have: `<objective>`, `<quick_start>`, and `<success_criteria>` (or `<when_successful>`).
|
||||
</pitfall>
|
||||
</anti_patterns>
|
||||
|
||||
<validation_checklist>
|
||||
Before finalizing a skill, verify:
|
||||
|
||||
- ✅ YAML frontmatter valid (name matches directory, description in third person)
|
||||
- ✅ No markdown headings in body (pure XML structure)
|
||||
- ✅ Required tags present: objective, quick_start, success_criteria
|
||||
- ✅ Conditional tags appropriate for complexity level
|
||||
- ✅ All XML tags properly closed
|
||||
- ✅ Progressive disclosure applied (SKILL.md < 500 lines)
|
||||
- ✅ Reference files use pure XML structure
|
||||
- ✅ File paths use forward slashes
|
||||
- ✅ Descriptive file names
|
||||
</validation_checklist>
|
||||
- **XML tags in body** - Use standard markdown headings
|
||||
- **Vague descriptions** - Be specific with trigger keywords
|
||||
- **Deep nesting** - Keep references one level from SKILL.md
|
||||
- **Missing invocation control** - Side-effect workflows need `disable-model-invocation: true`
|
||||
- **Inconsistent naming** - Directory name must match `name` field
|
||||
- **Windows paths** - Always use forward slashes
|
||||
|
||||
Reference in New Issue
Block a user