Skill Authoring

Drop into .claude/skills/ or .cursor/skills/ — the frontmatter drives when the skill loads.

---
name: skill-authoring
description: >-
  Write agent skill definitions that trigger reliably:
  description-as-trigger, situation-based phrasing, narrow scope, numbered
  rules, and explicit anti-patterns. Use when creating a SKILL.md or
  debugging a skill that never loads.
argument-hint: "[skill name]"
license: MIT
metadata:
  author: John Felix Lim
  version: "1.0.0"
---
# Skill Authoring

Apply when authoring or debugging a skill. If a skill is not firing when it should, the description is almost always the cause — rewrite it around symptoms and situations before touching the body.

## Rules

1. **The description is the whole trigger** — It is usually the only part the model reads when deciding whether to load the skill. A vague description means a skill that never fires, no matter how good the body is. Write it last, once you know what the skill actually does.
2. **Describe the triggering situation, not the topic** — 'React Native performance' is a subject heading. 'Use when a list stutters, a screen janks, or profiling shows excess re-renders' describes the moment the skill is needed — which is what the routing decision needs.
3. **Include the vocabulary users actually type** — People say 'laggy', 'janky', 'slow scrolling'. If none of those words appear in the description, the match will not happen when it should.
4. **One skill, one job** — A 'react' skill covering architecture, testing, styling, and performance triggers on everything and helps with nothing. Split until each skill has a clear moment it belongs to.
5. **Say what not to do, and when not to trigger** — Explicit anti-patterns and exclusions are what stop a skill from firing on adjacent-but-wrong tasks. They are as load-bearing as the positive guidance.

## Patterns

### Writing the description

**Avoid** — Matches everything and nothing. The model has no basis for deciding when this is the right skill.

```md
---
name: react-helper
description: Helps with React development
---
```

**Prefer** — Names the symptoms in the user's own words, states the coverage, and draws an explicit boundary.

```md
---
name: react-native-performance
description: >
  Diagnose and fix React Native performance problems — janky
  scrolling, stuttering lists, slow screen transitions, excess
  re-renders, dropped animation frames. Covers FlatList
  virtualization, memoization, Reanimated worklets, and context
  splitting. Use when a screen feels slow or profiling shows
  wasted renders. Not for build size or network latency.
---
```

### Body structure

**Avoid** — Prose with no actionable instruction. An agent cannot turn this into a decision.

```md
# React Native Performance

React Native performance is important. There are many things
that can affect it, including how you render lists, how often
components re-render, and how animations are implemented. You
should be careful about all of these things and try to optimize
where possible...
```

**Prefer** — Trigger conditions, numbered rules, named anti-patterns, and a verification step.

```md
# React Native Performance

## When to use
- A list stutters while scrolling
- A screen takes >100ms to become interactive
- Profiling shows components re-rendering without prop changes

## Rules
1. Measure in a release build on a mid-range Android device first.
2. Every list needs `keyExtractor`; fixed-height lists need
   `getItemLayout`.
3. No inline functions or object literals in `renderItem`.
4. Animations use Reanimated worklets or `useNativeDriver: true`.

## Anti-patterns
- `React.memo` on a row while the parent passes inline arrows
  (the memo can never bail out)
- One context holding values with different update frequencies

## Verify
Re-profile on the same device and confirm the frame drop is gone.
```

### Scope

**Avoid** — Over-broad scope means poor routing and a large context cost on every match.

```bash
skills/
  react/SKILL.md    # architecture + testing + styling +
                    # performance + state + navigation

# Triggers on every React task, dumps 800 lines of
# mostly-irrelevant guidance each time.
```

**Prefer** — Narrow skills route accurately and keep the loaded context relevant.

```bash
skills/
  react-native-architecture/SKILL.md
  react-native-performance/SKILL.md
  react-testing/SKILL.md
  typescript-conventions/SKILL.md

# Each triggers on a distinct moment and loads only
# what that moment needs.
```

## Review checklist

- [ ] The description names concrete triggering situations, not a topic.
- [ ] It includes the informal words users actually type.
- [ ] It states what the skill does *not* cover.
- [ ] The body opens with explicit 'when to use' conditions.
- [ ] Guidance is numbered rules, not prose.
- [ ] Anti-patterns are named, and there is a verification step.
- [ ] Triggering was tested with real prompts, including near-misses.

---

From the John Felix Lim Frontend Engineering Playbook — https://github.com/JohnFelixLim