Designing Skills That Stabilize Output: Template Fixing and Decision Guides in Claude Code

A practical design guide for stabilizing wobbly Claude Code skill output: stating when to use it, decision-guide tables, fixing quality with references templates, and traceability rules, with code from real operations.

Claude Code¹⁹⁶ Agent Skills² SKILL.md⁶ prompt design⁶

✦ Premium Article

The most frustrating thing about writing skills is output that differs every run despite the same prompt. I run article generation and quality checks for four sites as skills, and my early skills just wrote down "how to ask," so the structure and tone of the deliverable wobbled on every execution. Here's how to kill that wobble through design, drawn from a skill that converts spec docs into readable HTML and from how I operate my own article_gate.py.

The subject is a skill that "analyzes, restructures, and summarizes a spec doc into an HTML report with diagrams and badges." The crux is that it's a comprehension-bearing conversion, not a mechanical Markdown-to-HTML transform, and how you encode that into the design is what separates stable output from chaos.

Put "when to use, when not to" at the top of the body

The first thing to do is fix the task's premise at the top. Write only "convert" and weaker models read it as swapping Markdown tags for HTML tags; even strong models lean toward literal conversion depending on context. So declare up front that "this is a conversion that involves analysis, restructuring, and summarization."

## When to Use This Skill
- Convert a specification, requirements, or design doc into a
  readable HTML report (analyze, restructure, summarize)
- Make a Markdown spec easier for humans to read
- Add summaries, diagrams, and charts that aid comprehension
 
Do **not** treat this as a literal Markdown-to-HTML conversion
unless the user explicitly asks for a faithful conversion.

That "Do not" line does the work. In my article-generation skill too, after I stated up front, in the negative, that "this is not a task of summarizing the official docs," the drift toward template summaries dropped visibly. Write the unwanted interpretation in the negative with the same weight as the definition of what you want as the first step toward pulling output toward intent.

Give decision criteria as a table

Leave a skill room and "how to decide" wobbles every time. To kill that, make the decision branches explicit in the skill. The HTML skill gave "when to emit which diagram" as a table.

A step-by-step process → flowchart
API calls between systems → sequence diagram
Entities and relationships → ER diagram
A status lifecycle → state diagram

Just handing over this mapping makes the right diagram get selected automatically. My quality-check skill uses the same idea, embedding threshold judgments like "fewer than N signals is a violation, N or more passes" and doubling it up with article_gate.py. Rather than writing judgment in fuzzy prose, enumerate it as input feature -> output to take and the model's decisions stabilize.

✦

Thank you for reading this far.

Continue Reading

What follows includes implementation code, benchmarks, and practical content we hope you'll find useful. This site runs without ads — server and development costs are supported entirely by members like you. If it's been helpful, we'd be truly grateful for your support.

WHAT YOU'LL LEARN

✦Anyone frustrated by skill output that wobbled every run can now get stable output by fixing a references template

✦You'll learn to state when to use and when not to use a skill so 'convert' isn't misread as tag substitution

✦You'll embed decision-guide tables and traceability rules to prevent summaries from drifting off the source

✦You can apply references/ to your own skill to fix CSS and structure and reproduce output quality

Secure payment via Stripe · Cancel anytime

✦

Unlock This Article

Get full access to the rest of this article. Buy once, read anytime. This site is ad-free — your support goes directly toward keeping it running.

Unlock all articles with Membership →

Fix quality with a references template

Prompts alone leave the deliverable's style wobbling every run. The design that helps here is putting a template in references/. The skill body holds judgment and procedure; the concrete thing you want fixed gets offloaded into a template file.

skill-name/
├── SKILL.md                  # judgment / procedure (under 200 lines)
└── references/
    ├── template.html         # base HTML (contains CSS variables)
    └── components.md          # usage guide for each UI part

In the template, define the look you want fixed as CSS variables.

:root {
  --color-primary: #00a273;
  --color-primary-dark: #008a62;
  --color-surface: #f5f8f7;
  --font-sans: 'Hiragino Kaku Gothic ProN', sans-serif;
  --radius: 12px;
}

This "template plus component guide" combination is the trick: copy the CSS wholesale while generating only the content from the source doc, and you get stable output. Try to write everything in the body and the SKILL.md bloats, with the added risk that its back half goes unread. Offloading detail to references/ is exactly the same direction as the progressive disclosure I covered in the second half of my SKILL.md wasn't being read.

In my article-generation skill, splitting AUTHOR_VOICE_STYLE_GUIDE.md and PERSONALIZATION_MAX_GUIDE.md into separate files and only referencing them from the body is the same template-fixing idea. Write the "concrete things" like tone and banned patterns in the body and they wobble; fix them in a separate file and reference them, and reproducibility goes up.

Embed traceability as rules

When AI summarizes a document, there's always a risk the original meaning drifts. To prevent that by design, write traceability rules into the SKILL.md explicitly. The HTML skill embedded rules like these.

Label inferred content with Inferred or Assumption
Keep spec keywords (MUST / SHOULD / SHALL) verbatim
Copy API paths, field names, error codes, and enum values from the source unchanged
Don't interpret ambiguous spots; separate them into an "Open Questions" section

Rule-ify these four and you prevent the "it's summarized but you can't trace it back to the source" accident. My quality gate works the same way: I fix the mechanical-check regexes in article_gate.py so detection conditions aren't fuzzy. For example, the rule that rejects plain-form (常体) Japanese is written like this.

JOTAI_REGEX = [
    r"(?:^|[^\w])である[。．]",
    r"(?:^|[^\w])だった[。．]",
    r"[ぁ-んァ-ヶ一-龥]だ[。．]",
]
# Any single match counts as a violation and blocks the push

Fix, as rules, the spots that wobble when left to human judgment. In both skills and scripts, that's where I think the essence of stability lies.

Pitfalls I hit in production

A few things that tripped me up in real use.

Without binding "convert" in the negative, it falls to plain tag substitution. Without the leading Do not, even strong models lean mechanical depending on context.
Writing the template CSS in the body bloats SKILL.md. Past 200 lines, the back half risks going unread in cross-agent use.
Writing decision criteria in prose doesn't reproduce. Enumerating input features and corresponding outputs stabilizes it.
Without summary rules, source terminology drifts. Rule-ifying preservation of MUST / SHOULD and field names is the safe move.

Try it on one skill first

If you have a skill whose output wobbles, first carve "the look you want fixed" into references/template.html and rewrite the SKILL.md body to reference it. Just gathering the concrete things scattered through the body into one file changes how stable the output gets.

A skill's strength is that you can build a tool from prompts and templates alone. As an indie developer running multiple sites solo, this "judgment in the body, concrete things in templates" split has bailed me out many times. Fixing the orchestration itself with a script is covered in authoring Dynamic Workflows with phase / agent / pipeline, which should help you decide between skills and workflows.

Thank You for Reading

Claude Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.