john/claude-engineering-plugin
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

Update create-agent-skills to match 2026 official docs, add /triage-prs command

Browse Source 
- 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
2026-02-08 14:39:02 -08:00
parent 04ee7e4506
commit 4f4873f8c0
5 changed files with 683 additions and 657 deletions
Download Patch File Download Diff File Expand all files Collapse all files

193
.claude/commands/triage-prs.md Normal file
View 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
View 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

378
plugins/compound-engineering/skills/create-agent-skills/SKILL.md
View File

@@ -1,21 +1,35 @@
--- ---
name: creating-agent-skills name: create-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. 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 ```markdown
--- ---
@@ -35,25 +49,113 @@ Step-by-step procedures...
Concrete usage examples... 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/ my-skill/
├── SKILL.md # Entry point (required) ├── SKILL.md # Entry point (required, overview + navigation)
├── reference.md # Detailed docs (loaded when needed) ├── reference.md # Detailed docs (loaded when needed)
├── examples.md # Usage examples ├── examples.md # Usage examples (loaded when needed)
└── scripts/ # Utility scripts (executed, not loaded) └── 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:** **Good:**
```yaml ```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:** **Bad:**
@@ -61,239 +163,113 @@ description: Extracts text and tables from PDF files, fills forms, merges docume
description: Helps with documents 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? ## What Would You Like To Do?
1. **Create new skill** - Build from scratch 1. **Create new skill** - Build from scratch
2. **Audit existing skill** - Check against best practices 2. **Create new command** - Build a slash command
3. **Add component** - Add workflow/reference/example 3. **Audit existing skill** - Check against best practices
4. **Get guidance** - Understand skill design 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 ### Step 1: Choose Type
**Simple skill (single file):** Ask: Is this a manual workflow (deploy, commit, triage) or background knowledge (conventions, patterns)?
- Under 500 lines
- Self-contained guidance
- No complex workflows
**Progressive disclosure skill (multiple files):** - **Manual workflow** → command with `disable-model-invocation: true`
- SKILL.md as overview - **Background knowledge** → skill without `disable-model-invocation`
- Reference files for detailed docs - **Complex with supporting files** → skill directory
- Scripts for utilities
### Step 2: Create SKILL.md ### Step 2: Create the File
**Command:**
```markdown ```markdown
--- ---
name: your-skill-name name: my-command
description: [What it does]. Use when [trigger conditions]. 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] ### Step 2: Execute
[Code example] ...
## 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] [Core guidance]
## Examples ## Examples
[Concrete input/output pairs]
**Example 1:**
Input: [description]
Output:
```
[result]
```
## Guidelines
- [Constraint 1]
- [Constraint 2]
``` ```
### Step 3: Add Reference Files (If Needed) ### Step 3: Add Reference Files (If Needed)
Link from SKILL.md to detailed content: Link from SKILL.md to detailed content:
```markdown ```markdown
For API reference, see [REFERENCE.md](REFERENCE.md). For API reference, see [reference.md](reference.md).
For form filling guide, see [FORMS.md](FORMS.md). For form filling guide, see [forms.md](forms.md).
``` ```
Keep references **one level deep** from SKILL.md. ### Step 4: Test With Real Usage
### 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
1. Test with actual tasks, not test scenarios 1. Test with actual tasks, not test scenarios
2. Observe where Claude struggles 2. Invoke directly with `/skill-name` to verify
3. Refine based on real behavior 3. Check auto-triggering by asking something that matches the description
4. Test with Haiku, Sonnet, and Opus 4. Refine based on real behavior
## Auditing Existing Skills ## Audit Checklist
Check against this rubric:
- [ ] Valid YAML frontmatter (name + description) - [ ] Valid YAML frontmatter (name + description)
- [ ] Description includes trigger keywords - [ ] Description includes trigger keywords and is specific
- [ ] Uses standard markdown headings (not XML tags) - [ ] Uses standard markdown headings (not XML tags)
- [ ] SKILL.md under 500 lines - [ ] 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 - [ ] Examples are concrete, not abstract
- [ ] Consistent terminology - [ ] Tested with real usage
- [ ] 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.
```
## Anti-Patterns to Avoid ## 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 - **Vague descriptions** - Be specific with trigger keywords
- **Deep nesting** - Keep references one level from SKILL.md - **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 - **Too many options** - Provide a default with escape hatch
- **Windows paths** - Always use forward slashes - **Punting to Claude** - Scripts should handle errors explicitly
- **Punting to Claude** - Scripts should handle errors
- **Time-sensitive info** - Use "old patterns" section instead
## Reference Files ## Reference Files
For detailed guidance, see: For detailed guidance, see:
- [official-spec.md](references/official-spec.md) - Official skill specification
- [official-spec.md](references/official-spec.md) - Anthropic's official skill specification
- [best-practices.md](references/best-practices.md) - Skill authoring best practices - [best-practices.md](references/best-practices.md) - Skill authoring best practices
## Success Criteria ## Sources
A well-structured skill: - [Extend Claude with skills - Official Docs](https://code.claude.com/docs/en/skills)
- 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)
- [GitHub - anthropics/skills](https://github.com/anthropics/skills) - [GitHub - anthropics/skills](https://github.com/anthropics/skills)

205
plugins/compound-engineering/skills/create-agent-skills/references/official-spec.md
View File

@@ -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) 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 ## SKILL.md File Structure
Every Skill requires a `SKILL.md` file with YAML frontmatter followed by Markdown instructions. Every skill requires a `SKILL.md` file with YAML frontmatter followed by standard markdown instructions.
### Basic Format
```markdown ```markdown
--- ---
name: your-skill-name 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 # Your Skill Name
## Instructions ## Instructions
Provide clear, step-by-step guidance for Claude. Clear, step-by-step guidance.
## Examples ## 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 | | Field | Required | Description |
|-------|----------|-------------| |-------|----------|-------------|
| `name` | Yes | Skill name using lowercase letters, numbers, and hyphens only (max 64 characters). Should match the directory name. | | `name` | No | Display name. Lowercase letters, numbers, hyphens only (max 64 chars). Defaults to directory name if omitted. |
| `description` | Yes | What the Skill does and when to use it (max 1024 characters). Claude uses this to decide when to apply the Skill. | | `description` | Recommended | What it does AND when to use it (max 1024 chars). 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` | | `argument-hint` | No | Hint shown during autocomplete. Example: `[issue-number]` or `[filename] [format]` |
| `model` | No | Specific model to use when this Skill is active (e.g., `claude-sonnet-4-20250514`). Defaults to the conversation's model. | | `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 ## Skill Locations & Priority
@@ -40,146 +60,75 @@ Enterprise (highest priority) → Personal → Project → Plugin (lowest priori
| Type | Path | Applies to | | Type | Path | Applies to |
|------|------|-----------| |------|------|-----------|
| **Enterprise** | See managed settings | All users in organization | | Enterprise | See managed settings | All users in organization |
| **Personal** | `~/.claude/skills/` | You, across all projects | | Personal | `~/.claude/skills/<name>/SKILL.md` | You, across all projects |
| **Project** | `.claude/skills/` | Anyone working in repository | | Project | `.claude/skills/<name>/SKILL.md` | Anyone working in repository |
| **Plugin** | Bundled with plugins | Anyone with plugin installed | | 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 ## How Skills Work
1. **Discovery**: Claude loads only name and description at startup 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 asks for confirmation 2. **Activation**: When your request matches a skill's description, Claude loads the full content
3. **Execution**: Claude follows the Skill's instructions and loads referenced files 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/ my-skill/
├── SKILL.md (required - overview and navigation) ├── SKILL.md # Entry point (required)
├── reference.md (detailed API docs - loaded when needed) ├── reference.md # Detailed docs (loaded when needed)
├── examples.md (usage examples - loaded when needed) ├── examples.md # Usage examples (loaded when needed)
└── scripts/ └── 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 ```markdown
--- For API details, see [reference.md](reference.md).
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 form filling, see [FORMS.md](FORMS.md). ## Running in a Subagent
For detailed API reference, see [REFERENCE.md](REFERENCE.md).
## Requirements Add `context: fork` to run in isolation:
Packages must be installed:
```bash
pip install pypdf pdfplumber
```
```
## Restricting Tool Access
```yaml ```yaml
--- ---
name: reading-files-safely name: deep-research
description: Read files without making changes. Use when you need read-only file access. description: Research a topic thoroughly
allowed-tools: Read, Grep, Glob context: fork
--- agent: Explore
```
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.
--- ---
# Generating Commit Messages Research $ARGUMENTS thoroughly...
## 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
``` ```
## Complete Example: Code Explanation Skill The skill content becomes the subagent's prompt. It won't have access to conversation history.
```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.
```
## Distribution ## Distribution
- **Project Skills**: Commit `.claude/skills/` to version control - **Project skills**: Commit `.claude/skills/` to version control
- **Plugins**: Add `skills/` directory to plugin with Skill folders - **Plugins**: Add `skills/` directory to plugin
- **Enterprise**: Deploy organization-wide through managed settings - **Enterprise**: Deploy organization-wide through managed settings

436
plugins/compound-engineering/skills/create-agent-skills/references/skill-structure.md
View File

@@ -1,372 +1,152 @@
<overview> # Skill Structure Reference
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>
<xml_structure_requirements> Skills have three structural components: YAML frontmatter (metadata), standard markdown body (content), and progressive disclosure (file organization).
<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>
<required_tags> ## Body Format
Every skill MUST have these three tags:
- **`<objective>`** - What the skill does and why it matters (1-3 paragraphs) Use **standard markdown headings** for structure. Keep markdown formatting within content (bold, italic, lists, code blocks, links).
- **`<quick_start>`** - Immediate, actionable guidance (minimal working example)
- **`<success_criteria>`** or **`<when_successful>`** - How to know it worked
</required_tags>
<conditional_tags> ```markdown
Add based on skill complexity and domain requirements: ---
name: my-skill
description: What it does and when to use it
---
- **`<context>`** - Background/situational information # Skill Name
- **`<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
See [use-xml-tags.md](use-xml-tags.md) for detailed guidance on each tag. ## Quick Start
</conditional_tags> Immediate actionable guidance...
<tag_selection_intelligence> ## Instructions
**Simple skills** (single domain, straightforward): Step-by-step procedures...
- Required tags only
- Example: Text extraction, file format conversion
**Medium skills** (multiple patterns, some complexity): ## Examples
- Required tags + workflow/examples as needed Concrete usage examples...
- Example: Document processing with steps, API integration
**Complex skills** (multiple domains, security, APIs): ## Guidelines
- Required tags + conditional tags as appropriate Rules and constraints...
- 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>
``` ```
Always close tags: ## Recommended Sections
```xml
<objective>
Content here
</objective>
```
</xml_nesting>
<tag_naming_conventions> Every skill should have:
Use descriptive, semantic names:
- `<workflow>` not `<steps>`
- `<success_criteria>` not `<done>`
- `<anti_patterns>` not `<dont_do>`
Be consistent within your skill. If you use `<workflow>`, don't also use `<process>` for the same purpose (unless they serve different roles). - **Quick Start** - Immediate, actionable guidance (minimal working example)
</tag_naming_conventions> - **Instructions** - Core step-by-step guidance
</xml_structure_requirements> - **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 ```yaml
--- ---
name: skill-name-here 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> ### Name Field
**Validation rules**:
**Validation rules:**
- Maximum 64 characters - Maximum 64 characters
- Lowercase letters, numbers, hyphens only - Lowercase letters, numbers, hyphens only
- No XML tags - Must match directory name
- No reserved words: "anthropic", "claude" - No reserved words: "anthropic", "claude"
- Must match directory name exactly
**Examples**: **Examples:**
- ✅ `process-pdfs` - `triage-prs`
- ✅ `manage-facebook-ads` - `deploy-production`
- ✅ `setup-stripe-payments` - `review-code`
- ❌ `PDF_Processor` (uppercase) - `setup-stripe-payments`
- ❌ `helper` (vague)
- ❌ `claude-helper` (reserved word)
</name_field>
<description_field> **Avoid:** `helper`, `utils`, `tools`, generic names
**Validation rules**:
- Non-empty, maximum 1024 characters ### Description Field
- No XML tags
- Third person (never first or second person) **Validation rules:**
- Maximum 1024 characters
- Include what it does AND when to use it - Include what it does AND when to use it
- Third person voice
**Critical rule**: Always write in third person. **Good:**
- ✅ "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**:
```yaml ```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. 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 **Bad:**
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**:
```yaml ```yaml
description: Helps with documents description: Helps with documents
``` ```
```yaml ### Optional Fields
description: Processes data
| 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> **Rules:**
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
- Keep references one level deep from SKILL.md - Keep references one level deep from SKILL.md
- Add table of contents to reference files over 100 lines - 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"> ## Validation Checklist
Quick start in SKILL.md, details in reference files:
```markdown Before finalizing:
---
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.
---
<objective> - [ ] YAML frontmatter valid (name matches directory, description specific)
Extract text and tables from PDF files, fill forms, and merge documents using Python libraries. - [ ] Uses standard markdown headings (not XML tags)
</objective> - [ ] 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> ## Anti-Patterns
Extract text with pdfplumber:
```python - **XML tags in body** - Use standard markdown headings
import pdfplumber - **Vague descriptions** - Be specific with trigger keywords
with pdfplumber.open("file.pdf") as pdf: - **Deep nesting** - Keep references one level from SKILL.md
text = pdf.pages[0].extract_text() - **Missing invocation control** - Side-effect workflows need `disable-model-invocation: true`
``` - **Inconsistent naming** - Directory name must match `name` field
</quick_start> - **Windows paths** - Always use forward slashes
<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>