feat(create-agent-skills): rewrite to match Anthropic official spec
The previous version incorrectly recommended XML tags for skill body content. Anthropic's official specification uses standard markdown headings. Changes: - SKILL.md: Complete rewrite using markdown format, not XML tags - Added references/official-spec.md from code.claude.com/docs/en/skills - Added references/best-practices.md from platform.claude.com - Removed obsolete use-xml-tags.md - Updated naming to gerund form (creating-agent-skills) - Descriptions now third person with "what" and "when" BREAKING: If you followed the old XML tag guidance, convert to markdown headings. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Kieran Klaassen
@@ -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
|
||||
|
||||
<details>
|
||||
<summary>Legacy v1 API (deprecated 2025-08)</summary>
|
||||
The v1 API used: `api.example.com/v1/messages`
|
||||
</details>
|
||||
```
|
||||
|
||||
### 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
|
||||
Reference in New Issue
Block a user