A SKILL.md at ~/.claude/skills/{name}/SKILL.md looks simple. It's markdown with frontmatter. But the difference between a skill that works every session and a skill that drifts is in 4 specific structural choices most examples skip.
Here's what a production skill actually contains.
---
name: pr-review-comprehensive
description: Run a 7-lens review on a pending PR. Use when the user asks to review a PR, review pending changes, or audit a branch before merge.
---Two fields. Both matter:
name— lowercase-kebab-case. Claude Code uses this as the invocation identifier (use the pr-review-comprehensive skill). Keep it short; keep it memorable.description— this is what Claude reads to decide when to auto-invoke the skill. Write it as "Use when the user asks to X, Y, or Z." Not "Reviews PRs." The trigger-intent framing matters — vague descriptions lead to skills that fire at the wrong moment or never fire at all.
Explicit. Not "take whatever they give you":
## Inputs
If the user didn't specify, confirm:
- PR number, URL, or branch name
- Base branch (usually `main` or `master`)
- Known constraints (e.g., "don't flag the deprecated `old_payments.ts`")A skill that doesn't ask for missing inputs will invent them. The input section forces the clarifying-question behavior before any work starts.
The difference between a skill and a prompt is: a skill declares sequence. Not "here's what to consider" but "run these in order":
## The seven lenses, in order
Run them sequentially. Each writes its findings as you go; don't batch.
### 1. Intent drift
Does the diff match the PR description? ...
### 2. Logic correctness
Walk through every non-trivial branch. ...
### 3. Test gaps
..."In order" and "don't batch" are the two phrases that keep the output consistent. Without them, Claude will collapse multi-step work into a single gestalt and skip whatever didn't get attention.
This is the non-negotiable part:
## Output format
Structured markdown, one section per lens. Under each, findings as:
- [severity] file:line — one-sentence finding + suggested action
Severities: blocker, major, minor, nit.
End with a verdict line: APPROVE, APPROVE with comments, REQUEST CHANGES, or BLOCK.Why structured output changes everything:
- You can grep:
output | grep '\[blocker\]'returns blockers - You can pipe into CI: fail build if
[blocker]appears - You can track severity over time across PRs
- Reviewers can scan 50 findings in 15 seconds instead of reading 50 prose paragraphs
A skill without a declared output format is a skill that produces drift-prone prose. Declare the shape; get consistency.
The single most underused feature of skills. Explicit refusals:
## What this drill refuses to do
- Approve a PR it hasn't reviewed in full. Reading only the description or commit messages is not a review.
- Generate a "LGTM" without specific citations. Every approve must name at least three things it actually verified.
- Speculate about files outside the diff. Comment only on what changed.Refusals let a skill fail loudly instead of hallucinating quietly. An approval without citations gets rejected by the skill itself, not by you after the fact. A review that speculates about unseen code gets cut.
Most people skip the refuses section because it feels negative. It's the opposite: a skill with strong refusals is a skill you can trust to hold the line under pressure (long context, late PRs, 2am debugging).
- Explicit inputs — ask for missing context; don't invent it.
- Ordered steps — "in order, don't batch" are load-bearing words.
- Structured output — declare the shape; produce greppable artifacts.
- Refuses to — bake failure modes into the skill so they can't be accidentally bypassed.
Any skill missing one of these drifts. Any skill that has all four behaves the same on Monday morning as on Friday afternoon.
If you want 25 production-grade skills with this exact structure — covering PR review, test gaps, migration safety, security triage, refactor, dead-code, type tightening, env audit, changelog, postmortem, launch copy, and 14 others — the full pack is at septimlabs.vercel.app/drills for $29 lifetime.
3 free samples (including readme-sync, commit-quality, launch-post-hn) are open-source at github.com/septimlabs-code/septim-drills-samples — read one before you pay.
Tonight only: Drills + Vault (encrypted dev-secret vault) bundled for $39 — septimlabs.vercel.app/tonight. Expires midnight ET.
Also: a free CLAUDE.md analyzer that audits your current file against these principles is at septimlabs.vercel.app/tools/claude-md-analyzer.
Septim Labs — April 20, 2026.