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. A capability may be a single component or a cohesive set (skill + agent).

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)

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

Component Templates

User-Invocable Skill Template

Location: skills/<name>/SKILL.md

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

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

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

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 skills and agents, balanced performance	/work-issue, code-reviewer
opus	Deep reasoning, architectural analysis, complex judgment	/arch-review-repo

Decision Criteria

• 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

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

Referencing Skills

In User-Invocable Skills

Use the @ 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" - 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 (User-Invocable Skills)

Always ask before significant actions:

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:

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

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

• docs/writing-capabilities.md - Complete guide covering skills and agents

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

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 (not just inherit)
• skills list is right-sized (not too many)
• File at agents/<name>/AGENT.md