feat(skills): modernize capability-writing with Anthropic best practices
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:
@@ -10,7 +10,101 @@ user-invocable: false
|
|||||||
|
|
||||||
# Capability Writing
|
# 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
|
## Component Overview
|
||||||
|
|
||||||
@@ -40,41 +134,12 @@ Start here: What do you need?
|
|||||||
--> Full capability (background skill + user-invocable skill + agent)
|
--> Full capability (background skill + user-invocable skill + agent)
|
||||||
```
|
```
|
||||||
|
|
||||||
### Decision Matrix
|
**Detailed decision criteria:** See [best-practices.md](best-practices.md)
|
||||||
|
|
||||||
| 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
|
|
||||||
|
|
||||||
## Component Templates
|
## Component Templates
|
||||||
|
|
||||||
### User-Invocable Skill Template
|
### User-Invocable Skill Template
|
||||||
|
|
||||||
Location: `skills/<name>/SKILL.md`
|
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
---
|
---
|
||||||
name: skill-name
|
name: skill-name
|
||||||
@@ -99,22 +164,10 @@ Brief intro if needed.
|
|||||||
5. **Present results** with links and summary
|
5. **Present results** with links and summary
|
||||||
```
|
```
|
||||||
|
|
||||||
**Frontmatter fields:**
|
**Complete template with all fields:** See [templates/user-invocable-skill.md](templates/user-invocable-skill.md)
|
||||||
|
|
||||||
| 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 |
|
|
||||||
|
|
||||||
### Background Skill Template
|
### Background Skill Template
|
||||||
|
|
||||||
Location: `skills/<name>/SKILL.md`
|
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
---
|
---
|
||||||
name: skill-name
|
name: skill-name
|
||||||
@@ -129,130 +182,87 @@ user-invocable: false
|
|||||||
Brief description of what this skill covers.
|
Brief description of what this skill covers.
|
||||||
|
|
||||||
## Core Concepts
|
## Core Concepts
|
||||||
|
|
||||||
Explain fundamental ideas Claude needs to understand.
|
|
||||||
|
|
||||||
## Patterns and Templates
|
## Patterns and Templates
|
||||||
|
|
||||||
Provide reusable structures and formats.
|
|
||||||
|
|
||||||
## Guidelines
|
## Guidelines
|
||||||
|
|
||||||
List rules, best practices, and quality standards.
|
|
||||||
|
|
||||||
## Examples
|
## 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
|
```yaml
|
||||||
---
|
---
|
||||||
name: agent-name
|
name: agent-name
|
||||||
description: What this agent does and when to spawn it
|
description: What this agent does and when to spawn it
|
||||||
model: sonnet
|
model: haiku
|
||||||
skills: skill1, skill2
|
skills: skill1, skill2
|
||||||
disallowedTools:
|
disallowedTools:
|
||||||
- Edit
|
- Edit # For read-only agents
|
||||||
- Write
|
- Write
|
||||||
---
|
---
|
||||||
|
|
||||||
You are a [role] specialist that [primary function].
|
You are a [role] specialist that [primary function].
|
||||||
|
|
||||||
## When Invoked
|
## When Invoked
|
||||||
|
1. **Gather context**
|
||||||
Describe the process the agent follows:
|
2. **Analyze**
|
||||||
|
3. **Act**
|
||||||
1. **Gather context**: What information to collect
|
4. **Report**
|
||||||
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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**Frontmatter fields:**
|
**Complete template:** See [templates/agent.md](templates/agent.md)
|
||||||
|
|
||||||
| Field | Required | Description |
|
**Helper script template:** See [templates/helper-script.sh](templates/helper-script.sh)
|
||||||
|-------|----------|-------------|
|
|
||||||
| `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` |
|
|
||||||
|
|
||||||
## Model Selection Guidance
|
## Structure Examples
|
||||||
|
|
||||||
| Model | Use When | Examples |
|
### Simple Skill (< 300 lines, no scripts)
|
||||||
|-------|----------|----------|
|
```
|
||||||
| `haiku` | Simple fetch/display, formatting, mechanical tasks | /dashboard, /roadmap |
|
skills/simple-skill/
|
||||||
| `sonnet` | Most skills and agents, balanced performance | /work-issue, code-reviewer |
|
└── SKILL.md
|
||||||
| `opus` | Deep reasoning, architectural analysis, complex judgment | /arch-review-repo |
|
```
|
||||||
|
|
||||||
### 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
|
### With Bundled Scripts
|
||||||
- **Use `sonnet`** for most skills and agents (default choice)
|
```
|
||||||
- **Reserve `opus` for judgment** - when errors are costly or reasoning is complex
|
skills/skill-with-scripts/
|
||||||
- **Consider the stakes** - higher consequence tasks warrant more capable models
|
├── SKILL.md
|
||||||
|
├── reference/
|
||||||
|
│ └── error-handling.md
|
||||||
|
└── scripts/
|
||||||
|
├── validate.sh
|
||||||
|
└── process.sh
|
||||||
|
```
|
||||||
|
|
||||||
## Naming Conventions
|
**Detailed examples:** See [examples/](examples/) folder
|
||||||
|
|
||||||
### 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`
|
|
||||||
|
|
||||||
## Referencing Skills
|
## Referencing Skills
|
||||||
|
|
||||||
### In User-Invocable 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
|
```markdown
|
||||||
@~/.claude/skills/gitea/SKILL.md
|
@~/.claude/skills/gitea/SKILL.md
|
||||||
@~/.claude/skills/issue-writing/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
|
### In Agents
|
||||||
|
|
||||||
List skill names in the frontmatter (not paths):
|
List skill names in frontmatter (not paths):
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
---
|
---
|
||||||
@@ -261,24 +271,16 @@ skills: gitea, issue-writing, backlog-grooming
|
|||||||
---
|
---
|
||||||
```
|
```
|
||||||
|
|
||||||
The agent runtime loads these skills automatically.
|
|
||||||
|
|
||||||
## Common Patterns
|
## Common Patterns
|
||||||
|
|
||||||
### Approval Workflow (User-Invocable Skills)
|
### Approval Workflow
|
||||||
|
|
||||||
Always ask before significant actions:
|
|
||||||
|
|
||||||
```markdown
|
```markdown
|
||||||
4. **Present plan** for approval
|
4. **Present plan** for approval
|
||||||
5. **If approved**, create the issues
|
5. **If approved**, create the issues
|
||||||
6. **Present summary** with links
|
6. **Present summary** with links
|
||||||
```
|
```
|
||||||
|
|
||||||
### Conditional Behavior (User-Invocable Skills)
|
### Conditional Behavior
|
||||||
|
|
||||||
Handle optional arguments with mode switching:
|
|
||||||
|
|
||||||
```markdown
|
```markdown
|
||||||
## If issue number provided ($1):
|
## If issue number provided ($1):
|
||||||
1. Fetch specific issue
|
1. Fetch specific issue
|
||||||
@@ -289,18 +291,12 @@ Handle optional arguments with mode switching:
|
|||||||
2. Process each
|
2. Process each
|
||||||
```
|
```
|
||||||
|
|
||||||
### Spawning Agents from Skills
|
### Spawning Agents
|
||||||
|
|
||||||
Delegate complex subtasks:
|
|
||||||
|
|
||||||
```markdown
|
```markdown
|
||||||
9. **Auto-review**: Spawn the `code-reviewer` agent with the PR number
|
9. **Auto-review**: Spawn the `code-reviewer` agent with the PR number
|
||||||
```
|
```
|
||||||
|
|
||||||
### Read-Only Agents
|
### Read-Only Agents
|
||||||
|
|
||||||
For analysis without modification:
|
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
---
|
---
|
||||||
name: code-reviewer
|
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
|
## Naming Conventions
|
||||||
```markdown
|
|
||||||
# Project Management
|
|
||||||
Handles issues, PRs, releases, documentation, deployment...
|
|
||||||
```
|
|
||||||
|
|
||||||
**Good:** Focused components with clear responsibility
|
| Component | Convention | Examples |
|
||||||
```markdown
|
|-----------|------------|----------|
|
||||||
# Issue Writing
|
| Skill folder | kebab-case | `software-architecture`, `work-issue` |
|
||||||
How to write clear, actionable issues.
|
| Skill file | UPPERCASE | `SKILL.md` |
|
||||||
```
|
| Agent folder | kebab-case | `code-reviewer`, `issue-worker` |
|
||||||
|
| Agent file | UPPERCASE | `AGENT.md` |
|
||||||
|
|
||||||
### Vague Instructions
|
**Skills:** Name after domain/action (good: `gitea`, `work-issue`; bad: `utils`, `helpers`)
|
||||||
|
**Agents:** Name by role/persona (good: `code-reviewer`; bad: `helper`, `agent1`)
|
||||||
**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
|
|
||||||
|
|
||||||
## Checklists
|
## Checklists
|
||||||
|
|
||||||
@@ -390,6 +337,7 @@ For comprehensive guides, see:
|
|||||||
- [ ] Background skills referenced via `@~/.claude/skills/<name>/SKILL.md`
|
- [ ] Background skills referenced via `@~/.claude/skills/<name>/SKILL.md`
|
||||||
- [ ] Approval checkpoints before significant actions
|
- [ ] Approval checkpoints before significant actions
|
||||||
- [ ] File at `skills/<name>/SKILL.md`
|
- [ ] File at `skills/<name>/SKILL.md`
|
||||||
|
- [ ] **Model defaults to `haiku`** unless justified
|
||||||
|
|
||||||
### Before Creating a Background Skill
|
### Before Creating a Background Skill
|
||||||
|
|
||||||
@@ -405,6 +353,6 @@ For comprehensive guides, see:
|
|||||||
- [ ] Built-in agents (Explore, Plan) are not sufficient
|
- [ ] Built-in agents (Explore, Plan) are not sufficient
|
||||||
- [ ] Context isolation or skill composition is needed
|
- [ ] Context isolation or skill composition is needed
|
||||||
- [ ] Clear role/persona emerges
|
- [ ] 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)
|
- [ ] `skills` list is right-sized (not too many)
|
||||||
- [ ] File at `agents/<name>/AGENT.md`
|
- [ ] File at `agents/<name>/AGENT.md`
|
||||||
|
|||||||
500
skills/capability-writing/best-practices.md
Normal file
500
skills/capability-writing/best-practices.md
Normal 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
129
skills/capability-writing/examples/progressive-disclosure.md
Normal 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
71
skills/capability-writing/examples/simple-workflow.md
Normal 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
210
skills/capability-writing/examples/with-scripts.md
Normal 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
536
skills/capability-writing/reference/anti-patterns.md
Normal 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
278
skills/capability-writing/reference/frontmatter-fields.md
Normal 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
336
skills/capability-writing/reference/model-selection.md
Normal 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
67
skills/capability-writing/templates/agent.md
Normal 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
69
skills/capability-writing/templates/background-skill.md
Normal 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
86
skills/capability-writing/templates/helper-script.sh
Normal 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
65
skills/capability-writing/templates/user-invocable-skill.md
Normal 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
|
||||||
|
- ...
|
||||||
|
\`\`\`
|
||||||
@@ -13,7 +13,7 @@ user-invocable: true
|
|||||||
|
|
||||||
@~/.claude/skills/capability-writing/SKILL.md
|
@~/.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
|
## 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]
|
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:**
|
**For all components:**
|
||||||
- Name (kebab-case, descriptive)
|
- Name (kebab-case, descriptive)
|
||||||
- Description (one-line summary)
|
- Description (one-line summary including trigger conditions)
|
||||||
|
|
||||||
**For Skills:**
|
**For Skills:**
|
||||||
- What domain/knowledge does this cover?
|
- 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?
|
- What skills does it need?
|
||||||
- Should it be read-only (no Edit/Write)?
|
- Should it be read-only (no Edit/Write)?
|
||||||
|
|
||||||
4. **Select appropriate models**:
|
5. **Select appropriate models** (UPDATED):
|
||||||
|
|
||||||
| Model | Use For |
|
**Default to Haiku, upgrade only if needed:**
|
||||||
|-------|---------|
|
|
||||||
| `haiku` | Simple fetch/display skills, formatting tasks |
|
|
||||||
| `sonnet` | Most skills and agents (default) |
|
|
||||||
| `opus` | Deep reasoning, architectural analysis, complex judgment |
|
|
||||||
|
|
||||||
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`
|
- User-invocable skill references background skills via `@~/.claude/skills/name/SKILL.md`
|
||||||
- Agent lists skills in `skills:` frontmatter (names only, not paths)
|
- 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
|
- 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
|
## Generated Files
|
||||||
|
|
||||||
### skills/name/SKILL.md
|
### skills/name/SKILL.md
|
||||||
[full content]
|
[full content]
|
||||||
|
|
||||||
|
### skills/name/scripts/helper.sh (if applicable)
|
||||||
|
[full content]
|
||||||
|
|
||||||
### agents/name/AGENT.md (if applicable)
|
### agents/name/AGENT.md (if applicable)
|
||||||
[full content]
|
[full content]
|
||||||
|
|
||||||
Ready to create these files?
|
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`
|
- `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
|
## Capability Created: name
|
||||||
|
|
||||||
Files created:
|
Files created:
|
||||||
- skills/name/SKILL.md
|
- skills/name/SKILL.md
|
||||||
|
- skills/name/scripts/helper.sh (if applicable)
|
||||||
- agents/name/AGENT.md (if applicable)
|
- agents/name/AGENT.md (if applicable)
|
||||||
|
|
||||||
Next steps:
|
Next steps:
|
||||||
1. Run `make install` to symlink to ~/.claude/
|
1. Run `make install` to symlink to ~/.claude/
|
||||||
2. Test with: /name (for user-invocable skills)
|
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
|
- 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
|
- Reference existing skills rather than duplicating knowledge
|
||||||
- Keep components focused - split if scope is too broad
|
- Keep components focused - split if scope is too broad
|
||||||
- User-invocable skills should have approval checkpoints before significant actions
|
- User-invocable skills should have approval checkpoints
|
||||||
- Default to `sonnet` model unless there's a clear reason for haiku/opus
|
- Skills should have descriptive `description` fields with trigger conditions
|
||||||
- Skills should have descriptive `description` fields for auto-activation
|
- **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
|
||||||
|
|||||||
Reference in New Issue
Block a user