Writing Skills

AskUserQuestion Format

ALWAYS follow this structure for every AskUserQuestion call:

1. Re-ground: State the project, the current branch (use the _BRANCH value from preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
2. Simplify: Explain the problem in plain English a smart 16-year-old could follow. No raw function names, no internal jargon, no implementation details. Use concrete examples and analogies. Say what it DOES, not what it's called.
3. Recommend: RECOMMENDATION: Choose [X] because [one-line reason] — always prefer the complete option over shortcuts (see Completeness Principle). Include Completeness: X/10 for each option. Calibration: 10 = complete implementation (all edge cases, full coverage), 7 = covers happy path but skips some edges, 3 = shortcut that defers significant work.
4. Options: Lettered options: A) ... B) ... C) ... — when an option involves effort, show both scales: (human: ~X / CC: ~Y)

Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.

Completeness Principle

AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with AI. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans.

Effort reference — always show both scales:

Include Completeness: X/10 for each option (10=all edge cases, 7=happy path, 3=shortcut).

Completion Status

When completing a skill workflow, report status using one of:

• DONE — All steps completed successfully. Evidence provided for each claim.
• DONE_WITH_CONCERNS — Completed, but with issues the user should know about. List each concern.
• BLOCKED — Cannot proceed. State what is blocking and what was tried.
• NEEDS_CONTEXT — Missing information required to continue. State exactly what you need.

Escalation

It is always OK to stop and say "this is too hard for me" or "I'm not confident in this result."

Bad work is worse than no work. You will not be penalized for escalating.

• If you have attempted a task 3 times without success, STOP and escalate.
• If you are uncertain about a security-sensitive change, STOP and escalate.
• If the scope of work exceeds what you can verify, STOP and escalate.

Escalation format:

STATUS: BLOCKED | NEEDS_CONTEXT
REASON: [1-2 sentences]
ATTEMPTED: [what you tried]
RECOMMENDATION: [what the user should do next]

Writing Skills

This skill teaches how to create skills for YOUR project. It combines:

1. This file — skill design patterns, TDD for documentation, CSO
2. refs/ — official Claude Code documentation (auto-updated)
3. Companion files — testing methodology and persuasion research

Announce at start: "I'm using the writing-skills skill to create/edit a skill."

What is a Skill?

A skill is a SKILL.md file with instructions that Claude follows when relevant. Skills live in directories with optional supporting files:

my-skill/
  SKILL.md           # Main instructions (required)
  reference.md       # Detailed docs (loaded when needed)
  scripts/
    helper.sh        # Scripts Claude can execute

Where Skills Live

Project skills are shared with the team (committed to git). Personal skills are yours only.

Full discovery rules and monorepo support: Read refs/skills.md — section "Where skills live".

Skill Types

When to Create

Create when: technique wasn't obvious, you'd reference it again, pattern applies broadly, others would benefit.

Don't create for: one-off solutions, standard practices, project-specific conventions (put in CLAUDE.md instead), constraints enforceable with automation (use hooks instead).

SKILL.md Structure

Every skill starts with YAML frontmatter between --- markers, followed by markdown instructions.

Frontmatter

---