chore: move agents and skills to old2 folder
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
@@ -1,358 +0,0 @@
|
||||
---
|
||||
name: capability-writing
|
||||
description: >
|
||||
Guide for designing and creating capabilities for the architecture repository.
|
||||
A capability is a cohesive set of components (skill + agent).
|
||||
Use when creating new skills, agents, or extending the
|
||||
AI workflow system. Includes templates, design guidance, and conventions.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# Capability Writing
|
||||
|
||||
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 | Location | Purpose | Example |
|
||||
|-----------|----------|---------|---------|
|
||||
| **User-invocable Skill** | `skills/name/SKILL.md` | Workflow users trigger with `/name` | /work-issue, /dashboard |
|
||||
| **Background Skill** | `skills/name/SKILL.md` | Knowledge auto-loaded when needed | gitea, issue-writing |
|
||||
| **Agent** | `agents/name/AGENT.md` | Isolated subtask handler | code-reviewer |
|
||||
|
||||
## When to Use Each Component
|
||||
|
||||
### Decision Tree
|
||||
|
||||
```
|
||||
Start here: What do you need?
|
||||
|
|
||||
+--> Just knowledge to apply automatically?
|
||||
| --> Background skill (user-invocable: false)
|
||||
|
|
||||
+--> User-initiated workflow?
|
||||
| --> User-invocable skill (user-invocable: true)
|
||||
|
|
||||
+--> Complex isolated work needing focused context?
|
||||
| --> User-invocable skill + Agent
|
||||
|
|
||||
+--> New domain expertise + workflow + isolated work?
|
||||
--> Full capability (background skill + user-invocable skill + agent)
|
||||
```
|
||||
|
||||
**Detailed decision criteria:** See [best-practices.md](best-practices.md)
|
||||
|
||||
## Component Templates
|
||||
|
||||
### User-Invocable Skill Template
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: skill-name
|
||||
description: >
|
||||
What this skill does and when to use it.
|
||||
Use when [trigger conditions] or when user says /skill-name.
|
||||
model: haiku
|
||||
argument-hint: <required> [optional]
|
||||
user-invocable: true
|
||||
---
|
||||
|
||||
# Skill Title
|
||||
|
||||
@~/.claude/skills/relevant-skill/SKILL.md
|
||||
|
||||
Brief intro if needed.
|
||||
|
||||
1. **First step**: What to do
|
||||
2. **Second step**: What to do next
|
||||
3. **Ask for approval** before significant actions
|
||||
4. **Execute** the approved actions
|
||||
5. **Present results** with links and summary
|
||||
```
|
||||
|
||||
**Complete template with all fields:** See [templates/user-invocable-skill.md](templates/user-invocable-skill.md)
|
||||
|
||||
### Background Skill Template
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: skill-name
|
||||
description: >
|
||||
What this skill teaches and when to use it.
|
||||
Include trigger conditions in description.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# Skill Name
|
||||
|
||||
Brief description of what this skill covers.
|
||||
|
||||
## Core Concepts
|
||||
## Patterns and Templates
|
||||
## Guidelines
|
||||
## Examples
|
||||
```
|
||||
|
||||
**Complete template:** See [templates/background-skill.md](templates/background-skill.md)
|
||||
|
||||
### Agent Template
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: agent-name
|
||||
description: What this agent does and when to spawn it
|
||||
model: haiku
|
||||
skills: skill1, skill2
|
||||
disallowedTools:
|
||||
- Edit # For read-only agents
|
||||
- Write
|
||||
---
|
||||
|
||||
You are a [role] specialist that [primary function].
|
||||
|
||||
## When Invoked
|
||||
1. **Gather context**
|
||||
2. **Analyze**
|
||||
3. **Act**
|
||||
4. **Report**
|
||||
```
|
||||
|
||||
**Complete template:** See [templates/agent.md](templates/agent.md)
|
||||
|
||||
**Helper script template:** See [templates/helper-script.sh](templates/helper-script.sh)
|
||||
|
||||
## Structure Examples
|
||||
|
||||
### Simple Skill (< 300 lines, no scripts)
|
||||
```
|
||||
skills/simple-skill/
|
||||
└── SKILL.md
|
||||
```
|
||||
|
||||
### Progressive Disclosure (with reference files)
|
||||
```
|
||||
skills/complex-skill/
|
||||
├── SKILL.md (~200 lines)
|
||||
├── reference/
|
||||
│ ├── detailed-guide.md
|
||||
│ └── api-reference.md
|
||||
└── examples/
|
||||
└── usage-examples.md
|
||||
```
|
||||
|
||||
### With Bundled Scripts
|
||||
```
|
||||
skills/skill-with-scripts/
|
||||
├── SKILL.md
|
||||
├── reference/
|
||||
│ └── error-handling.md
|
||||
└── scripts/
|
||||
├── validate.sh
|
||||
└── process.sh
|
||||
```
|
||||
|
||||
**Detailed examples:** See [examples/](examples/) folder
|
||||
|
||||
## Referencing Skills
|
||||
|
||||
### In User-Invocable Skills
|
||||
|
||||
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" - file references guarantee the content is available.
|
||||
|
||||
### In Agents
|
||||
|
||||
List skill names in frontmatter (not paths):
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: product-manager
|
||||
skills: gitea, issue-writing, backlog-grooming
|
||||
---
|
||||
```
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Approval Workflow
|
||||
```markdown
|
||||
4. **Present plan** for approval
|
||||
5. **If approved**, create the issues
|
||||
6. **Present summary** with links
|
||||
```
|
||||
|
||||
### Conditional Behavior
|
||||
```markdown
|
||||
## If issue number provided ($1):
|
||||
1. Fetch specific issue
|
||||
2. Process it
|
||||
|
||||
## If no argument (batch mode):
|
||||
1. List all issues
|
||||
2. Process each
|
||||
```
|
||||
|
||||
### Spawning Agents
|
||||
```markdown
|
||||
9. **Auto-review**: Spawn the `code-reviewer` agent with the PR number
|
||||
```
|
||||
|
||||
### Read-Only Agents
|
||||
```yaml
|
||||
---
|
||||
name: code-reviewer
|
||||
disallowedTools:
|
||||
- Edit
|
||||
- Write
|
||||
---
|
||||
```
|
||||
|
||||
## Quick Reference
|
||||
|
||||
**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)
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
| 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` |
|
||||
|
||||
**Skills:** Name after domain/action (good: `gitea`, `work-issue`; bad: `utils`, `helpers`)
|
||||
**Agents:** Name by role/persona (good: `code-reviewer`; bad: `helper`, `agent1`)
|
||||
|
||||
## Checklists
|
||||
|
||||
### Before Creating a User-Invocable Skill
|
||||
|
||||
- [ ] Workflow is used multiple times
|
||||
- [ ] User explicitly triggers it (not automatic)
|
||||
- [ ] Clear start and end points
|
||||
- [ ] Frontmatter has `user-invocable: true`
|
||||
- [ ] Description includes "Use when... or when user says /skill-name"
|
||||
- [ ] 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
|
||||
|
||||
- [ ] Knowledge is used in multiple places (not just once)
|
||||
- [ ] Existing skills do not already cover this domain
|
||||
- [ ] Content is specific and actionable (not generic)
|
||||
- [ ] Frontmatter has `user-invocable: false`
|
||||
- [ ] Description includes trigger terms
|
||||
- [ ] File at `skills/<name>/SKILL.md`
|
||||
|
||||
### Before Creating an Agent
|
||||
|
||||
- [ ] Built-in agents (Explore, Plan) are not sufficient
|
||||
- [ ] Context isolation or skill composition is needed
|
||||
- [ ] Clear role/persona emerges
|
||||
- [ ] `model` selection is deliberate (default to `haiku`)
|
||||
- [ ] `skills` list is right-sized (not too many)
|
||||
- [ ] File at `agents/<name>/AGENT.md`
|
||||
Reference in New Issue
Block a user