Skill Authoring

# Advanced Skill-Authoring Patterns

Patterns for skill authors who have shipped a working skill and now
need to coordinate with other skills, scale across many activation
contexts, or expose conditional behavior. Read this after the core
SKILL.md and `tdd-methodology.md` modules. The Iron Law still
applies: every advanced pattern below assumes a baseline failing
test exists for the behavior being added.

## When to reach for these patterns

Most skills do not need any of this. Add an advanced pattern only
when a baseline scenario fails because of coordination, scale, or
context, not because of missing content. If the failure can be
fixed by adding a section to a single SKILL.md, do that first.

| Symptom in baseline tests | Pattern below |
|---------------------------|---------------|
| Two skills give conflicting advice on same task | Multi-skill coordination |
| One SKILL.md exceeds 500 lines and still grows | Hub-and-spoke loading |
| Skill activates on irrelevant tasks | Trigger narrowing |
| Skill must behave differently per environment | Conditional activation |
| Same module needed by 3+ skills | Shared module extraction |

## Multi-skill coordination

Skills frequently overlap. `abstract:skill-authoring` writes new
skills, `abstract:skills-eval` audits them, and
`abstract:subagent-testing` validates them. When a task touches
all three, the user does not want three skills shouting in
parallel. They want a chain.

### Establish a primary skill per task

In each SKILL.md, declare which other skills it defers to and
which it owns. Example from `abstract:skill-authoring/SKILL.md`:

```markdown
## Integration and Best Practices

Individual skills are created using `skill-authoring`, while
`modular-skills` handles the architecture of larger structures.
`skills-eval` provides ongoing quality assessment.
```

This single paragraph prevents the three skills from racing. The
user reading any one of them learns where the boundaries live.

### Cross-reference real targets, not abstractions

Use the fully qualified `plugin:skill` form so the reference
resolves regardless of which marketplace the user installed:

```markdown
For pressure testing the new skill, see
`Skill(abstract:subagent-testing)`.
```

Anti-pattern: `see the testing skill`. There are six skills with
"testing" in the name across this repo. The reader cannot route.

### Hand off, do not duplicate

When skill A needs behavior owned by skill B, link to skill B
rather than restating its content. Duplicated guidance drifts.
The version in `abstract:skill-authoring` will say one thing and
the copy in `abstract:skills-eval` will say something else after
two PRs. Pick an owner and link.

## Hub-and-spoke loading

The hub-and-spoke pattern is documented in
`progressive-disclosure.md`. The advanced variant adds two rules
that only matter once a skill has 5+ modules.

### Rule 1: the hub never loads more than two spokes

If your SKILL.md routinely says "for X, see module-a; for Y, see
module-b; for Z, see module-c," the hub is doing too much. Either
collapse the three modules into one, or split the hub into
multiple skills. A reader who must load four files to start
working has lost progressive disclosure.

### Rule 2: spokes do not chain

A spoke that says "see other-spoke.md for prerequisites" forces
sequential loading and defeats the model. If two spokes share
foundational content, extract a third spoke and have the hub
load it explicitly when needed. See
`Skill(abstract:modular-skills)` for the full chain-elimination
algorithm.

## Dynamic activation via description triggers

Skills activate by semantic match on the `description:` field.
Authors of mature skills tune triggers deliberately rather than
listing every possible synonym.

### Use specific noun phrases, not generic verbs

| Generic (low signal) | Specific (high signal) |
|----------------------|------------------------|
| Use when reviewing code | Use when reviewing PRs |
| Use when writing tests | Use when writ