flowmade-one/architecture
3
0
Fork 0
Code Issues 15 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

feat(skills): modernize capability-writing with Anthropic best practices

Browse Source 
Updates capability-writing skill with progressive disclosure structure based on
Anthropic's January 2025 documentation. Implements Haiku-first approach (12x
cheaper, 2-5x faster than Sonnet).

Key changes:
- Add 5 core principles: conciseness, progressive disclosure, script bundling,
  degrees of freedom, and Haiku-first model selection
- Restructure with best-practices.md, templates/, examples/, and reference/
- Create 4 templates: user-invocable skill, background skill, agent, helper script
- Add 3 examples: simple workflow, progressive disclosure, with scripts
- Add 3 reference docs: frontmatter fields, model selection, anti-patterns
- Update create-capability to analyze complexity and recommend structures
- Default all new skills/agents to Haiku unless justified

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Hugo Nijhuis
2026-01-11 18:10:53 +01:00
parent 7406517cd9
commit f424a7f992
13 changed files with 2612 additions and 229 deletions
Download Patch File Download Diff File Expand all files Collapse all files

364
skills/capability-writing/SKILL.md
View File

@@ -10,7 +10,101 @@ user-invocable: false
# Capability Writing
How to design and create capabilities for the architecture repository. A capability may be a single component or a cohesive set (skill + agent).
How to design and create capabilities for the architecture repository using Anthropic's latest best practices (January 2025).
## Core Principles (NEW)
### 1. Conciseness is Critical
**Default assumption: Claude already knows.**
- Don't explain git, tea, standard CLI tools
- Don't explain concepts Claude understands
- Only add domain-specific context
- Keep main SKILL.md under 500 lines
**Bad:** "Git is a version control system. The commit command saves changes..."
**Good:** "`git commit -m 'feat: add feature'`"
### 2. Progressive Disclosure
Skills can bundle reference files and scripts that load/execute on-demand:
```
skill-name/
├── SKILL.md # Main workflow (200-500 lines)
├── best-practices.md # Detailed guidance (loaded when referenced)
├── examples/
│ ├── example1.md
│ └── example2.md
├── reference/
│ ├── api-docs.md
│ └── checklists.md
└── scripts/ # Bundled with this skill
├── validate.sh # Executed, not loaded into context
└── process.sh
```
**Benefits:**
- Main SKILL.md stays concise
- Reference files load only when Claude references them
- Scripts execute without consuming context tokens
- Each skill is self-contained
### 3. Script Bundling
Bundle error-prone bash operations as scripts within the skill:
**Instead of inline bash:**
```markdown
5. Create PR: `tea pulls create --title "..." --description "..."`
```
**Bundle a script:**
```markdown
5. **Create PR**: `./scripts/create-pr.sh $issue "$title"`
```
```bash
# In skill-name/scripts/create-pr.sh
#!/bin/bash
set -e
# Script handles errors, retries, validation
```
**When to bundle scripts:**
- Operations with complex error handling
- Operations that need retries
- Operations with multiple validation steps
- Fragile bash operations
### 4. Degrees of Freedom
Match instruction style to task fragility:
| Degree | When | Example |
|--------|------|---------|
| **High** (text) | Multiple valid approaches | "Review code quality and suggest improvements" |
| **Medium** (template) | Preferred pattern with variation | "Use this template, customize as needed" |
| **Low** (script) | Fragile operation, exact sequence | "Run: `./scripts/validate.sh`" |
### 5. Model Selection (UPDATED)
**New guidance:** Default to Haiku, justify if not.
| Model | Use When | Cost vs Haiku |
|-------|----------|---------------|
| **Haiku** | Simple workflows, validated steps, with scripts | Baseline |
| **Sonnet** | When Haiku testing shows <80% success rate | 12x more expensive |
| **Opus** | Deep reasoning, architectural judgment | 60x more expensive |
**Haiku works well when:**
- Steps are simple and validated
- Instructions are concise
- Error-prone operations use scripts
- Outputs have structured templates
**Test with Haiku first.** Only upgrade if needed.
## Component Overview
@@ -40,41 +134,12 @@ Start here: What do you need?
--> Full capability (background skill + user-invocable skill + agent)
```
### Decision Matrix
| Need | Component | Example |
|------|-----------|---------|
| Knowledge Claude applies automatically | Background skill | gitea, issue-writing |
| User-invoked workflow | User-invocable skill | /work-issue, /dashboard |
| Isolated subtask with focused context | Agent | code-reviewer, issue-worker |
| All three working together | Full capability | architecture review |
### Signs You Need Each Component
**Create a Background Skill when:**
- You explain the same concepts repeatedly
- Quality is inconsistent without explicit guidance
- Multiple user-invocable skills need the same knowledge
- There is a clear domain that doesn't fit existing skills
**Create a User-Invocable Skill when:**
- Same workflow is used multiple times
- User explicitly triggers the action
- Approval checkpoints are needed
- Multiple tools need orchestration
**Create an Agent when:**
- Task requires deep exploration that would pollute main context
- Multiple skills work better together
- Batch processing or parallel execution is needed
- Specialist persona improves outputs
**Detailed decision criteria:** See [best-practices.md](best-practices.md)
## Component Templates
### User-Invocable Skill Template
Location: `skills/<name>/SKILL.md`
```yaml
---
name: skill-name
@@ -99,22 +164,10 @@ Brief intro if needed.
5. **Present results** with links and summary
```
**Frontmatter fields:**
| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Lowercase, hyphens, matches directory name |
| `description` | Yes | What it does + when to use (max 1024 chars) |
| `user-invocable` | Yes | Set `true` for user-triggered workflows |
| `argument-hint` | No | Shows expected args: `<required>`, `[optional]` |
| `model` | No | `haiku`, `sonnet`, `opus` |
| `context` | No | Use `fork` for isolated context |
| `allowed-tools` | No | Restrict available tools |
**Complete template with all fields:** See [templates/user-invocable-skill.md](templates/user-invocable-skill.md)
### Background Skill Template
Location: `skills/<name>/SKILL.md`
```yaml
---
name: skill-name
@@ -129,130 +182,87 @@ user-invocable: false
Brief description of what this skill covers.
## Core Concepts
Explain fundamental ideas Claude needs to understand.
## Patterns and Templates
Provide reusable structures and formats.
## Guidelines
List rules, best practices, and quality standards.
## Examples
Show concrete illustrations of the skill in action.
## Common Mistakes
Document pitfalls to avoid.
## Reference
Quick-reference tables, checklists, or commands.
```
### Agent Template
**Complete template:** See [templates/background-skill.md](templates/background-skill.md)
Location: `agents/<name>/AGENT.md`
### Agent Template
```yaml
---
name: agent-name
description: What this agent does and when to spawn it
model: sonnet
model: haiku
skills: skill1, skill2
disallowedTools:
- Edit
- Edit # For read-only agents
- Write
---
You are a [role] specialist that [primary function].
## When Invoked
Describe the process the agent follows:
1. **Gather context**: What information to collect
2. **Analyze**: What to evaluate
3. **Act**: What actions to take
4. **Report**: How to communicate results
## Output Format
Describe expected output structure.
## Guidelines
- Behavioral rules
- Constraints
- Quality standards
1. **Gather context**
2. **Analyze**
3. **Act**
4. **Report**
```
**Frontmatter fields:**
**Complete template:** See [templates/agent.md](templates/agent.md)
| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Lowercase, hyphens, matches directory name |
| `description` | Yes | What it does + when to spawn |
| `model` | No | `haiku`, `sonnet`, `opus`, or `inherit` |
| `skills` | No | Comma-separated skill names (not paths) |
| `disallowedTools` | No | Tools to block (e.g., Edit, Write for read-only) |
| `permissionMode` | No | `default` or `bypassPermissions` |
**Helper script template:** See [templates/helper-script.sh](templates/helper-script.sh)
## Model Selection Guidance
## Structure Examples
| Model | Use When | Examples |
|-------|----------|----------|
| `haiku` | Simple fetch/display, formatting, mechanical tasks | /dashboard, /roadmap |
| `sonnet` | Most skills and agents, balanced performance | /work-issue, code-reviewer |
| `opus` | Deep reasoning, architectural analysis, complex judgment | /arch-review-repo |
### Simple Skill (< 300 lines, no scripts)
```
skills/simple-skill/
└── SKILL.md
```
### Decision Criteria
### Progressive Disclosure (with reference files)
```
skills/complex-skill/
├── SKILL.md (~200 lines)
├── reference/
│ ├── detailed-guide.md
│ └── api-reference.md
└── examples/
└── usage-examples.md
```
- **Start with `haiku`** for simple display/fetch workflows
- **Use `sonnet`** for most skills and agents (default choice)
- **Reserve `opus` for judgment** - when errors are costly or reasoning is complex
- **Consider the stakes** - higher consequence tasks warrant more capable models
### With Bundled Scripts
```
skills/skill-with-scripts/
├── SKILL.md
├── reference/
│ └── error-handling.md
└── scripts/
├── validate.sh
└── process.sh
```
## Naming Conventions
### File and Folder Names
| Component | Convention | Examples |
|-----------|------------|----------|
| Skill folder | kebab-case | `software-architecture`, `work-issue` |
| Skill file | UPPERCASE | `SKILL.md` |
| Agent folder | kebab-case | `code-reviewer`, `issue-worker` |
| Agent file | UPPERCASE | `AGENT.md` |
### Naming Patterns
**Skills:** Name after the domain, knowledge area, or action
- Good: `gitea`, `issue-writing`, `work-issue`, `dashboard`
- Bad: `utils`, `helpers`, `misc`
**Agents:** Name by role or persona (recognizable specialist)
- Good: `code-reviewer`, `issue-worker`, `software-architect`
- Bad: `helper`, `do-stuff`, `agent1`
**Detailed examples:** See [examples/](examples/) folder
## Referencing Skills
### In User-Invocable Skills
Use the `@` file reference syntax to guarantee background skill content is loaded:
Use `@` file reference syntax to guarantee background skill content is loaded:
```markdown
@~/.claude/skills/gitea/SKILL.md
@~/.claude/skills/issue-writing/SKILL.md
```
**Important:** Do NOT use phrases like "Use the gitea skill" - skills have only ~20% auto-activation rate. File references guarantee the content is available.
**Important:** Do NOT use phrases like "Use the gitea skill" - file references guarantee the content is available.
### In Agents
List skill names in the frontmatter (not paths):
List skill names in frontmatter (not paths):
```yaml
---
@@ -261,24 +271,16 @@ skills: gitea, issue-writing, backlog-grooming
---
```
The agent runtime loads these skills automatically.
## Common Patterns
### Approval Workflow (User-Invocable Skills)
Always ask before significant actions:
### Approval Workflow
```markdown
4. **Present plan** for approval
5. **If approved**, create the issues
6. **Present summary** with links
```
### Conditional Behavior (User-Invocable Skills)
Handle optional arguments with mode switching:
### Conditional Behavior
```markdown
## If issue number provided ($1):
1. Fetch specific issue
@@ -289,18 +291,12 @@ Handle optional arguments with mode switching:
2. Process each
```
### Spawning Agents from Skills
Delegate complex subtasks:
### Spawning Agents
```markdown
9. **Auto-review**: Spawn the `code-reviewer` agent with the PR number
```
### Read-Only Agents
For analysis without modification:
```yaml
---
name: code-reviewer
@@ -310,73 +306,24 @@ disallowedTools:
---
```
## Anti-Patterns to Avoid
## Quick Reference
### Overly Broad Components
**Frontmatter fields:** See [reference/frontmatter-fields.md](reference/frontmatter-fields.md)
**Model selection:** See [reference/model-selection.md](reference/model-selection.md)
**Anti-patterns:** See [reference/anti-patterns.md](reference/anti-patterns.md)
**Best practices:** See [best-practices.md](best-practices.md)
**Bad:** One skill/agent that does everything
```markdown
# Project Management
Handles issues, PRs, releases, documentation, deployment...
```
## Naming Conventions
**Good:** Focused components with clear responsibility
```markdown
# Issue Writing
How to write clear, actionable issues.
```
| Component | Convention | Examples |
|-----------|------------|----------|
| Skill folder | kebab-case | `software-architecture`, `work-issue` |
| Skill file | UPPERCASE | `SKILL.md` |
| Agent folder | kebab-case | `code-reviewer`, `issue-worker` |
| Agent file | UPPERCASE | `AGENT.md` |
### Vague Instructions
**Bad:**
```markdown
1. Handle the issue
2. Do the work
3. Finish up
```
**Good:**
```markdown
1. **View the issue** with `--comments` flag
2. **Create branch**: `git checkout -b issue-$1-<title>`
3. **Commit** with message referencing the issue
```
### Missing Skill References
**Bad:**
```markdown
Use the gitea skill to create an issue.
```
**Good:**
```markdown
@~/.claude/skills/gitea/SKILL.md
Use `tea issues create --title "..." --description "..."`
```
### God Skills
**Bad:** Single skill with 1000+ lines covering unrelated topics
**Good:** Multiple focused skills that reference each other
### Premature Agent Creation
**Bad:** Creating an agent for every task
**Good:** Use agents only when you need:
- Context isolation
- Skill composition
- Parallel execution
- Specialist persona
## Detailed Documentation
For comprehensive guides, see:
- `docs/writing-capabilities.md` - Complete guide covering skills and agents
**Skills:** Name after domain/action (good: `gitea`, `work-issue`; bad: `utils`, `helpers`)
**Agents:** Name by role/persona (good: `code-reviewer`; bad: `helper`, `agent1`)
## Checklists
@@ -390,6 +337,7 @@ For comprehensive guides, see:
- [ ] Background skills referenced via `@~/.claude/skills/<name>/SKILL.md`
- [ ] Approval checkpoints before significant actions
- [ ] File at `skills/<name>/SKILL.md`
- [ ] **Model defaults to `haiku`** unless justified
### Before Creating a Background Skill
@@ -405,6 +353,6 @@ For comprehensive guides, see:
- [ ] Built-in agents (Explore, Plan) are not sufficient
- [ ] Context isolation or skill composition is needed
- [ ] Clear role/persona emerges
- [ ] `model` selection is deliberate (not just `inherit`)
- [ ] `model` selection is deliberate (default to `haiku`)
- [ ] `skills` list is right-sized (not too many)
- [ ] File at `agents/<name>/AGENT.md`

500
skills/capability-writing/best-practices.md Normal file
View File

@@ -0,0 +1,500 @@
# Skill Authoring Best Practices
Based on Anthropic's latest agent skills documentation (January 2025).
## Core Principles
### Concise is Key
> "The context window is a public good. 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):**
```markdown
## Extract PDF text
Use pdfplumber:
\`\`\`python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
\`\`\`
```
**Bad example (verbose):**
```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 for PDF processing, but we recommend pdfplumber
because it's easy to use and handles most cases well. First, you'll need to install
it using pip. Then you can use the code below...
```
The concise version assumes Claude knows what PDFs are and how libraries work.
### Set Appropriate Degrees of Freedom
Match the level of specificity to the task's fragility and variability.
#### High Freedom (Text-Based Instructions)
Use when multiple approaches are valid:
```markdown
## Code Review Process
1. Analyze 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 (Templates/Pseudocode)
Use when there's a preferred pattern but variation is acceptable:
```markdown
## Generate Report
Use this template and customize as needed:
\`\`\`python
def generate_report(data, format="markdown", include_charts=True):
# Process data
# Generate output in specified format
# Optionally include visualizations
\`\`\`
```
#### Low Freedom (Exact Scripts)
Use when operations are fragile and error-prone:
```markdown
## Database Migration
Run exactly this script:
\`\`\`bash
python scripts/migrate.py --verify --backup
\`\`\`
Do not modify the command or add additional flags.
```
**Analogy:** Think of Claude as a robot exploring a path:
- **Narrow bridge with cliffs**: One safe way forward. Provide specific guardrails (low freedom)
- **Open field**: Many paths lead to success. Give general direction (high freedom)
### Progressive Disclosure
Split large skills into layers that load on-demand.
#### Three Levels of Loading
| Level | When Loaded | Token Cost | Content |
|-------|------------|------------|---------|
| **Level 1: Metadata** | Always (at startup) | ~100 tokens | `name` and `description` from frontmatter |
| **Level 2: Instructions** | When skill is triggered | Under 5k tokens | SKILL.md body with instructions |
| **Level 3: Resources** | As needed | Unlimited | Referenced files, scripts |
#### Organizing Large Skills
**Pattern 1: High-level guide with references**
```markdown
# 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)
```
Claude loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.
**Pattern 2: Domain-specific organization**
For skills with multiple domains:
```
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 `reference/finance.md`.
**Pattern 3: Conditional details**
```markdown
# DOCX Processing
## Creating Documents
Use docx-js. See [DOCX-JS.md](DOCX-JS.md).
## Editing Documents
For simple edits, modify XML directly.
**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)
```
#### Avoid Deeply Nested References
**Keep references one level deep from SKILL.md.**
**Bad (too deep):**
```
SKILL.md → advanced.md → details.md → actual info
```
**Good (one level):**
```
SKILL.md → {advanced.md, reference.md, examples.md}
```
#### Structure Longer Files with TOC
For reference files >100 lines, include a table of contents:
```markdown
# API Reference
## Contents
- Authentication and setup
- Core methods (create, read, update, delete)
- Advanced features (batch operations, webhooks)
- Error handling patterns
- Code examples
## Authentication and Setup
...
```
This ensures Claude can see the full scope even with partial reads.
## Script Bundling
### When to Bundle Scripts
Bundle scripts for:
- **Error-prone operations**: Complex bash with retry logic
- **Fragile sequences**: Operations requiring exact order
- **Validation steps**: Checking conditions before proceeding
- **Reusable utilities**: Operations used in multiple steps
**Benefits of bundled scripts:**
- More reliable than generated code
- Save tokens (no code in context)
- Save time (no code generation)
- Ensure consistency
### Script Structure
```bash
#!/bin/bash
# script-name.sh - Brief description
#
# Usage: script-name.sh <param1> <param2>
#
# Example: script-name.sh issue-42 "Fix bug"
set -e # Exit on error
# Input validation
if [ $# -lt 2 ]; then
echo "Usage: $0 <param1> <param2>"
exit 1
fi
param1=$1
param2=$2
# Main logic with error handling
if ! some_command; then
echo "ERROR: Command failed"
exit 1
fi
# Success output
echo "SUCCESS: Operation completed"
```
### Referencing Scripts in Skills
**Make clear whether to execute or read:**
**Execute (most common):**
```markdown
7. **Create PR**: `./scripts/create-pr.sh $1 "$title"`
```
**Read as reference (for understanding complex logic):**
```markdown
See `./scripts/analyze-form.py` for the field extraction algorithm
```
### Solving, Not Punting
Scripts should handle error conditions, not punt to Claude.
**Good (handles errors):**
```python
def process_file(path):
try:
with open(path) as f:
return f.read()
except FileNotFoundError:
print(f"File {path} not found, creating default")
with open(path, 'w') as f:
f.write('')
return ''
except PermissionError:
print(f"Cannot access {path}, using default")
return ''
```
**Bad (punts to Claude):**
```python
def process_file(path):
return open(path).read() # Fails, Claude has to figure it out
```
## Workflow Patterns
### Plan-Validate-Execute
Add verification checkpoints to catch errors early.
**Example: Workflow with validation**
```markdown
## PDF Form Filling
Copy this checklist:
\`\`\`
Progress:
- [ ] Step 1: Analyze form (run analyze_form.py)
- [ ] Step 2: Create field mapping (edit fields.json)
- [ ] Step 3: Validate mapping (run validate_fields.py)
- [ ] Step 4: Fill form (run fill_form.py)
- [ ] Step 5: Verify output (run verify_output.py)
\`\`\`
**Step 1: Analyze**
Run: `python scripts/analyze_form.py input.pdf`
**Step 2: Create Mapping**
Edit `fields.json`
**Step 3: Validate**
Run: `python scripts/validate_fields.py fields.json`
Fix any errors before continuing.
**Step 4: Fill**
Run: `python scripts/fill_form.py input.pdf fields.json output.pdf`
**Step 5: Verify**
Run: `python scripts/verify_output.py output.pdf`
If verification fails, return to Step 2.
```
### Feedback Loops
**Pattern:** Run validator → fix errors → repeat
**Example: Document editing**
```markdown
1. Make edits to `word/document.xml`
2. **Validate**: `python scripts/validate.py unpacked_dir/`
3. If validation fails:
- Review error message
- Fix issues
- Run validation again
4. **Only proceed when validation passes**
5. Rebuild: `python scripts/pack.py unpacked_dir/ output.docx`
6. Test output document
```
## Model Selection
### Decision Framework
```
Start with Haiku
|
v
Test on 3-5 representative tasks
|
+-- Success rate ≥80%? ---------> Use Haiku ✓
|
+-- Success rate <80%? --------> Try Sonnet
|
v
Test on same tasks
|
+-- Success ≥80%? --> Use Sonnet
|
+-- Still failing? --> Opus or redesign task
```
### Haiku Works Well When
- **Steps are simple and validated**
- **Instructions are concise** (no verbose explanations)
- **Error-prone operations use scripts** (deterministic)
- **Outputs have structured templates**
- **Checklists replace open-ended judgment**
### Testing with Multiple Models
Test skills with all models you plan to use:
1. **Create test cases:** 3-5 representative scenarios
2. **Run with Haiku:** Measure success rate, response quality
3. **Run with Sonnet:** Compare results
4. **Adjust instructions:** If Haiku struggles, add clarity or scripts
What works for Opus might need more detail for Haiku.
## Common Anti-Patterns
### Offering Too Many Options
**Bad (confusing):**
```markdown
You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or...
```
**Good (provide default):**
```markdown
Use pdfplumber for text extraction:
\`\`\`python
import pdfplumber
\`\`\`
For scanned PDFs requiring OCR, use pdf2image with pytesseract instead.
```
### Time-Sensitive Information
**Bad (will become wrong):**
```markdown
If you're doing this before August 2025, use the old API.
After August 2025, use the new API.
```
**Good (use "old patterns" section):**
```markdown
## Current Method
Use the v2 API: `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`
This endpoint is no longer supported.
</details>
```
### Inconsistent Terminology
**Good (consistent):**
- Always "API endpoint"
- Always "field"
- Always "extract"
**Bad (inconsistent):**
- Mix "API endpoint", "URL", "API route", "path"
- Mix "field", "box", "element", "control"
- Mix "extract", "pull", "get", "retrieve"
### Windows-Style Paths
Always use forward slashes:
- ✓ **Good**: `scripts/helper.py`, `reference/guide.md`
- ✗ **Bad**: `scripts\helper.py`, `reference\guide.md`
Unix-style paths work cross-platform.
## Iterative Development
### Build Evaluations First
Create test cases BEFORE extensive documentation:
1. **Identify gaps**: Run Claude on tasks without skill, document failures
2. **Create evaluations**: Build 3-5 test scenarios
3. **Establish baseline**: Measure Claude's performance without skill
4. **Write minimal instructions**: Just enough to pass evaluations
5. **Iterate**: Execute evaluations, refine
### Develop Iteratively with Claude
**Use Claude to help write skills:**
1. **Complete a task without skill**: Work through problem, note what context you provide
2. **Identify reusable pattern**: What context is useful for similar tasks?
3. **Ask Claude to create skill**: "Create a skill that captures this pattern"
4. **Review for conciseness**: Remove unnecessary explanations
5. **Test on similar tasks**: Use skill with fresh Claude instance
6. **Iterate based on observation**: Where does Claude struggle?
Claude understands skill format natively - no special prompts needed.
## Checklist for Effective Skills
**Before publishing:**
### Core Quality
- [ ] Description is specific and includes key terms
- [ ] Description includes what skill does AND when to use it
- [ ] SKILL.md body under 500 lines
- [ ] Additional details in separate files (if needed)
- [ ] No time-sensitive information
- [ ] Consistent terminology throughout
- [ ] Examples are concrete, not abstract
- [ ] File references are one level deep
- [ ] Progressive disclosure used appropriately
- [ ] Workflows have clear steps
### Code and Scripts
- [ ] Scripts solve problems, don't punt to Claude
- [ ] Error handling is explicit and helpful
- [ ] No "magic numbers" (all values justified)
- [ ] Required packages listed and verified
- [ ] Scripts have clear documentation
- [ ] No Windows-style paths (all forward slashes)
- [ ] Validation steps for critical operations
- [ ] Feedback loops for quality-critical tasks
### Testing
- [ ] At least 3 test cases created
- [ ] Tested with Haiku (if that's the target)
- [ ] Tested with real usage scenarios
- [ ] Team feedback incorporated (if applicable)

129
skills/capability-writing/examples/progressive-disclosure.md Normal file
View File

@@ -0,0 +1,129 @@
# Example: Progressive Disclosure Skill
A skill that uses reference files to keep the main SKILL.md concise.
## Structure
```
skills/database-query/
├── SKILL.md (~200 lines)
├── reference/
│ ├── schemas.md (table schemas)
│ ├── common-queries.md (frequently used queries)
│ └── optimization-tips.md (performance guidance)
└── examples/
├── simple-select.md
└── complex-join.md
```
## When to Use
- Skill content would be >500 lines
- Multiple domains or topics
- Reference documentation is large
- Want to keep main workflow concise
## Example: database-query (main SKILL.md)
```markdown
---
name: database-query
description: >
Help users query the PostgreSQL database with proper schemas and optimization.
Use when user needs to write SQL queries or mentions database/tables.
user-invocable: false
---
# Database Query Helper
Help write efficient, correct SQL queries for our PostgreSQL database.
## Quick Start
\`\`\`sql
SELECT id, name, created_at
FROM users
WHERE status = 'active'
LIMIT 10;
\`\`\`
## Table Schemas
We have 3 main schemas:
- **Users & Auth**: See [reference/schemas.md#users](reference/schemas.md#users)
- **Products**: See [reference/schemas.md#products](reference/schemas.md#products)
- **Orders**: See [reference/schemas.md#orders](reference/schemas.md#orders)
## Common Queries
For frequently requested queries, see [reference/common-queries.md](reference/common-queries.md):
- User activity reports
- Sales summaries
- Inventory status
## Writing Queries
1. **Identify tables**: Which schemas does this query need?
2. **Check schema**: Load relevant schema from reference
3. **Write query**: Use proper column names and types
4. **Optimize**: See [reference/optimization-tips.md](reference/optimization-tips.md)
## Examples
- **Simple select**: See [examples/simple-select.md](examples/simple-select.md)
- **Complex join**: See [examples/complex-join.md](examples/complex-join.md)
```
## Example: reference/schemas.md
```markdown
# Database Schemas
## Users
| Column | Type | Description |
|--------|------|-------------|
| id | UUID | Primary key |
| email | VARCHAR(255) | Unique email |
| name | VARCHAR(100) | Display name |
| status | ENUM('active','inactive','banned') | Account status |
| created_at | TIMESTAMP | Account creation |
| updated_at | TIMESTAMP | Last update |
## Products
| Column | Type | Description |
|--------|------|-------------|
| id | UUID | Primary key |
| name | VARCHAR(200) | Product name |
| price | DECIMAL(10,2) | Price in USD |
| inventory | INTEGER | Stock count |
| category_id | UUID | FK to categories |
## Orders
[...more tables...]
```
## Why This Works
- **Main file stays concise** (~200 lines)
- **Details load on-demand**: schemas.md loads when user asks about specific table
- **Fast for common cases**: Simple queries don't need reference files
- **Scalable**: Can add more schemas without bloating main file
## Loading Pattern
1. User: "Show me all active users"
2. Claude reads SKILL.md (sees Users schema reference)
3. Claude: "I'll load the users schema to get column names"
4. Claude reads reference/schemas.md#users
5. Claude writes correct query
## What Makes It Haiku-Friendly
- ✓ Main workflow is simple ("identify → check schema → write query")
- ✓ Reference files provide facts, not reasoning
- ✓ Clear pointers to where details are
- ✓ Examples show patterns

71
skills/capability-writing/examples/simple-workflow.md Normal file
View File

@@ -0,0 +1,71 @@
# Example: Simple Workflow Skill
A basic skill with just a SKILL.md file - no scripts or reference files needed.
## Structure
```
skills/list-open-prs/
└── SKILL.md
```
## When to Use
- Skill is simple (<300 lines)
- No error-prone bash operations
- No need for reference documentation
- Straightforward workflow
## Example: list-open-prs
```markdown
---
name: list-open-prs
description: >
List all open pull requests for the current repository.
Use when user wants to see PRs or says /list-open-prs.
model: haiku
user-invocable: true
---
# List Open PRs
@~/.claude/skills/gitea/SKILL.md
Show all open pull requests in the current repository.
## Process
1. **Get repository info**
- `git remote get-url origin`
- Parse owner/repo from URL
2. **Fetch open PRs**
- `tea pulls list --state open --output simple`
3. **Format results** as table
| PR # | Title | Author | Created |
|------|-------|--------|---------|
| ... | ... | ... | ... |
## Guidelines
- Show most recent PRs first
- Include link to each PR
- If no open PRs, say "No open pull requests"
```
## Why This Works
- **Concise**: Entire skill fits in ~30 lines
- **Simple commands**: Just git and tea CLI
- **No error handling needed**: tea handles errors gracefully
- **Structured output**: Table format is clear
## What Makes It Haiku-Friendly
- ✓ Simple sequential steps
- ✓ Clear commands with no ambiguity
- ✓ Structured output format
- ✓ No complex decision-making

210
skills/capability-writing/examples/with-scripts.md Normal file
View File

@@ -0,0 +1,210 @@
# Example: Skill with Bundled Scripts
A skill that bundles helper scripts for error-prone operations.
## Structure
```
skills/deploy-to-staging/
├── SKILL.md
├── reference/
│ └── rollback-procedure.md
└── scripts/
├── validate-build.sh
├── deploy.sh
└── health-check.sh
```
## When to Use
- Operations have complex error handling
- Need retry logic
- Multiple validation steps
- Fragile bash commands
## Example: deploy-to-staging (main SKILL.md)
```markdown
---
name: deploy-to-staging
description: >
Deploy current branch to staging environment with validation and health checks.
Use when deploying to staging or when user says /deploy-to-staging.
model: haiku
user-invocable: true
---
# Deploy to Staging
Deploy current branch to staging with automated validation and rollback capability.
## Process
1. **Validate build**
- `./scripts/validate-build.sh`
- Checks tests pass, linter clean, no uncommitted changes
2. **Show deployment plan** for approval
- Branch name
- Latest commit
- Services that will be updated
3. **If approved, deploy**
- `./scripts/deploy.sh staging $branch`
- Script handles Docker build, push, k8s apply
4. **Health check**
- `./scripts/health-check.sh staging`
- Verifies all services are healthy
5. **Report results**
- Deployment URL
- Status of each service
- Rollback command if needed
## Rollback
If deployment fails, see [reference/rollback-procedure.md](reference/rollback-procedure.md)
```
## Example: scripts/validate-build.sh
```bash
#!/bin/bash
# validate-build.sh - Pre-deployment validation
#
# Checks:
# - Tests pass
# - Linter clean
# - No uncommitted changes
# - Docker builds successfully
set -e
RED='\033[0;31m'
GREEN='\033[0;32m'
NC='\033[0m'
error() {
echo -e "${RED}ERROR: $1${NC}" >&2
exit 1
}
success() {
echo -e "${GREEN}✓ $1${NC}"
}
# Check 1: No uncommitted changes
if ! git diff-index --quiet HEAD --; then
error "Uncommitted changes detected. Commit or stash first."
fi
success "No uncommitted changes"
# Check 2: Tests pass
if ! npm test > /dev/null 2>&1; then
error "Tests failing. Fix tests before deploying."
fi
success "Tests pass"
# Check 3: Linter clean
if ! npm run lint > /dev/null 2>&1; then
error "Linter errors. Run 'npm run lint' to see details."
fi
success "Linter clean"
# Check 4: Docker builds
if ! docker build -t test-build . > /dev/null 2>&1; then
error "Docker build failed"
fi
success "Docker build successful"
echo ""
echo -e "${GREEN}✓ All validations passed${NC}"
```
## Example: scripts/deploy.sh
```bash
#!/bin/bash
# deploy.sh - Deploy to environment
#
# Usage: deploy.sh <environment> <branch>
# Example: deploy.sh staging feature-new-ui
set -e
ENVIRONMENT=$1
BRANCH=$2
if [ -z "$ENVIRONMENT" ] || [ -z "$BRANCH" ]; then
echo "Usage: $0 <environment> <branch>"
exit 1
fi
echo "Deploying $BRANCH to $ENVIRONMENT..."
# Build Docker image
docker build -t myapp:$BRANCH .
# Tag for registry
docker tag myapp:$BRANCH registry.example.com/myapp:$BRANCH
# Push to registry with retry
for i in {1..3}; do
if docker push registry.example.com/myapp:$BRANCH; then
break
fi
echo "Push failed, retrying ($i/3)..."
sleep 5
done
# Update Kubernetes deployment
kubectl set image deployment/myapp \
myapp=registry.example.com/myapp:$BRANCH \
-n $ENVIRONMENT
# Wait for rollout
kubectl rollout status deployment/myapp -n $ENVIRONMENT --timeout=5m
echo "Deployment complete!"
echo "URL: https://$ENVIRONMENT.example.com"
```
## Why This Works
**Script benefits:**
- **Deterministic**: Same behavior every time
- **Error handling**: Retries, clear messages
- **Validation**: Pre-flight checks prevent bad deployments
- **No token cost**: Scripts execute without loading code into context
**Skill stays simple:**
- Main SKILL.md is ~30 lines
- Just calls scripts in order
- No complex bash logic inline
- Easy to test scripts independently
## What Makes It Haiku-Friendly
- ✓ Skill has simple instructions ("run script X, then Y")
- ✓ Scripts handle all complexity
- ✓ Clear success/failure from script exit codes
- ✓ Validation prevents ambiguous states
- ✓ Structured output from scripts is easy to parse
## Testing Scripts
Scripts can be tested independently:
```bash
# Test validation
./scripts/validate-build.sh
# Test deployment (dry-run)
./scripts/deploy.sh staging test-branch --dry-run
# Test health check
./scripts/health-check.sh staging
```
This makes the skill more reliable than inline bash.

536
skills/capability-writing/reference/anti-patterns.md Normal file
View File

@@ -0,0 +1,536 @@
# Anti-Patterns to Avoid
Common mistakes when creating skills and agents.
## Skill Design Anti-Patterns
### 1. Overly Broad Components
**Bad:** One skill that does everything
```yaml
---
name: project-management
description: Handles issues, PRs, releases, documentation, deployment, testing, CI/CD...
---
# Project Management
This skill does:
- Issue management
- Pull request reviews
- Release planning
- Documentation
- Deployment
- Testing
- CI/CD configuration
...
```
**Why it's bad:**
- Huge context window usage
- Hard to maintain
- Unclear when to trigger
- Tries to do too much
**Good:** Focused components
```yaml
---
name: issue-writing
description: How to write clear, actionable issues with acceptance criteria.
---
```
**Separate skills for:**
- `issue-writing` - Issue quality
- `review-pr` - PR reviews
- `gitea` - CLI reference
- Each does one thing well
---
### 2. Vague Instructions
**Bad:**
```markdown
1. Handle the issue
2. Do the work
3. Finish up
4. Let me know when done
```
**Why it's bad:**
- No clear actions
- Claude has to guess
- Inconsistent results
- Hard to validate
**Good:**
```markdown
1. **View issue**: `tea issues $1 --comments`
2. **Create branch**: `git checkout -b issue-$1-<title>`
3. **Plan work**: Use TodoWrite to break down steps
4. **Implement**: Make necessary changes
5. **Commit**: `git commit -m "feat: ..."`
6. **Create PR**: `tea pulls create --title "..." --description "..."`
```
---
### 3. Missing Skill References
**Bad:**
```markdown
Use the gitea skill to create an issue.
```
**Why it's bad:**
- Skills have ~20% auto-activation rate
- Claude might not load the skill
- Inconsistent results
**Good:**
```markdown
@~/.claude/skills/gitea/SKILL.md
Use `tea issues create --title "..." --description "..."`
```
**The `@` reference guarantees the skill content is loaded.**
---
### 4. God Skills
**Bad:** Single 1500-line skill covering everything
```
skills/database/SKILL.md (1500 lines)
- PostgreSQL
- MySQL
- MongoDB
- Redis
- All queries
- All optimization tips
- All schemas
```
**Why it's bad:**
- Exceeds recommended 500 lines
- Loads everything even if you need one thing
- Hard to maintain
- Wastes tokens
**Good:** Progressive disclosure
```
skills/database/
├── SKILL.md (200 lines - overview)
├── reference/
│ ├── postgres.md
│ ├── mysql.md
│ ├── mongodb.md
│ └── redis.md
└── schemas/
├── users.md
├── products.md
└── orders.md
```
Claude loads only what's needed.
---
### 5. Premature Agent Creation
**Bad:** Creating an agent for every task
```
agents/
├── issue-viewer/
├── branch-creator/
├── commit-maker/
├── pr-creator/
└── readme-updater/
```
**Why it's bad:**
- Overhead of spawning agents
- Most tasks don't need isolation
- Harder to follow workflow
- Slower execution
**Good:** Use agents only when needed:
- Context isolation (parallel work)
- Skill composition (multiple skills together)
- Specialist persona (architecture review)
**Simple tasks → Skills**
**Complex isolated work → Agents**
---
### 6. Verbose Explanations
**Bad:**
```markdown
Git is a distributed version control system that was created by Linus Torvalds in 2005. It allows multiple developers to work on the same codebase simultaneously while maintaining a complete history of all changes. When you want to save your changes, you use the git commit command, which creates a snapshot of your current working directory...
```
**Why it's bad:**
- Wastes tokens
- Claude already knows git
- Slows down loading
- Adds no value
**Good:**
```markdown
`git commit -m 'feat: add feature'`
```
**Assume Claude is smart. Only add domain-specific context.**
---
## Instruction Anti-Patterns
### 7. Offering Too Many Options
**Bad:**
```markdown
You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or camelot, or tabula, or...
```
**Why it's bad:**
- Decision paralysis
- Inconsistent choices
- No clear default
**Good:**
```markdown
Use pdfplumber for text extraction:
\`\`\`python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
\`\`\`
For scanned PDFs requiring OCR, use pdf2image + pytesseract instead.
```
**Provide default, mention alternative only when needed.**
---
### 8. Time-Sensitive Information
**Bad:**
```markdown
If you're doing this before August 2025, use the old API.
After August 2025, use the new API.
```
**Why it's bad:**
- Will become wrong
- Requires maintenance
- Confusing after the date
**Good:**
```markdown
## Current Method
Use v2 API: `api.example.com/v2/messages`
## Old Patterns
<details>
<summary>Legacy v1 API (deprecated 2025-08)</summary>
The v1 API: `api.example.com/v1/messages`
No longer supported.
</details>
```
---
### 9. Inconsistent Terminology
**Bad:** Mixing terms for the same thing
```markdown
1. Get the API endpoint
2. Call the URL
3. Hit the API route
4. Query the path
```
**Why it's bad:**
- Confusing
- Looks like different things
- Harder to search
**Good:** Pick one term and stick with it
```markdown
1. Get the API endpoint
2. Call the API endpoint
3. Check the API endpoint response
4. Retry the API endpoint if needed
```
---
### 10. Windows-Style Paths
**Bad:**
```markdown
Run: `scripts\helper.py`
See: `reference\guide.md`
```
**Why it's bad:**
- Fails on Unix systems
- Causes errors on Mac/Linux
**Good:**
```markdown
Run: `scripts/helper.py`
See: `reference/guide.md`
```
**Always use forward slashes. They work everywhere.**
---
## Script Anti-Patterns
### 11. Punting to Claude
**Bad script:**
```python
def process_file(path):
return open(path).read() # Let Claude handle errors
```
**Why it's bad:**
- Script fails with no helpful message
- Claude has to guess what happened
- Inconsistent error handling
**Good script:**
```python
def process_file(path):
try:
with open(path) as f:
return f.read()
except FileNotFoundError:
print(f"ERROR: File {path} not found")
print("Creating default file...")
with open(path, 'w') as f:
f.write('')
return ''
except PermissionError:
print(f"ERROR: Cannot access {path}")
print("Using default value")
return ''
```
**Scripts should solve problems, not punt to Claude.**
---
### 12. Magic Numbers
**Bad:**
```bash
TIMEOUT=47 # Why 47?
RETRIES=5 # Why 5?
DELAY=3.7 # Why 3.7?
```
**Why it's bad:**
- No one knows why these values
- Hard to adjust
- "Voodoo constants"
**Good:**
```bash
# HTTP requests typically complete in <30s
# Extra buffer for slow connections
TIMEOUT=30
# Three retries balances reliability vs speed
# Most intermittent failures resolve by retry 2
RETRIES=3
# Exponential backoff: 1s, 2s, 4s
INITIAL_DELAY=1
```
**Document why each value is what it is.**
---
## Model Selection Anti-Patterns
### 13. Always Using Sonnet/Opus
**Bad:**
```yaml
---
name: dashboard
model: opus # "Just to be safe"
---
```
**Why it's bad:**
- 60x more expensive than Haiku
- 5x slower
- Wasted cost for simple task
**Good:**
```yaml
---
name: dashboard
model: haiku # Tested: 5/5 tests passed
---
```
**Test with Haiku first. Only upgrade if needed.**
---
### 14. Never Testing Haiku
**Bad:**
```yaml
---
name: review-pr
model: sonnet # Assumed it needs Sonnet, never tested Haiku
---
```
**Why it's bad:**
- Might work fine with Haiku
- Missing 12x cost savings
- Missing 2.5x speed improvement
**Good:**
```yaml
---
name: review-pr
model: haiku # Tested: Haiku 4/5 (80%), good enough!
---
```
Or:
```yaml
---
name: review-pr
model: sonnet # Tested: Haiku 2/5 (40%), Sonnet 4/5 (80%)
---
```
**Always test Haiku first, document results.**
---
## Progressive Disclosure Anti-Patterns
### 15. Deeply Nested References
**Bad:**
```
SKILL.md → advanced.md → details.md → actual-info.md
```
**Why it's bad:**
- Claude may partially read nested files
- Information might be incomplete
- Hard to navigate
**Good:**
```
SKILL.md → {advanced.md, reference.md, examples.md}
```
**Keep references one level deep from SKILL.md.**
---
### 16. No Table of Contents for Long Files
**Bad:** 500-line reference file with no structure
```markdown
# Reference
(500 lines of content with no navigation)
```
**Why it's bad:**
- Hard to preview
- Claude might miss sections
- User can't navigate
**Good:**
```markdown
# Reference
## Contents
- Authentication and setup
- Core methods
- Advanced features
- Error handling
- Examples
## Authentication and Setup
...
```
**Files >100 lines should have TOC.**
---
## Checklist to Avoid Anti-Patterns
Before publishing a skill:
- [ ] Not overly broad (does one thing well)
- [ ] Instructions are specific (not vague)
- [ ] Skill references use `@` syntax
- [ ] Under 500 lines (or uses progressive disclosure)
- [ ] Only creates agents when needed
- [ ] Concise (assumes Claude knows basics)
- [ ] Provides default, not 10 options
- [ ] No time-sensitive information
- [ ] Consistent terminology
- [ ] Forward slashes for paths
- [ ] Scripts handle errors, don't punt
- [ ] No magic numbers in scripts
- [ ] Tested with Haiku first
- [ ] References are one level deep
- [ ] Long files have table of contents

278
skills/capability-writing/reference/frontmatter-fields.md Normal file
View File

@@ -0,0 +1,278 @@
# Frontmatter Fields Reference
Complete documentation of all available frontmatter fields for skills and agents.
## Skill Frontmatter
### Required Fields
#### `name`
- **Type:** string
- **Required:** Yes
- **Format:** Lowercase, hyphens only, no spaces
- **Max length:** 64 characters
- **Must match:** Directory name
- **Cannot contain:** XML tags, reserved words ("anthropic", "claude")
- **Example:** `work-issue`, `code-review`, `gitea`
#### `description`
- **Type:** string (multiline supported with `>`)
- **Required:** Yes
- **Max length:** 1024 characters
- **Cannot contain:** XML tags
- **Should include:**
- What the skill does
- When to use it
- Trigger conditions
- **Example:**
```yaml
description: >
View, create, and manage Gitea issues and pull requests.
Use when working with issues, PRs, or when user mentions tea, gitea, issue numbers.
```
#### `user-invocable`
- **Type:** boolean
- **Required:** Yes
- **Values:** `true` or `false`
- **Usage:**
- `true`: User can trigger with `/skill-name`
- `false`: Background skill, auto-loaded when needed
### Optional Fields
#### `model`
- **Type:** string
- **Required:** No
- **Values:** `haiku`, `sonnet`, `opus`
- **Default:** Inherits from parent (usually haiku)
- **Guidance:** Default to `haiku`, only upgrade if needed
- **Example:**
```yaml
model: haiku # 12x cheaper than sonnet
```
#### `argument-hint`
- **Type:** string
- **Required:** No (only for user-invocable skills)
- **Format:** `<required>` for required params, `[optional]` for optional
- **Shows in UI:** Helps users know what arguments to provide
- **Example:**
```yaml
argument-hint: <issue-number>
argument-hint: <issue-number> [optional-title]
```
#### `context`
- **Type:** string
- **Required:** No
- **Values:** `fork`
- **Usage:** Set to `fork` for skills needing isolated context
- **When to use:** Heavy exploration tasks that would pollute main context
- **Example:**
```yaml
context: fork # For arch-review-repo, deep exploration
```
#### `allowed-tools`
- **Type:** list of strings
- **Required:** No
- **Usage:** Restrict which tools the skill can use
- **Example:**
```yaml
allowed-tools:
- Read
- Bash
- Grep
```
- **Note:** Rarely used, most skills have all tools
## Agent Frontmatter
### Required Fields
#### `name`
- **Type:** string
- **Required:** Yes
- **Same rules as skill name**
#### `description`
- **Type:** string
- **Required:** Yes
- **Should include:**
- What the agent does
- When to spawn it
- **Example:**
```yaml
description: >
Automated code review of pull requests for quality, bugs, security, and style.
Spawn when reviewing PRs or checking code quality.
```
### Optional Fields
#### `model`
- **Type:** string
- **Required:** No
- **Values:** `haiku`, `sonnet`, `opus`, `inherit`
- **Default:** `inherit` (uses parent's model)
- **Guidance:**
- Default to `haiku` for simple agents
- Use `sonnet` for balanced performance
- Reserve `opus` for deep reasoning
- **Example:**
```yaml
model: haiku # Fast and cheap for code review checklist
```
#### `skills`
- **Type:** comma-separated list of skill names (not paths)
- **Required:** No
- **Usage:** Auto-load these skills when agent spawns
- **Format:** Just skill names, not paths
- **Example:**
```yaml
skills: gitea, issue-writing, code-review
```
- **Note:** Agent runtime loads skills automatically
#### `disallowedTools`
- **Type:** list of tool names
- **Required:** No
- **Common use:** Make agents read-only
- **Example:**
```yaml
disallowedTools:
- Edit
- Write
```
- **When to use:** Analysis agents that shouldn't modify code
#### `permissionMode`
- **Type:** string
- **Required:** No
- **Values:** `default`, `bypassPermissions`
- **Usage:** Rarely used, for agents that need to bypass permission prompts
- **Example:**
```yaml
permissionMode: bypassPermissions
```
## Examples
### Minimal User-Invocable Skill
```yaml
---
name: dashboard
description: Show open issues, PRs, and CI status.
user-invocable: true
---
```
### Full-Featured Skill
```yaml
---
name: work-issue
description: >
Implement a Gitea issue with full workflow: branch, plan, code, PR, review.
Use when implementing issues or when user says /work-issue.
model: haiku
argument-hint: <issue-number>
user-invocable: true
---
```
### Background Skill
```yaml
---
name: gitea
description: >
View, create, and manage Gitea issues and PRs using tea CLI.
Use when working with issues, PRs, viewing issue details, or when user mentions tea, gitea, issue numbers.
user-invocable: false
---
```
### Read-Only Agent
```yaml
---
name: code-reviewer
description: >
Automated code review of pull requests for quality, bugs, security, style, and test coverage.
model: sonnet
skills: gitea, code-review
disallowedTools:
- Edit
- Write
---
```
### Implementation Agent
```yaml
---
name: issue-worker
description: >
Autonomously implements a single issue in an isolated git worktree.
model: haiku
skills: gitea, issue-writing, software-architecture
---
```
## Validation Rules
### Name Validation
- Must be lowercase
- Must use hyphens (not underscores or spaces)
- Cannot contain: `anthropic`, `claude`
- Cannot contain XML tags `<`, `>`
- Max 64 characters
- Must match directory name exactly
### Description Validation
- Cannot be empty
- Max 1024 characters
- Cannot contain XML tags
- Should end with period
### Model Validation
- Must be one of: `haiku`, `sonnet`, `opus`, `inherit`
- Case-sensitive (must be lowercase)
## Common Mistakes
**Bad: Using paths in skills field**
```yaml
skills: ~/.claude/skills/gitea/SKILL.md # Wrong!
```
**Good: Just skill names**
```yaml
skills: gitea, issue-writing
```
**Bad: Reserved word in name**
```yaml
name: claude-helper # Contains "claude"
```
**Good: Descriptive name**
```yaml
name: code-helper
```
**Bad: Vague description**
```yaml
description: Helps with stuff
```
**Good: Specific description**
```yaml
description: >
Analyze Excel spreadsheets, create pivot tables, generate charts.
Use when analyzing Excel files, spreadsheets, or .xlsx files.
```

336
skills/capability-writing/reference/model-selection.md Normal file
View File

@@ -0,0 +1,336 @@
# Model Selection Guide
Detailed guidance on choosing the right model for skills and agents.
## Cost Comparison
| Model | Input (per MTok) | Output (per MTok) | vs Haiku |
|-------|------------------|-------------------|----------|
| **Haiku** | $0.25 | $1.25 | Baseline |
| **Sonnet** | $3.00 | $15.00 | 12x more expensive |
| **Opus** | $15.00 | $75.00 | 60x more expensive |
**Example cost for typical skill call (2K input, 1K output):**
- Haiku: $0.00175
- Sonnet: $0.021 (12x more)
- Opus: $0.105 (60x more)
## Speed Comparison
| Model | Tokens/Second | vs Haiku |
|-------|---------------|----------|
| **Haiku** | ~100 | Baseline |
| **Sonnet** | ~40 | 2.5x slower |
| **Opus** | ~20 | 5x slower |
## Decision Framework
```
Start with Haiku by default
|
v
Test on 3-5 representative tasks
|
+-- Success rate ≥80%? ---------> ✓ Use Haiku
| (12x cheaper, 2-5x faster)
|
+-- Success rate <80%? --------> Try Sonnet
| |
| v
| Test on same tasks
| |
| +-- Success ≥80%? --> Use Sonnet
| |
| +-- Still failing? --> Opus or redesign
|
v
Document why you chose the model
```
## When Haiku Works Well
### ✓ Ideal for Haiku
**Simple sequential workflows:**
- `/dashboard` - Fetch and display
- `/roadmap` - List and format
- `/commit` - Generate message from diff
**Workflows with scripts:**
- Error-prone operations in scripts
- Skills just orchestrate script calls
- Validation is deterministic
**Structured outputs:**
- Tasks with clear templates
- Format is defined upfront
- No ambiguous formatting
**Reference/knowledge skills:**
- `gitea` - CLI reference
- `issue-writing` - Patterns and templates
- `software-architecture` - Best practices
### Examples of Haiku Success
**work-issue skill:**
- Sequential steps (view → branch → plan → implement → PR)
- Each step has clear validation
- Scripts handle error-prone operations
- Success rate: ~90%
**dashboard skill:**
- Fetch data (tea commands)
- Format as table
- Clear, structured output
- Success rate: ~95%
## When to Use Sonnet
### Use Sonnet When
**Haiku fails 20%+ of the time**
- Test with Haiku first
- If success rate <80%, upgrade to Sonnet
**Complex judgment required:**
- Code review (quality assessment)
- Issue grooming (clarity evaluation)
- Architecture decisions
**Nuanced reasoning:**
- Understanding implicit requirements
- Making trade-off decisions
- Applying context-dependent rules
### Examples of Sonnet Success
**review-pr skill:**
- Requires code understanding
- Judgment about quality/bugs
- Context-dependent feedback
- Originally tried Haiku: 65% success → Sonnet: 85%
**issue-worker agent:**
- Autonomous implementation
- Pattern matching
- Architectural decisions
- Originally tried Haiku: 70% success → Sonnet: 82%
## When to Use Opus
### Reserve Opus For
**Deep architectural reasoning:**
- `software-architect` agent
- Pattern recognition across large codebases
- Identifying subtle anti-patterns
- Trade-off analysis
**High-stakes decisions:**
- Breaking changes analysis
- System-wide refactoring plans
- Security architecture review
**Complex pattern recognition:**
- Requires sophisticated understanding
- Multiple layers of abstraction
- Long-term implications
### Examples of Opus Success
**software-architect agent:**
- Analyzes entire codebase
- Identifies 8 different anti-patterns
- Provides prioritized recommendations
- Sonnet: 68% success → Opus: 88%
**arch-review-repo skill:**
- Comprehensive architecture audit
- Cross-cutting concerns
- System-wide patterns
- Opus justified for depth
## Making Haiku More Effective
If Haiku is struggling, try these improvements **before** upgrading to Sonnet:
### 1. Add Validation Steps
**Instead of:**
```markdown
3. Implement changes and create PR
```
**Try:**
```markdown
3. Implement changes
4. Validate: Run `./scripts/validate.sh` (tests pass, linter clean)
5. Create PR: `./scripts/create-pr.sh`
```
### 2. Bundle Error-Prone Operations in Scripts
**Instead of:**
```markdown
5. Create PR: `tea pulls create --title "..." --description "..."`
```
**Try:**
```markdown
5. Create PR: `./scripts/create-pr.sh $issue "$title"`
```
### 3. Add Structured Output Templates
**Instead of:**
```markdown
Show the results
```
**Try:**
```markdown
Format results as:
| Issue | Status | Link |
|-------|--------|------|
| ... | ... | ... |
```
### 4. Add Explicit Checklists
**Instead of:**
```markdown
Review the code for quality
```
**Try:**
```markdown
Check:
- [ ] Code quality (readability, naming)
- [ ] Bugs (edge cases, null checks)
- [ ] Tests (coverage, assertions)
```
### 5. Make Instructions More Concise
**Instead of:**
```markdown
Git is a version control system. When you want to commit changes, you use the git commit command which saves your changes to the repository...
```
**Try:**
```markdown
`git commit -m 'feat: add feature'`
```
## Testing Methodology
### Create Test Suite
For each skill, create 3-5 test cases:
**Example: work-issue skill tests**
1. Simple bug fix issue
2. New feature with acceptance criteria
3. Issue missing acceptance criteria
4. Issue with tests that fail
5. Complex refactoring task
### Test with Haiku
```bash
# Set skill to Haiku
model: haiku
# Run all 5 tests
# Document success/failure for each
```
### Measure Success Rate
```
Success rate = (Successful tests / Total tests) × 100
```
**Decision:**
- ≥80% → Keep Haiku
- <80% → Try Sonnet
- <50% → Likely need Opus or redesign
### Test with Sonnet (if needed)
```bash
# Upgrade to Sonnet
model: sonnet
# Run same 5 tests
# Compare results
```
### Document Decision
```yaml
---
name: work-issue
model: haiku # Tested: 4/5 tests passed with Haiku (80%)
---
```
Or:
```yaml
---
name: review-pr
model: sonnet # Tested: Haiku 3/5 (60%), Sonnet 4/5 (80%)
---
```
## Common Patterns
### Pattern: Start Haiku, Upgrade if Needed
**Issue-worker agent evolution:**
1. **V1 (Haiku):** 70% success - struggled with pattern matching
2. **Analysis:** Added more examples, still 72%
3. **V2 (Sonnet):** 82% success - better code understanding
4. **Decision:** Keep Sonnet, document why
### Pattern: Haiku for Most, Sonnet for Complex
**Review-pr skill:**
- Static analysis steps: Haiku could handle
- Manual code review: Needs Sonnet judgment
- **Decision:** Use Sonnet for whole skill (simplicity)
### Pattern: Split Complex Skills
**Instead of:** One complex skill using Opus
**Try:** Split into:
- Haiku skill for orchestration
- Sonnet agent for complex subtask
- Saves cost (most work in Haiku)
## Model Selection Checklist
Before choosing a model:
- [ ] Tested with Haiku first
- [ ] Measured success rate on 3-5 test cases
- [ ] Tried improvements (scripts, validation, checklists)
- [ ] Documented why this model is needed
- [ ] Considered cost implications (12x/60x)
- [ ] Considered speed implications (2.5x/5x slower)
- [ ] Will re-test if Claude models improve
## Future-Proofing
**Models improve over time.**
Periodically re-test Sonnet/Opus skills with Haiku:
- Haiku v2 might handle what Haiku v1 couldn't
- Cost savings compound over time
- Speed improvements are valuable
**Set a reminder:** Test Haiku again in 3-6 months.

67
skills/capability-writing/templates/agent.md Normal file
View File

@@ -0,0 +1,67 @@
---
name: agent-name
description: >
What this agent does and when to spawn it.
Include specific conditions that indicate this agent is needed.
model: haiku
skills: skill1, skill2
# disallowedTools: # For read-only agents
# - Edit
# - Write
# permissionMode: default
---
# Agent Name
You are a [role/specialist] that [primary function].
## When Invoked
You are spawned when [specific conditions].
Follow this process:
1. **Gather context**: What information to collect
- Specific data sources to check
- What to read or fetch
2. **Analyze**: What to evaluate
- Criteria to check
- Standards to apply
3. **Act**: What actions to take
- Specific operations
- What to create or modify
4. **Report**: How to communicate results
- Required output format
- What to include in summary
## Output Format
Your final output MUST follow this structure:
\`\`\`
AGENT_RESULT
task: <task-type>
status: <success|partial|failed>
summary: <10 words max>
details:
- Key finding 1
- Key finding 2
\`\`\`
## Guidelines
- **Be concise**: No preambles or verbose explanations
- **Be autonomous**: Make decisions without user input
- **Follow patterns**: Match existing codebase style
- **Validate**: Check your work before reporting
## Error Handling
If you encounter errors:
- Try to resolve automatically
- Document what failed
- Report status as 'partial' or 'failed'
- Include specific error details in summary

69
skills/capability-writing/templates/background-skill.md Normal file
View File

@@ -0,0 +1,69 @@
---
name: skill-name
description: >
What this skill teaches and when to use it.
Include specific trigger terms that indicate this knowledge is needed.
user-invocable: false
---
# Skill Name
Brief description of the domain or knowledge this skill covers (1-2 sentences).
## Core Concepts
Fundamental ideas Claude needs to understand:
- Key concept 1
- Key concept 2
- Key concept 3
## Patterns and Templates
Reusable structures and formats:
### Pattern 1: Common Use Case
\`\`\`
Example code or structure
\`\`\`
### Pattern 2: Another Use Case
\`\`\`
Another example
\`\`\`
## Guidelines
Rules and best practices:
- Guideline 1
- Guideline 2
- Guideline 3
## Examples
### Example 1: Simple Case
\`\`\`
Concrete example showing the skill in action
\`\`\`
### Example 2: Complex Case
\`\`\`
More advanced example
\`\`\`
## Common Mistakes
Pitfalls to avoid:
- **Mistake 1**: Why it's wrong and what to do instead
- **Mistake 2**: Why it's wrong and what to do instead
## Reference
Quick-reference tables or checklists:
| Command | Purpose | Example |
|---------|---------|---------|
| ... | ... | ... |

86
skills/capability-writing/templates/helper-script.sh Normal file
View File

@@ -0,0 +1,86 @@
#!/bin/bash
# script-name.sh - Brief description of what this script does
#
# Usage: script-name.sh <param1> <param2> [optional-param]
#
# Example:
# script-name.sh value1 value2
# script-name.sh value1 value2 optional-value
#
# Exit codes:
# 0 - Success
# 1 - Invalid arguments or general error
# 2 - Specific error condition (document what)
set -e # Exit immediately on error
# set -x # Uncomment for debugging
# Color output for better visibility
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color
# Helper functions
error() {
echo -e "${RED}ERROR: $1${NC}" >&2
exit 1
}
success() {
echo -e "${GREEN}SUCCESS: $1${NC}"
}
warn() {
echo -e "${YELLOW}WARNING: $1${NC}"
}
# Input validation
if [ $# -lt 2 ]; then
echo "Usage: $0 <param1> <param2> [optional-param]"
echo ""
echo "Description: Brief description of what this does"
echo ""
echo "Arguments:"
echo " param1 Description of param1"
echo " param2 Description of param2"
echo " optional-param Description of optional param (default: value)"
exit 1
fi
# Parse arguments
PARAM1=$1
PARAM2=$2
OPTIONAL_PARAM=${3:-"default-value"}
# Validate inputs
if [ -z "$PARAM1" ]; then
error "param1 cannot be empty"
fi
# Main logic
main() {
echo "Processing with param1=$PARAM1, param2=$PARAM2..."
# Step 1: Describe what this step does
if ! some_command "$PARAM1"; then
error "Failed to process param1"
fi
# Step 2: Another operation with error handling
result=$(another_command "$PARAM2" 2>&1)
if [ $? -ne 0 ]; then
error "Failed to process param2: $result"
fi
# Step 3: Validation
if [ ! -f "$result" ]; then
error "Expected file not found: $result"
fi
success "Operation completed successfully"
echo "$result" # Output for caller to parse
}
# Execute main function
main

65
skills/capability-writing/templates/user-invocable-skill.md Normal file
View File

@@ -0,0 +1,65 @@
---
name: skill-name
description: >
Clear description of what this skill does and when to use it.
Use when [specific trigger conditions] or when user says /skill-name.
model: haiku
argument-hint: <required-param> [optional-param]
user-invocable: true
# context: fork # Use for skills needing isolated context
# allowed-tools: # Restrict tools if needed
# - Read
# - Bash
---
# Skill Title
@~/.claude/skills/relevant-background-skill/SKILL.md
Brief intro explaining the skill's purpose (1-2 sentences max).
## Process
1. **First step**: Clear action with specific command or instruction
- `command or tool to use`
- What to look for or validate
2. **Second step**: Next action
- Specific details
- Expected output
3. **Ask for approval** before significant actions
- Show what will be created/modified
- Wait for user confirmation
4. **Execute** the approved actions
- Run commands/create files
- Handle errors gracefully
5. **Present results** with links and summary
- Structured output (table or list)
- Links to created resources
## Guidelines
- Keep responses concise
- Use structured output (tables, lists)
- No preambles or sign-offs
- Validate inputs before acting
## Output Format
Use this structure for responses:
\`\`\`
## Summary
[1-2 sentences]
## Results
| Item | Status | Link |
|------|--------|------|
| ... | ... | ... |
## Next Steps
- ...
\`\`\`

130
skills/create-capability/SKILL.md
View File

@@ -13,7 +13,7 @@ user-invocable: true
@~/.claude/skills/capability-writing/SKILL.md
Create new capabilities following established patterns. A capability may be a single component or a cohesive set (skill + agent).
Create new capabilities following latest Anthropic best practices (progressive disclosure, script bundling, Haiku-first).
## Process
@@ -42,11 +42,41 @@ Create new capabilities following established patterns. A capability may be a si
Reasoning: [explain why this combination fits the need]
```
3. **Gather information**: For each recommended component, ask:
3. **Analyze complexity** (NEW): For each skill, determine structure needed:
**Ask these questions:**
a) **Expected size**: Will this skill be >500 lines?
- If NO → Simple structure (just SKILL.md)
- If YES → Suggest progressive disclosure
b) **Error-prone operations**: Are there complex bash operations?
- Check for: PR creation, worktree management, complex git operations
- If YES → Suggest bundling scripts
c) **Degree of freedom**: What instruction style is appropriate?
- Multiple valid approaches → Text instructions (high freedom)
- Preferred pattern with variation → Templates (medium freedom)
- Fragile operations, exact sequence → Scripts (low freedom)
**Present structure recommendation:**
```
## Recommended Structure
Based on complexity analysis:
- **Size**: [Simple | Progressive disclosure]
- **Scripts**: [None | Bundle error-prone operations]
- **Degrees of freedom**: [High | Medium | Low]
Structure:
[Show folder structure diagram]
```
4. **Gather information**: For each recommended component, ask:
**For all components:**
- Name (kebab-case, descriptive)
- Description (one-line summary)
- Description (one-line summary including trigger conditions)
**For Skills:**
- What domain/knowledge does this cover?
@@ -59,59 +89,117 @@ Create new capabilities following established patterns. A capability may be a si
- What skills does it need?
- Should it be read-only (no Edit/Write)?
4. **Select appropriate models**:
5. **Select appropriate models** (UPDATED):
| Model | Use For |
|-------|---------|
| `haiku` | Simple fetch/display skills, formatting tasks |
| `sonnet` | Most skills and agents (default) |
| `opus` | Deep reasoning, architectural analysis, complex judgment |
**Default to Haiku, upgrade only if needed:**
For each component, recommend a model with reasoning.
| Model | Use For | Cost vs Haiku |
|-------|---------|---------------|
| `haiku` | Most skills and agents (DEFAULT) | Baseline |
| `sonnet` | When Haiku would struggle (<80% success rate) | 12x more expensive |
| `opus` | Deep reasoning, architectural analysis | 60x more expensive |
5. **Generate files**: Create content using templates from capability-writing skill
**Ask for justification if not Haiku:**
- "This looks like a simple workflow. Should we try Haiku first?"
- "Does this require complex reasoning that Haiku can't handle?"
Ensure proper inter-references:
For each component, recommend Haiku unless there's clear reasoning for Sonnet/Opus.
6. **Generate files**: Create content using templates from capability-writing skill
**Structure options:**
a) **Simple skill** (most common):
```
skills/skill-name/
└── SKILL.md
```
b) **Progressive disclosure** (for large skills):
```
skills/skill-name/
├── SKILL.md (~200-300 lines)
├── reference/
│ ├── detailed-guide.md
│ └── api-reference.md
└── examples/
└── usage-examples.md
```
c) **With bundled scripts** (for error-prone operations):
```
skills/skill-name/
├── SKILL.md
├── reference/
│ └── error-handling.md
└── scripts/
├── validate.sh
└── process.sh
```
**Ensure proper inter-references:**
- User-invocable skill references background skills via `@~/.claude/skills/name/SKILL.md`
- Agent lists skills in `skills:` frontmatter (names only, not paths)
- User-invocable skill spawns agent via Task tool if agent is part of the set
- Scripts are called with `./scripts/script-name.sh` in SKILL.md
6. **Present for approval**: Show all generated files with their full content:
7. **Present for approval**: Show all generated files with their full content:
```
## Generated Files
### skills/name/SKILL.md
[full content]
### skills/name/scripts/helper.sh (if applicable)
[full content]
### agents/name/AGENT.md (if applicable)
[full content]
Ready to create these files?
```
7. **Create files** in correct locations after approval:
8. **Create files** in correct locations after approval:
- Create directories if needed
- `skills/<name>/SKILL.md`
- `agents/<name>/AGENT.md`
- `skills/<name>/scripts/` (if scripts recommended)
- `skills/<name>/reference/` (if progressive disclosure)
- `agents/<name>/AGENT.md` (if agent recommended)
8. **Report success**:
9. **Report success**:
```
## Capability Created: name
Files created:
- skills/name/SKILL.md
- skills/name/scripts/helper.sh (if applicable)
- agents/name/AGENT.md (if applicable)
Next steps:
1. Run `make install` to symlink to ~/.claude/
2. Test with: /name (for user-invocable skills)
3. Background skills will auto-activate based on context
3. **Test with Haiku** on 3-5 scenarios
4. Measure success rate (aim for ≥80%)
5. Upgrade to Sonnet only if Haiku <80%
```
## Guidelines
## Guidelines (UPDATED)
- Follow all conventions from capability-writing skill
- **Default to Haiku** for all new skills/agents (12x cheaper, 2-5x faster)
- **Bundle scripts** for error-prone bash operations
- **Use progressive disclosure** for skills >500 lines
- Reference existing skills rather than duplicating knowledge
- Keep components focused - split if scope is too broad
- User-invocable skills should have approval checkpoints before significant actions
- Default to `sonnet` model unless there's a clear reason for haiku/opus
- Skills should have descriptive `description` fields for auto-activation
- User-invocable skills should have approval checkpoints
- Skills should have descriptive `description` fields with trigger conditions
- **Be concise** - assume Claude knows basics
## Output Style
Be concise and direct:
- No preambles ("I'll help you...")
- No sign-offs ("Let me know...")
- Show structure diagrams clearly
- Use tables for comparisons
- One decision per section