architecture/skills/capability-writing/SKILL.md

name, description, user-invocable

name	description	user-invocable
capability-writing	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.	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:

5. Create PR: `tea pulls create --title "..." --description "..."`

Bundle a script:

5. **Create PR**: `./scripts/create-pr.sh $issue "$title"`

# 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

Component Templates

User-Invocable Skill Template

---
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

Background Skill Template

---
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

Agent Template

---
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

Helper script template: See 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/ folder

Referencing Skills

In User-Invocable Skills

Use @ file reference syntax to guarantee background skill content is loaded:

@~/.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):

---
name: product-manager
skills: gitea, issue-writing, backlog-grooming
---

Common Patterns

Approval Workflow

4. **Present plan** for approval
5. **If approved**, create the issues
6. **Present summary** with links

Conditional Behavior

## 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

9. **Auto-review**: Spawn the `code-reviewer` agent with the PR number

Read-Only Agents

---
name: code-reviewer
disallowedTools:
  - Edit
  - Write
---

Quick Reference

Frontmatter fields: See reference/frontmatter-fields.md Model selection: See reference/model-selection.md Anti-patterns: See reference/anti-patterns.md Best practices: See 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