# Examples

## Descriptions

### Weak

```yaml
description: Helps with navigation stuff.
```

No situation, no trigger words, no platform. The router has nothing to match a request against, so the skill stays unloaded.

### Strong, reference layer

```yaml
description: "Navigation for iOS / SwiftUI: NavigationStack paths, tab structure, deep links, sheets and full-screen modals, and where routing state lives. Use when adding a screen, a tab or a deep link, presenting a modal, or debugging a push that does nothing. Triggers: 'add a new screen', 'open this from a deep link', 'present as a sheet'."
```

Coverage, concrete situations, the platform, and quoted phrases a developer would type. The domain words keep it apart from sibling skills on state or overlays.

### Strong, workflow layer

```yaml
description: "Creates a branch, commits, pushes and opens a pull request with the house guardrails: type-first branch names, conventional commit messages with no AI attribution, never a force push, and the correct base branch. Use when work is ready to ship. Triggers: 'open a PR', 'commit and push this', 'create a branch for this ticket'."
```

States the action, the guardrails that make it safe, when it applies, and how users ask for it.

## Layer shape

### Wrong: a reference skill written as keystrokes

```markdown
## Adding a tab
1. Open AppTabView.swift.
2. Add a case to the Tab enum.
3. Add a .tabItem block under the last one.
4. Build.
```

A reference skill describes; it does not dictate. These steps go stale the first time the file changes.

### Right: the rule plus where to look

```markdown
## Conventions
- Tabs are cases of the root `Tab` enum; each case owns its own navigation path.
  Canonical file: `App/Sources/AppTabView.swift`.
```

### Right: a workflow that earns its steps

```markdown
## Procedures
1. Pre-flight: `git status` is clean and the base branch is correct.
2. Create `{type}/{scope}-{short-description}`.
3. Commit with a conventional message; strip any AI co-author trailer.
4. Push without `--force`; never to a protected branch.
5. `gh pr create --base {base}` with no AI footer in the body.

## Verification
- `git log -1` shows a clean message, no AI trailer, and the expected author.
```

Every step is deterministic or irreversible, and the skill proves its result before it finishes.