diff --git a/plugins/compound-engineering/.claude-plugin/plugin.json b/plugins/compound-engineering/.claude-plugin/plugin.json index 42dcd9d..4364758 100644 --- a/plugins/compound-engineering/.claude-plugin/plugin.json +++ b/plugins/compound-engineering/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "compound-engineering", - "version": "2.19.0", + "version": "2.20.0", "description": "AI-powered development tools. 27 agents, 20 commands, 13 skills, 2 MCP servers for code review, research, design, and workflow automation.", "author": { "name": "Kieran Klaassen", diff --git a/plugins/compound-engineering/CHANGELOG.md b/plugins/compound-engineering/CHANGELOG.md index 04cf86a..2e8b283 100644 --- a/plugins/compound-engineering/CHANGELOG.md +++ b/plugins/compound-engineering/CHANGELOG.md @@ -5,6 +5,24 @@ All notable changes to the compound-engineering plugin will be documented in thi The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [2.20.0] - 2026-01-01 + +### Changed + +- **`create-agent-skills` skill** - Complete rewrite to match Anthropic's official skill specification: + - **Format change**: Skills now use standard markdown headings (`## Quick Start`, `## Instructions`), NOT XML tags. The previous version incorrectly recommended XML tags which is not the official format. + - **Naming convention**: Updated to use gerund form (`creating-agent-skills`, `processing-pdfs`) per official spec + - **Description format**: Must be third person, include both what and when to use + - Added `references/official-spec.md` - Anthropic's official skill specification from code.claude.com/docs/en/skills + - Added `references/best-practices.md` - Skill authoring best practices from platform.claude.com + - Removed obsolete `references/use-xml-tags.md` - this was incorrect guidance + +### Philosophy + +This update aligns the skill with Anthropic's official documentation. The key insight: **Skills are prompts**. All standard prompting best practices apply. Use standard markdown, not custom XML tags. Keep SKILL.md under 500 lines with progressive disclosure to reference files. + +--- + ## [2.19.0] - 2025-12-31 ### Added diff --git a/plugins/compound-engineering/skills/create-agent-skills/SKILL.md b/plugins/compound-engineering/skills/create-agent-skills/SKILL.md index 8962cef..fe69023 100644 --- a/plugins/compound-engineering/skills/create-agent-skills/SKILL.md +++ b/plugins/compound-engineering/skills/create-agent-skills/SKILL.md @@ -1,192 +1,299 @@ --- -name: create-agent-skills -description: This skill provides expert guidance for creating, writing, building, and refining Claude Code Skills. It should be used when working with SKILL.md files, authoring new skills, improving existing skills, or understanding skill structure and best practices. +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. --- - -## How Skills Work +# Creating Agent Skills -Skills are modular, filesystem-based capabilities that provide domain expertise on demand. This skill teaches how to create effective skills. +This skill teaches how to create effective Claude Code Skills following Anthropic's official specification. + +## Core Principles ### 1. Skills Are Prompts -All prompting best practices apply. Be clear, be direct, use XML structure. Assume Claude is smart - only add context Claude doesn't have. +All prompting best practices apply. Be clear, be direct. Assume Claude is smart - only add context Claude doesn't have. -### 2. SKILL.md Is Always Loaded +### 2. Standard Markdown Format -When a skill is invoked, Claude reads SKILL.md. Use this guarantee: -- Essential principles go in SKILL.md (can't be skipped) -- Workflow-specific content goes in workflows/ -- Reusable knowledge goes in references/ +Use YAML frontmatter + markdown body. **No XML tags** - use standard markdown headings. -### 3. Router Pattern for Complex Skills +```markdown +--- +name: my-skill-name +description: What it does and when to use it +--- -``` -skill-name/ -├── SKILL.md # Router + principles -├── workflows/ # Step-by-step procedures (FOLLOW) -├── references/ # Domain knowledge (READ) -├── templates/ # Output structures (COPY + FILL) -└── scripts/ # Reusable code (EXECUTE) +# My Skill Name + +## Quick Start +Immediate actionable guidance... + +## Instructions +Step-by-step procedures... + +## Examples +Concrete usage examples... ``` -SKILL.md asks "what do you want to do?" → routes to workflow → workflow specifies which references to read. +### 3. Progressive Disclosure -**When to use each folder:** -- **workflows/** - Multi-step procedures Claude follows -- **references/** - Domain knowledge Claude reads for context -- **templates/** - Consistent output structures Claude copies and fills (plans, specs, configs) -- **scripts/** - Executable code Claude runs as-is (deploy, setup, API calls) +Keep SKILL.md under 500 lines. Split detailed content into reference files. Load only what's needed. -### 4. Pure XML Structure - -No markdown headings (#, ##, ###) in skill body. Use semantic XML tags: -```xml -... -... -... +``` +my-skill/ +├── SKILL.md # Entry point (required) +├── reference.md # Detailed docs (loaded when needed) +├── examples.md # Usage examples +└── scripts/ # Utility scripts (executed, not loaded) ``` -Keep markdown formatting within content (bold, lists, code blocks). +### 4. Effective Descriptions -### 5. Progressive Disclosure +The description field enables skill discovery. Include both what the skill does AND when to use it. Write in third person. -SKILL.md under 500 lines. Split detailed content into reference files. Load only what's needed for the current workflow. - +**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. +``` - -What would you like to do? +**Bad:** +```yaml +description: Helps with documents +``` -1. Create new skill -2. Audit/modify existing skill -3. Add component (workflow/reference/template/script) -4. Get guidance +## Skill Structure -**Wait for response before proceeding.** - +### Required Frontmatter - -| Response | Next Action | Workflow | -|----------|-------------|----------| -| 1, "create", "new", "build" | Ask: "Task-execution skill or domain expertise skill?" | Route to appropriate create workflow | -| 2, "audit", "modify", "existing" | Ask: "Path to skill?" | Route to appropriate workflow | -| 3, "add", "component" | Ask: "Add what? (workflow/reference/template/script)" | workflows/add-{type}.md | -| 4, "guidance", "help" | General guidance | workflows/get-guidance.md | +| 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 | -**Progressive disclosure for option 1 (create):** -- If user selects "Task-execution skill" → workflows/create-new-skill.md -- If user selects "Domain expertise skill" → workflows/create-domain-expertise-skill.md +### Naming Conventions -**Progressive disclosure for option 3 (add component):** -- If user specifies workflow → workflows/add-workflow.md -- If user specifies reference → workflows/add-reference.md -- If user specifies template → workflows/add-template.md -- If user specifies script → workflows/add-script.md +Use **gerund form** (verb + -ing) for skill names: -**Intent-based routing (if user provides clear intent without selecting menu):** -- "audit this skill", "check skill", "review" → workflows/audit-skill.md -- "verify content", "check if current" → workflows/verify-skill.md -- "create domain expertise", "exhaustive knowledge base" → workflows/create-domain-expertise-skill.md -- "create skill for X", "build new skill" → workflows/create-new-skill.md -- "add workflow", "add reference", etc. → workflows/add-{type}.md -- "upgrade to router" → workflows/upgrade-to-router.md +- `processing-pdfs` +- `analyzing-spreadsheets` +- `generating-commit-messages` +- `reviewing-code` -**After reading the workflow, follow it exactly.** - +Avoid: `helper`, `utils`, `tools`, `anthropic-*`, `claude-*` - -## Skill Structure Quick Reference +### 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 + +## Creating a New Skill + +### Step 1: Choose Type **Simple skill (single file):** -```yaml +- Under 500 lines +- Self-contained guidance +- No complex workflows + +**Progressive disclosure skill (multiple files):** +- SKILL.md as overview +- Reference files for detailed docs +- Scripts for utilities + +### Step 2: Create SKILL.md + +```markdown --- -name: skill-name -description: What it does and when to use it. +name: your-skill-name +description: [What it does]. Use when [trigger conditions]. --- -What this skill does -Immediate actionable guidance -Step-by-step procedure -How to know it worked +# Your Skill Name + +## Quick Start + +[Immediate actionable example] + +```[language] +[Code example] ``` -**Complex skill (router pattern):** +## Instructions + +[Core guidance] + +## Examples + +**Example 1:** +Input: [description] +Output: ``` -SKILL.md: - - Always applies - - Question to ask - - Maps answers to workflows - -workflows/: - - Which refs to load - - Steps - - Done when... - -references/: - Domain knowledge, patterns, examples - -templates/: - Output structures Claude copies and fills - (plans, specs, configs, documents) - -scripts/: - Executable code Claude runs as-is - (deploy, setup, API calls, data processing) -``` - - - -## Domain Knowledge - -All in `references/`: - -- **Structure:** [recommended-structure.md](./references/recommended-structure.md), [skill-structure.md](./references/skill-structure.md) -- **Principles:** [core-principles.md](./references/core-principles.md), [be-clear-and-direct.md](./references/be-clear-and-direct.md), [use-xml-tags.md](./references/use-xml-tags.md) -- **Patterns:** [common-patterns.md](./references/common-patterns.md), [workflows-and-validation.md](./references/workflows-and-validation.md) -- **Assets:** [using-templates.md](./references/using-templates.md), [using-scripts.md](./references/using-scripts.md) -- **Advanced:** [executable-code.md](./references/executable-code.md), [api-security.md](./references/api-security.md), [iteration-and-testing.md](./references/iteration-and-testing.md) - - - -## Workflows - -All in `workflows/`: - -| Workflow | Purpose | -|----------|---------| -| create-new-skill.md | Build a skill from scratch | -| create-domain-expertise-skill.md | Build exhaustive domain knowledge base for build/ | -| audit-skill.md | Analyze skill against best practices | -| verify-skill.md | Check if content is still accurate | -| add-workflow.md | Add a workflow to existing skill | -| add-reference.md | Add a reference to existing skill | -| add-template.md | Add a template to existing skill | -| add-script.md | Add a script to existing skill | -| upgrade-to-router.md | Convert simple skill to router pattern | -| get-guidance.md | Help decide what kind of skill to build | - - - -## YAML Frontmatter - -Required fields: -```yaml ---- -name: skill-name # lowercase-with-hyphens, matches directory -description: ... # What it does AND when to use it (third person) ---- +[result] ``` -Name conventions: `create-*`, `manage-*`, `setup-*`, `generate-*`, `build-*` - +## Guidelines + +- [Constraint 1] +- [Constraint 2] +``` + +### 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). +``` + +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 + +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 + +## Auditing Existing Skills + +Check against this rubric: + +- [ ] Valid YAML frontmatter (name + description) +- [ ] Description includes trigger keywords +- [ ] Uses standard markdown headings (not XML tags) +- [ ] SKILL.md under 500 lines +- [ ] References one level deep +- [ ] 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. +``` + +## Anti-Patterns to Avoid + +- **XML tags in body** - Use markdown headings instead +- **Vague descriptions** - Be specific with trigger keywords +- **Deep nesting** - Keep references one level from SKILL.md +- **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 + +## Reference Files + +For detailed guidance, see: + +- [official-spec.md](references/official-spec.md) - Anthropic's official skill specification +- [best-practices.md](references/best-practices.md) - Skill authoring best practices + +## Success Criteria - A well-structured skill: -- Has valid YAML frontmatter -- Uses pure XML structure (no markdown headings in body) -- Has essential principles inline in SKILL.md -- Routes directly to appropriate workflows based on user intent +- Has valid YAML frontmatter with descriptive name and description +- Uses standard markdown headings (not XML tags) - Keeps SKILL.md under 500 lines -- Asks minimal clarifying questions only when truly needed +- 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) diff --git a/plugins/compound-engineering/skills/create-agent-skills/references/best-practices.md b/plugins/compound-engineering/skills/create-agent-skills/references/best-practices.md new file mode 100644 index 0000000..23c7639 --- /dev/null +++ b/plugins/compound-engineering/skills/create-agent-skills/references/best-practices.md @@ -0,0 +1,404 @@ +# Skill Authoring Best Practices + +Source: [platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) + +## Core Principles + +### Concise is Key + +The context window is a public good. Your Skill shares the context window with everything else Claude needs to know. + +**Default assumption**: Claude is already very smart. Only add context Claude doesn't already have. + +Challenge each piece of information: +- "Does Claude really need this explanation?" +- "Can I assume Claude knows this?" +- "Does this paragraph justify its token cost?" + +**Good example (concise, ~50 tokens):** +```markdown +## Extract PDF text + +Use pdfplumber for text extraction: + +```python +import pdfplumber +with pdfplumber.open("file.pdf") as pdf: + text = pdf.pages[0].extract_text() +``` +``` + +**Bad example (too verbose, ~150 tokens):** +```markdown +## Extract PDF text + +PDF (Portable Document Format) files are a common file format that contains +text, images, and other content. To extract text from a PDF, you'll need to +use a library. There are many libraries available... +``` + +### Set Appropriate Degrees of Freedom + +Match specificity to task fragility and variability. + +**High freedom** (multiple valid approaches): +```markdown +## Code review process + +1. Analyze the code structure and organization +2. Check for potential bugs or edge cases +3. Suggest improvements for readability +4. Verify adherence to project conventions +``` + +**Medium freedom** (preferred pattern with variation): +```markdown +## Generate report + +Use this template and customize as needed: + +```python +def generate_report(data, format="markdown"): + # Process data + # Generate output in specified format +``` +``` + +**Low freedom** (fragile, exact sequence required): +```markdown +## Database migration + +Run exactly this script: + +```bash +python scripts/migrate.py --verify --backup +``` + +Do not modify the command or add flags. +``` + +### Test With All Models + +Skills act as additions to models. Test with Haiku, Sonnet, and Opus. + +- **Haiku**: Does the Skill provide enough guidance? +- **Sonnet**: Is the Skill clear and efficient? +- **Opus**: Does the Skill avoid over-explaining? + +## Naming Conventions + +Use **gerund form** (verb + -ing) for Skill names: + +**Good:** +- `processing-pdfs` +- `analyzing-spreadsheets` +- `managing-databases` +- `testing-code` +- `writing-documentation` + +**Acceptable alternatives:** +- Noun phrases: `pdf-processing`, `spreadsheet-analysis` +- Action-oriented: `process-pdfs`, `analyze-spreadsheets` + +**Avoid:** +- Vague: `helper`, `utils`, `tools` +- Generic: `documents`, `data`, `files` +- Reserved: `anthropic-*`, `claude-*` + +## Writing Effective Descriptions + +**Always write in third person.** The description is injected into the system prompt. + +**Be specific and include key terms:** + +```yaml +# PDF Processing skill +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. + +# Excel Analysis skill +description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files. + +# Git Commit Helper skill +description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes. +``` + +**Avoid vague descriptions:** +```yaml +description: Helps with documents # Too vague! +description: Processes data # Too generic! +description: Does stuff with files # Useless! +``` + +## Progressive Disclosure Patterns + +### Pattern 1: High-level guide with references + +```markdown +--- +name: pdf-processing +description: Extracts text and tables from PDF files, fills forms, merges documents. +--- + +# PDF Processing + +## Quick start + +```python +import pdfplumber +with pdfplumber.open("file.pdf") as pdf: + text = pdf.pages[0].extract_text() +``` + +## Advanced features + +**Form filling**: See [FORMS.md](FORMS.md) +**API reference**: See [REFERENCE.md](REFERENCE.md) +**Examples**: See [EXAMPLES.md](EXAMPLES.md) +``` + +### Pattern 2: Domain-specific organization + +``` +bigquery-skill/ +├── SKILL.md (overview and navigation) +└── reference/ + ├── finance.md (revenue, billing) + ├── sales.md (opportunities, pipeline) + ├── product.md (API usage, features) + └── marketing.md (campaigns, attribution) +``` + +### Pattern 3: Conditional details + +```markdown +# DOCX Processing + +## Creating documents + +Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md). + +## Editing documents + +For simple edits, modify the XML directly. + +**For tracked changes**: See [REDLINING.md](REDLINING.md) +**For OOXML details**: See [OOXML.md](OOXML.md) +``` + +## Keep References One Level Deep + +Claude may partially read files when they're referenced from other referenced files. + +**Bad (too deep):** +```markdown +# SKILL.md +See [advanced.md](advanced.md)... + +# advanced.md +See [details.md](details.md)... + +# details.md +Here's the actual information... +``` + +**Good (one level deep):** +```markdown +# SKILL.md + +**Basic usage**: [in SKILL.md] +**Advanced features**: See [advanced.md](advanced.md) +**API reference**: See [reference.md](reference.md) +**Examples**: See [examples.md](examples.md) +``` + +## Workflows and Feedback Loops + +### Workflow with Checklist + +```markdown +## Research synthesis workflow + +Copy this checklist: + +``` +- [ ] Step 1: Read all source documents +- [ ] Step 2: Identify key themes +- [ ] Step 3: Cross-reference claims +- [ ] Step 4: Create structured summary +- [ ] Step 5: Verify citations +``` + +**Step 1: Read all source documents** + +Review each document in `sources/`. Note main arguments. +... +``` + +### Feedback Loop Pattern + +```markdown +## Document editing process + +1. Make your edits to `word/document.xml` +2. **Validate immediately**: `python scripts/validate.py unpacked_dir/` +3. If validation fails: + - Review the error message + - Fix the issues + - Run validation again +4. **Only proceed when validation passes** +5. Rebuild: `python scripts/pack.py unpacked_dir/ output.docx` +``` + +## Common Patterns + +### Template Pattern + +```markdown +## Report structure + +Use this template: + +```markdown +# [Analysis Title] + +## Executive summary +[One-paragraph overview] + +## Key findings +- Finding 1 with supporting data +- Finding 2 with supporting data + +## Recommendations +1. Specific actionable recommendation +2. Specific actionable recommendation +``` +``` + +### Examples Pattern + +```markdown +## Commit message format + +**Example 1:** +Input: Added user authentication with JWT tokens +Output: +``` +feat(auth): implement JWT-based authentication + +Add login endpoint and token validation middleware +``` + +**Example 2:** +Input: Fixed bug where dates displayed incorrectly +Output: +``` +fix(reports): correct date formatting in timezone conversion +``` +``` + +### Conditional Workflow Pattern + +```markdown +## Document modification + +1. Determine the modification type: + + **Creating new content?** → Follow "Creation workflow" + **Editing existing?** → Follow "Editing workflow" + +2. Creation workflow: + - Use docx-js library + - Build document from scratch + +3. Editing workflow: + - Unpack existing document + - Modify XML directly + - Validate after each change +``` + +## Content Guidelines + +### Avoid Time-Sensitive Information + +**Bad:** +```markdown +If you're doing this before August 2025, use the old API. +``` + +**Good:** +```markdown +## Current method + +Use the v2 API endpoint: `api.example.com/v2/messages` + +## Old patterns + +
+Legacy v1 API (deprecated 2025-08) +The v1 API used: `api.example.com/v1/messages` +
+``` + +### Use Consistent Terminology + +**Good - Consistent:** +- Always "API endpoint" +- Always "field" +- Always "extract" + +**Bad - Inconsistent:** +- Mix "API endpoint", "URL", "API route", "path" +- Mix "field", "box", "element", "control" + +## Anti-Patterns to Avoid + +### Windows-Style Paths + +- **Good**: `scripts/helper.py`, `reference/guide.md` +- **Avoid**: `scripts\helper.py`, `reference\guide.md` + +### Too Many Options + +**Bad:** +```markdown +You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or... +``` + +**Good:** +```markdown +Use pdfplumber for text extraction: +```python +import pdfplumber +``` + +For scanned PDFs requiring OCR, use pdf2image with pytesseract instead. +``` + +## Checklist for Effective Skills + +### Core Quality +- [ ] Description is specific and includes key terms +- [ ] Description includes both what and when +- [ ] SKILL.md body under 500 lines +- [ ] Additional details in separate files +- [ ] No time-sensitive information +- [ ] Consistent terminology +- [ ] Examples are concrete +- [ ] References one level deep +- [ ] Progressive disclosure used appropriately +- [ ] Workflows have clear steps + +### Code and Scripts +- [ ] Scripts handle errors explicitly +- [ ] No "voodoo constants" (all values justified) +- [ ] Required packages listed +- [ ] Scripts have clear documentation +- [ ] No Windows-style paths +- [ ] Validation steps for critical operations +- [ ] Feedback loops for quality-critical tasks + +### Testing +- [ ] At least three test scenarios +- [ ] Tested with Haiku, Sonnet, and Opus +- [ ] Tested with real usage scenarios +- [ ] Team feedback incorporated diff --git a/plugins/compound-engineering/skills/create-agent-skills/references/official-spec.md b/plugins/compound-engineering/skills/create-agent-skills/references/official-spec.md new file mode 100644 index 0000000..59bdeab --- /dev/null +++ b/plugins/compound-engineering/skills/create-agent-skills/references/official-spec.md @@ -0,0 +1,185 @@ +# Anthropic Official Skill Specification + +Source: [code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills) + +## SKILL.md File Structure + +Every Skill requires a `SKILL.md` file with YAML frontmatter followed by Markdown instructions. + +### Basic Format + +```markdown +--- +name: your-skill-name +description: Brief description of what this Skill does and when to use it +--- + +# Your Skill Name + +## Instructions +Provide clear, step-by-step guidance for Claude. + +## Examples +Show concrete examples of using this Skill. +``` + +## Required Frontmatter Fields + +| 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. | + +## Skill Locations & Priority + +``` +Enterprise (highest priority) → Personal → Project → Plugin (lowest priority) +``` + +| Type | Path | Applies to | +|------|------|-----------| +| **Enterprise** | See managed settings | All users in organization | +| **Personal** | `~/.claude/skills/` | You, across all projects | +| **Project** | `.claude/skills/` | Anyone working in repository | +| **Plugin** | Bundled with plugins | Anyone with plugin installed | + +## 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 + +**Key Principle**: Skills are **model-invoked** — Claude automatically decides which Skills to use based on your request. + +## Progressive Disclosure Pattern + +Keep `SKILL.md` under 500 lines by linking to supporting files: + +``` +my-skill/ +├── SKILL.md (required - overview and navigation) +├── reference.md (detailed API docs - loaded when needed) +├── examples.md (usage examples - loaded when needed) +└── scripts/ + └── helper.py (utility script - executed, not loaded) +``` + +### Example SKILL.md with References + +```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 form filling, see [FORMS.md](FORMS.md). +For detailed API reference, see [REFERENCE.md](REFERENCE.md). + +## Requirements + +Packages must be installed: +```bash +pip install pypdf pdfplumber +``` +``` + +## Restricting Tool Access + +```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. +--- + +# 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 +``` + +## 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. +``` + +## Distribution + +- **Project Skills**: Commit `.claude/skills/` to version control +- **Plugins**: Add `skills/` directory to plugin with Skill folders +- **Enterprise**: Deploy organization-wide through managed settings diff --git a/plugins/compound-engineering/skills/create-agent-skills/references/use-xml-tags.md b/plugins/compound-engineering/skills/create-agent-skills/references/use-xml-tags.md deleted file mode 100644 index 3b585cf..0000000 --- a/plugins/compound-engineering/skills/create-agent-skills/references/use-xml-tags.md +++ /dev/null @@ -1,466 +0,0 @@ - -Skills use pure XML structure for consistent parsing, efficient token usage, and improved Claude performance. This reference defines the required and conditional XML tags for skill authoring, along with intelligence rules for tag selection. - - - -**Remove ALL markdown headings (#, ##, ###) from skill body content.** Replace with semantic XML tags. Keep markdown formatting WITHIN content (bold, italic, lists, code blocks, links). - - - -Every skill MUST have these three tags: - - -**Purpose**: What the skill does and why it matters. Sets context and scope. - -**Content**: 1-3 paragraphs explaining the skill's purpose, domain, and value proposition. - -**Example**: -```xml - -Extract text and tables from PDF files, fill forms, and merge documents using Python libraries. This skill provides patterns for common PDF operations without requiring external services or APIs. - -``` - - - -**Purpose**: Immediate, actionable guidance. Gets Claude started quickly without reading advanced sections. - -**Content**: Minimal working example, essential commands, or basic usage pattern. - -**Example**: -```xml - -Extract text with pdfplumber: - -```python -import pdfplumber -with pdfplumber.open("file.pdf") as pdf: - text = pdf.pages[0].extract_text() -``` - -``` - - - -**Purpose**: How to know the task worked. Defines completion criteria. - -**Alternative name**: `` (use whichever fits better) - -**Content**: Clear criteria for successful execution, validation steps, or expected outputs. - -**Example**: -```xml - -A well-structured skill has: - -- Valid YAML frontmatter with descriptive name and description -- Pure XML structure with no markdown headings in body -- Required tags: objective, quick_start, success_criteria -- Progressive disclosure (SKILL.md < 500 lines, details in reference files) -- Real-world testing and iteration based on observed behavior - -``` - - - - -Add these tags based on skill complexity and domain requirements: - - -**When to use**: Background or situational information that Claude needs before starting. - -**Example**: -```xml - -The Facebook Marketing API uses a hierarchy: Account → Campaign → Ad Set → Ad. Each level has different configuration options and requires specific permissions. Always verify API access before making changes. - -``` - - - -**When to use**: Step-by-step procedures, sequential operations, multi-step processes. - -**Alternative name**: `` - -**Example**: -```xml - -1. **Analyze the form**: Run analyze_form.py to extract field definitions -2. **Create field mapping**: Edit fields.json with values -3. **Validate mapping**: Run validate_fields.py -4. **Fill the form**: Run fill_form.py -5. **Verify output**: Check generated PDF - -``` - - - -**When to use**: Deep-dive topics that most users won't need (progressive disclosure). - -**Example**: -```xml - -**Custom styling**: See [styling.md](styling.md) -**Template inheritance**: See [templates.md](templates.md) -**API reference**: See [reference.md](reference.md) - -``` - - - -**When to use**: Skills with verification steps, quality checks, or validation scripts. - -**Example**: -```xml - -After making changes, validate immediately: - -```bash -python scripts/validate.py output_dir/ -``` - -Only proceed when validation passes. If errors occur, review and fix before continuing. - -``` - - - -**When to use**: Multi-shot learning, input/output pairs, demonstrating patterns. - -**Example**: -```xml - - -User clicked signup button -track('signup_initiated', { source: 'homepage' }) - - - -Purchase completed -track('purchase', { value: 49.99, currency: 'USD' }) - - -``` - - - -**When to use**: Common mistakes that Claude should avoid. - -**Example**: -```xml - - -- ❌ "Helps with documents" -- ✅ "Extract text and tables from PDF files" - - - -- ❌ "You can use pypdf, or pdfplumber, or PyMuPDF..." -- ✅ "Use pdfplumber for text extraction. For OCR, use pytesseract instead." - - -``` - - - -**When to use**: Skills with security implications (API keys, payments, authentication). - -**Example**: -```xml - -- Never log API keys or tokens -- Always use environment variables for credentials -- Validate all user input before API calls -- Use HTTPS for all external requests -- Check API response status before proceeding - -``` - - - -**When to use**: Testing workflows, test patterns, or validation steps. - -**Example**: -```xml - -Test with all target models (Haiku, Sonnet, Opus): - -1. Run skill on representative tasks -2. Observe where Claude struggles or succeeds -3. Iterate based on actual behavior -4. Validate XML structure after changes - -``` - - - -**When to use**: Code examples, recipes, or reusable patterns. - -**Example**: -```xml - - -```python -try: - result = process_file(path) -except FileNotFoundError: - print(f"File not found: {path}") -except Exception as e: - print(f"Error: {e}") -``` - - -``` - - - -**When to use**: Links to detailed reference files (progressive disclosure). - -**Alternative name**: `` - -**Example**: -```xml - -For deeper topics, see reference files: - -**API operations**: [references/api-operations.md](references/api-operations.md) -**Security patterns**: [references/security.md](references/security.md) -**Troubleshooting**: [references/troubleshooting.md](references/troubleshooting.md) - -``` - - - - - -**Simple skills** (single domain, straightforward): -- Required tags only: objective, quick_start, success_criteria -- Example: Text extraction, file format conversion, simple calculations - -**Medium skills** (multiple patterns, some complexity): -- Required tags + workflow/examples as needed -- Example: Document processing with steps, API integration with configuration - -**Complex skills** (multiple domains, security, APIs): -- Required tags + conditional tags as appropriate -- Example: Payment processing, authentication systems, multi-step workflows with validation - - - -Don't over-engineer simple skills. Don't under-specify complex skills. Match tag selection to actual complexity and user needs. - - - -Ask these questions: - -- **Context needed?** → Add `` -- **Multi-step process?** → Add `` or `` -- **Advanced topics to hide?** → Add `` + reference files -- **Validation required?** → Add `` -- **Pattern demonstration?** → Add `` -- **Common mistakes?** → Add `` -- **Security concerns?** → Add `` -- **Testing guidance?** → Add `` -- **Code recipes?** → Add `` -- **Deep references?** → Add `` - - - - - -XML tags are more efficient than markdown headings: - -**Markdown headings**: -```markdown -## Quick start -## Workflow -## Advanced features -## Success criteria -``` -Total: ~20 tokens, no semantic meaning to Claude - -**XML tags**: -```xml - - - - -``` -Total: ~15 tokens, semantic meaning built-in - - - -XML provides unambiguous boundaries and semantic meaning. Claude can reliably: -- Identify section boundaries -- Understand content purpose -- Skip irrelevant sections -- Parse programmatically - -Markdown headings are just visual formatting. Claude must infer meaning from heading text. - - - -XML enforces consistent structure across all skills. All skills use the same tag names for the same purposes. Makes it easier to: -- Validate skill structure programmatically -- Learn patterns across skills -- Maintain consistent quality - - - - - -XML tags can nest for hierarchical content: - -```xml - - -User input here -Expected output here - - - -Another input -Another output - - -``` - - - -Always close tags properly: - -✅ Good: -```xml - -Content here - -``` - -❌ Bad: -```xml - -Content here -``` - - - -Use descriptive, semantic names: -- `` not `` -- `` not `` -- `` not `` - -Be consistent within your skill. If you use ``, don't also use `` for the same purpose. - - - - -**DO NOT use markdown headings in skill body content.** - -❌ Bad (hybrid approach): -```markdown -# PDF Processing - -## Quick start - -Extract text with pdfplumber... - -## Advanced features - -Form filling... -``` - -✅ Good (pure XML): -```markdown - -PDF processing with text extraction, form filling, and merging. - - - -Extract text with pdfplumber... - - - -Form filling... - -``` - - - - -Clearly separate different sections with unambiguous boundaries - - - -Reduce parsing errors. Claude knows exactly where sections begin and end. - - - -Easily find, add, remove, or modify sections without rewriting - - - -Programmatically extract specific sections for validation or analysis - - - -Lower token usage compared to markdown headings - - - -Standardized structure across all skills in the ecosystem - - - - -XML tags work well with other prompting techniques: - -**Multi-shot learning**: -```xml - -... -... - -``` - -**Chain of thought**: -```xml - -Analyze the problem... - - - -Based on the analysis... - -``` - -**Template provision**: -```xml - -``` - -**Reference material**: -```xml - -{ - "field": "type" -} - -``` - - - -When referencing content in tags, use the tag name: - -"Using the schema in `` tags..." -"Follow the workflow in ``..." -"See examples in ``..." - -This makes the structure self-documenting. -