# Skill templates

Two skeletons. Copy the one that matches the layer, fill it, then delete every line that fails the cut test. The toolkits use these frontmatter keys: `name`, `description`, `allowed-tools`, `user-invocable`, plus an optional `argument-hint` and a `metadata` block with `version` (semver of the skill text) and `source` (`multi-agent-pipeline` for a first-party skill, otherwise `<upstream> (<license>)` for the upstream it derives from, which a `NOTICE-*.md` beside it must list). For a shared knowledge skill in the pipeline source the block with `source` is required: the pipeline's skill lint fails one that has none. Elsewhere the block is optional; drop it rather than leave a placeholder in it.

## Reference skill

```markdown
---
name: {aspect-noun}
description: "{What it covers} for {platform}. {When to reach for it}. Triggers: '{phrase}', '{phrase}', '{phrase}'."
user-invocable: true
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
metadata:
  version: {x.y.z}
  source: {multi-agent-pipeline | upstream}
---

# {name} - {short title}

> **Layer:** reference (knowledge). **Use when:** {situation}. **Hand off to:** {sibling skill} for {adjacent concern}.

## Scope
In: {one line}. Out: {one line}.

## Invariants
- **{Rule}.** {Why it holds; what breaks otherwise.}

## Conventions and golden paths
- {Convention} - see `{path/to/canonical/file}`. Point at the file; do not paste its code.

## Decision rules
- {Condition} -> {choice}.

## Pitfalls
- {Mistake} - {symptom} - {correct move}.

## Escape hatches
- {Case this skill does not cover} -> {skill to use}.
```

## Workflow skill

```markdown
---
name: {verb-phrase}
description: "{What it does} for {platform}, with {guardrails}. Use when {situation}. Triggers: '{phrase}', '{phrase}'."
user-invocable: true
argument-hint: "{args}"
allowed-tools: Bash, Read
metadata:
  version: {x.y.z}
  source: {multi-agent-pipeline | upstream}
---

# {name} - {short title}

> **Layer:** workflow (action). **Use when:** {situation}. **Don't use when:** {situation} -> {sibling skill}.

## Scope
In: {one line}. Out: {one line}.

## Invariants
- **{Rule}.** {Why.}

## Conventions and golden paths
- Base branch: {branch}. Auth: {how}. Canonical commands: `{command}`.

## Decision rules
- {Condition} -> {choice}. Judgement calls cite `{reference skill}`.

## Procedures
1. {Deterministic, imperative step.}
2. {Next step.}

## Verification
- Run `{build / test / check}` and confirm {observable result}. The skill is not done until this passes.

## Pitfalls
- {Mistake} - {correct move}.

## Escape hatches
- {Case outside scope} -> {skill to use}.
```

A tool skill follows the workflow skeleton cut down to: when to use, the run command, a sub-command overview, and a link to its bundled `reference.md`.