# Examples - descriptions & shape

## Descriptions: the discovery lever

**Bad (vague - rarely triggers):**
```yaml
description: Helps with navigation
```
Why it fails: no "when", no trigger words, no platform - the router can't tell what task this matches.

**Good (what + when + triggers + platform):**
```yaml
description: "In-app navigation for a SwiftUI iOS app - the coordinator-per-domain pattern, the tab shell, cross-domain navigation, deep links, and modals. Reach for this when adding a screen, a tab, a deep link, or a modal, or deciding how one screen reaches another."
```
Why it works: states the domain, lists concrete triggers ("adding a screen, a tab, a deep link"), names the platform, and implies the boundary.

**Workflow example (action + when to run):**
```yaml
description: "Branch, commit, push, and open a PR for this repo. Owns the git/PR spine and house guardrails - type-first branch names, no AI attribution, no force-push, correct base branch. Reach for this whenever a change is ready to ship."
```

### Recipe
`<what it covers/does> + <concrete when/trigger phrases> + <platform> + <implied boundary vs siblings>`

---

## Shape: reference vs workflow

**Wrong - a reference skill drifting into a procedure:**
```markdown
## Procedures
1. Open the file
2. Add the wrapper
3. Register the route
4. Build and run
```
A reference (knowledge) skill should describe *the rule and where the canonical example lives*, not script the keystrokes.

**Right - reference stays descriptive:**
```markdown
## Decision rules
- New screen in a domain → add `<Name>Screen` under its Presentation layer,
  wrap content in the domain's container, route via the domain coordinator.
  Canonical: `<repo>/Features/Profile/ProfileScreen.swift`.
```

**Right - workflow earns its numbered steps** (deterministic/irreversible spine):
```markdown
## Procedures
1. Pre-flight: `git status` clean? on base branch?
2. Branch: `git checkout -b <type>/<scope>/<desc>`
3. Commit: stage; conventional message; strip any AI co-author trailer.
4. Push; never force-push a protected branch.
5. PR: `gh pr create --base <base> ...` (no AI footer).
## Verification
- `git log -1` shows clean message, no AI trailer, correct author.
```

---

## Leanness: cut what the model already knows

**Bloat:** "PDF files are documents that contain text and images. To read them you first need a library that can parse the binary format..."

**Lean:** "Extract text from PDFs with `pdfplumber`."