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

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

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

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

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

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

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