# Skill skeletons

Two skeletons - pick by layer. Both stay lean; push detail into one-level-deep bundled files.

Frontmatter fields used in this toolkit: `name`, `description` (required-quality), `user-invocable`, `argument-hint` (optional), `allowed-tools`.

---

## Reference skill (descriptive - knowledge)

No numbered procedures. Principles + pointers + heuristics.

```markdown
---
name: <aspect-noun>          # e.g. navigation - NO platform prefix
description: <what it covers + when to reach for it + trigger words. Say "iOS/SwiftUI" so the router can disambiguate.>
user-invocable: true
allowed-tools: Read, Grep, Glob, Bash, Edit, Write
---

# <name> - <short title>

> **Layer:** reference (knowledge)
> **Use when:** <trigger>   **Hand off to:** <sibling skill>

## Scope
In / out, 1-2 lines.

## Invariants            <!-- non-negotiables + the why -->
## Conventions & golden paths   <!-- point to canonical files; don't paste code -->
## Decision rules        <!-- if X do A; when unsure, ask/verify -->
## Pitfalls              <!-- known traps -->
## Escape hatches        <!-- when this doesn't apply → which skill -->
```

---

## Workflow skill (imperative - action)

Has a numbered procedure, but only for the deterministic/irreversible spine. Cite reference skills for judgment. Always include a verification gate.

```markdown
---
name: <verb-phrase>         # e.g. branch-and-pr
description: <what it does + when to run it + trigger words (iOS/SwiftUI).>
user-invocable: true
argument-hint: [<step> | ...]
allowed-tools: Bash, Read
---

# <name> - <short title>

> **Layer:** workflow (action)
> **Use when:** <trigger>   **Don't use when:** <hand off>

## Scope
In / out, 1-2 lines.

## Invariants            <!-- hard rules / guardrails -->
## Conventions & golden paths   <!-- base branch, auth, canonical commands -->
## Decision rules        <!-- branch when..., escalate when... -->
## Procedures            <!-- IMPERATIVE: only deterministic/irreversible steps -->
1. ...
## Verification          <!-- IMPERATIVE: prove it worked (build/run/test) -->
## Pitfalls
## Escape hatches
```