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 + command + agent). Use when creating new skills, commands, or agents, or when extending the AI workflow system. Includes templates, design guidance, and conventions.	false

Capability Writing

How to design and create capabilities for the architecture repository. A capability is often a cohesive set of components (skill + command + agent) that work together.

Component Overview

Component	Location	Purpose	Example
Skill	skills/name/SKILL.md	Knowledge Claude applies automatically	software-architecture
Command	commands/name.md	User-invoked workflow entry point	/work-issue
Agent	agents/name/AGENT.md	Isolated subtask handler with focused context	code-reviewer

When to Use Each Component

Decision Tree

Start here: What do you need?
    |
    +--> Just knowledge to apply automatically?
    |        --> Skill only
    |
    +--> User-initiated workflow using existing knowledge?
    |        --> Command (reference skills via @)
    |
    +--> Complex isolated work needing focused context?
    |        --> Command + Agent (agent uses skills)
    |
    +--> New domain expertise + workflow + isolated work?
             --> Full capability (all three)

Decision Matrix

Need	Component	Example
Knowledge Claude should apply automatically	Skill	software-architecture, issue-writing
User-invoked workflow	Command	/work-issue, /dashboard
Isolated subtask with focused context	Agent	code-reviewer, issue-worker
All three working together	Full capability	arch-review (skill + command + agent)

Signs You Need Each Component

Create a Skill when:

• You explain the same concepts repeatedly
• Quality is inconsistent without explicit guidance
• Multiple commands need the same knowledge
• There is a clear domain that does not fit existing skills

Create a Command 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

Skill Template

Location: skills/<name>/SKILL.md

---
name: skill-name
description: >
  What this skill teaches and when to use it.
  Include trigger conditions in description (not body).
  List specific capabilities users would mention.
user-invocable: false
---

# Skill Name

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.

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	No	Set false for reference-only skills
model	No	Specific model: haiku, sonnet, opus
context	No	Use fork for isolated context
allowed-tools	No	Restrict available tools

Command Template

Location: commands/<name>.md

---
description: What this command does (one-line summary)
argument-hint: <required> [optional]
model: sonnet
---

# Command Title

@~/.claude/skills/relevant-skill/SKILL.md

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

Frontmatter fields:

Field	Required	Description
description	Yes	One-line summary for help/listings
argument-hint	No	Shows expected args: <required>, [optional]
model	No	Override model: haiku, sonnet, opus
context	No	Use fork for isolated context
allowed-tools	No	Restrict available tools

Agent Template

Location: agents/<name>/AGENT.md

---
name: agent-name
description: What this agent does and when to spawn it
model: sonnet
skills: skill1, skill2
disallowedTools:
  - Edit
  - 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

Frontmatter fields:

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

Model Selection Guidance

Model	Use When	Examples
haiku	Simple fetch/display, formatting, mechanical tasks	/dashboard, /roadmap
sonnet	Most commands and agents, balanced performance	/work-issue, issue-worker, code-reviewer
opus	Deep reasoning, architectural analysis, complex judgment	software-architect, security auditor

Decision Criteria

• Start with sonnet - handles most tasks well
• Use haiku for volume - speed and cost matter at scale
• Reserve opus for judgment - when errors are costly or reasoning is complex
• Consider the stakes - higher consequence tasks warrant more capable models

Naming Conventions

File and Folder Names

Component	Convention	Examples
Skill folder	kebab-case	software-architecture, issue-writing
Skill file	UPPERCASE	SKILL.md
Command file	kebab-case	work-issue.md, review-pr.md
Agent folder	kebab-case	code-reviewer, issue-worker
Agent file	UPPERCASE	AGENT.md

Naming Patterns

Skills: Name after the domain or knowledge area

• Good: gitea, issue-writing, software-architecture
• Bad: utils, helpers, misc

Commands: Use verb or verb-phrase (actions)

• Good: work-issue, review-pr, create-issue
• Bad: issue-work, pr-review, issue

Agents: Name by role or persona (recognizable specialist)

• Good: code-reviewer, issue-worker, software-architect
• Bad: helper, do-stuff, agent1

Referencing Skills

In Commands

Use the @ file reference syntax to guarantee 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" - skills have only ~20% auto-activation rate. File references guarantee the content is available.

In Agents

List skill names in the frontmatter (not paths):

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

The agent runtime loads these skills automatically.

Common Patterns

Approval Workflow (Commands)

Always ask before significant actions:

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

Conditional Behavior (Commands)

Handle optional arguments with mode switching:

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

Delegate complex subtasks:

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

Read-Only Agents

For analysis without modification:

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

Anti-Patterns to Avoid

Overly Broad Components

Bad: One skill/command/agent that does everything

# Project Management
Handles issues, PRs, releases, documentation, deployment...

Good: Focused components with clear responsibility

# Issue Writing
How to write clear, actionable issues.

Vague Instructions

Bad:

1. Handle the issue
2. Do the work
3. Finish up

Good:

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:

Use the gitea skill to create an issue.

Good:

@~/.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 the docs/ directory:

• docs/writing-skills.md - Complete skill writing guide
• docs/writing-commands.md - Complete command writing guide
• docs/writing-agents.md - Complete agent writing guide

These documents include:

• Full frontmatter reference
• Annotated examples from the codebase
• Lifecycle management
• Integration checklists

Checklists

Before Creating a 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 descriptive description with trigger terms
• File at skills/<name>/SKILL.md

Before Creating a Command

• Workflow is repeatable (used multiple times)
• User explicitly triggers it (not automatic)
• Clear start and end points
• Skills referenced via @~/.claude/skills/<name>/SKILL.md
• Approval checkpoints before significant actions
• File at commands/<name>.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 (not just inherit)
• skills list is right-sized (not too many)
• File at agents/<name>/AGENT.md