Writing Skills

Writing Skills

Build effective A Team skills through TDD for documentation: write the skill, watch agents use it, close the gaps.

What Makes a Good Skill

A skill is a reference guide that agents consult before taking action. It is NOT:

• A tutorial (agents don't need hand-holding on basics)
• A checklist of preferences (that's a rule file)
• An agent definition (that's .claude/agents/)

A skill must:

• Define WHEN to use it (trigger conditions)
• Define WHEN NOT to use it (scope limits)
• Define the process (steps, decision points)
• Define red flags (patterns that mean you're off-track)
• Be verifiable (an agent following it produces measurable output)

The TDD Process for Skills

Phase RED — Write the Skill, Watch Agents Fail

1. Write a first draft of the skill
2. Give agents a task that should trigger it
3. Watch them use it — specifically look for:

• Where they skip steps
• Where they interpret a step differently than intended
• Where they think they're done but aren't
• Where the skill is silent on an important case

1. The gaps you find ARE the failing tests

Phase GREEN — Close the Gaps

For each failure you observed:

• Add explicit language that prevents the wrong behavior
• Add a red flag for the rationalization the agent used
• Add a concrete example if the step was ambiguous
• Make the step smaller if the agent couldn't execute it correctly

Phase REFACTOR — Tighten

• Remove content that agents ignored (it's not load-bearing)
• Consolidate redundant sections
• Keep each skill under ~300 lines — after that, split or extract

Skill File Structure

---
name: skill-name
description: When to use this (1-2 sentences). What it produces.
---

# Skill Title

## When to Use
[Trigger conditions — be specific enough that the agent knows for certain]

## When NOT to Use
[Scope limits — prevent misapplication]

## The Process
[Steps with decision points. Use flowchart notation for branching.]

## Red Flags — You're Doing It Wrong
[List of rationalizations and shortcuts that indicate the agent has gone off-track]

## Integration
[Which skills come before/after this one in the workflow]

Frontmatter Requirements

Every skill file needs frontmatter:

---
name: kebab-case-name          # matches the directory name
description: |                 # one sentence trigger + one sentence output
  Use when [condition].
  Produces [artifact].
---

The description is used by orchestrators and other agents to decide whether to invoke the skill. Write it as a contract, not marketing copy.

Naming Conventions

• Directory: skills/kebab-case-name/
• File: SKILL.md (always uppercase, always this name)
• Skill name in frontmatter: matches directory name exactly
• Supporting files: skills/kebab-case-name/supporting-file.md

Common Mistakes

| Mistake | Fix | |---------|-----| | Skill tries to cover too much | Split into two focused skills | | Steps are vague ("review the code") | Make them specific ("run git diff --staged") | | No red flags section | Add the 3 most common ways agents misuse this skill | | No "when NOT to use" | Add scope limits — prevent misapplication | | Skill is a list of preferences | Move to .claude/rules/ instead | | Skill describes an agent's role | Move to .claude/agents/ instead |

Registering a New Skill

After writing the skill:

1. Add it to CLAUDE.md skills table
2. Add it to AGENTS.md skills table
3. Add it to skills/using-a-team/SKILL.md trigger table
4. Test it: give an agent a task that should trigger the skill, verify they use it correctly

A skill that doesn't get used is a skill that doesn't exist.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: RBraga01
• Source: RBraga01/a-team
• License: MIT
• Homepage: https://rbraga01.github.io/a-team/

Install and usage instructions live in the source repository linked above.