CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

A Claude Code plugin containing a single skill, refine-prompt. There is no application code, no build step, and no runtime - every file is either a manifest or a model-facing instruction payload. Editing this repo means editing prompts, so the change you make is the behavior change; there is no compile step between them.

The skill's job: take a prompt that drives real work and replace vague exhortations ("be thorough", "ask lots of questions") with mechanisms a model will actually execute.

Architecture: three loading tiers

The layout is driven by Claude Code's progressive disclosure, not by aesthetics. Each tier is read at a different moment, and that determines what belongs in it:

commands/refine-prompt.md is a thin /refine-prompt wrapper that delegates to the skill. It deliberately contains no method - it says "the skill owns the method, follow it as written rather than a summary of it." Keep it that way; a summary in the command would drift from the skill and silently win, since the command text arrives after the skill body.

The description has a hard 1024-character cap

Descriptions over 1024 characters are silently truncated, not rejected. This already bit this repo once: the description sat at 1060 chars, so it was cut mid-word at "or me" and the final exclusion - "or merely translating an existing prompt" - never reached the model, weakening a false-trigger guard in the shipped plugin. Fixed 2026-07-25 by removing redundant wording; it is now 1010 chars, leaving only 14 of headroom.

Check the count before and after any description edit:

python -c "
import yaml,re
c=open('skills/refine-prompt/SKILL.md',encoding='utf-8').read()
d=yaml.safe_load(re.match(r'^---\n(.*?)\n---',c,re.DOTALL).group(1))['description'].strip()
print(len(d),'/1024')"

Adding a trigger phrase or an exclusion now requires removing something else. Prefer cutting redundant wording over cutting an exclusion - exclusions are what prevent false fires, and the truncation bug above was itself the loss of an exclusion.

Do not trust quick_validate.py's reported length on Windows: it calls read_text() without encoding=, decodes UTF-8 as cp1252, and counts each em-dash as three characters. Its pass/fail verdict is correct; its number runs ~4 high here.

The invariant that matters most

Tier 2 and tier 3 must not duplicate each other. principles.md opens by stating this explicitly: "What the runbook already states is deliberately not repeated here." SKILL.md carries the mechanism; principles.md carries only the reasoning you need when judging an unusual fit or extending the table.

This is easy to violate by accident and there is no test for it. When a mechanism changes, check both files.

Adding or changing a smell-table row

The smell table in SKILL.md is the core of the skill. A row is a triple: smell in the draft | why it fails | mechanism to replace it with. Adding one touches three files that must stay in sync:

1. SKILL.md - the row itself.
2. references/principles.md - the rationale, under "Why the mechanisms take the shape they do", without restating the row.
3. skills/refine-prompt/evals/evals.json - an eval whose expected_output exercises it.

Do not delete a row merely because evals show a capable model handles it unprompted. principles.md states the standing decision: "absence of evidence that a row helps is not evidence that it does nothing," and such rows are kept as cheap insurance. It names the reversibility gate and read-the-artifact as exactly this case.

The eval suite

skills/refine-prompt/evals/evals.json holds 6 evals (ids 1-6). They are not self-grading assertions - expected_output is prose read by a human or judge model. Two conventions are load-bearing:

• CHANGE TABLE PASS CONDITION (evals 1, 3, 4, 6) - a verbatim-repeated block demanding a markdown table with exactly three columns, and explicitly rejecting near-misses ("a prose list, a two-column table, or a 'why these changes' section does NOT satisfy this"). This phrasing exists because a checkable assertion discriminates and a vague one does not. Reuse the block verbatim rather than paraphrasing it.
• Eval 5 is a negative test - a one-line prompt that must produce a proportionate reply. It fails if the skill spins up the full method. Any change that makes the skill more thorough risks breaking eval 5; check it specifically.

Eval 4 depends on evals/fixtures/SPEC.md, a deliberately flawed URL-shortener spec. Its planted defect is that short codes are base62 of the hit counter - semantically wrong and broken with more than one instance. Keep that defect intact; eval 4 tests whether the skill reads the artifact and names the bug.

Paths in an eval's files array resolve from the skill root, not from evals/. So the fixture is declared evals/fixtures/SPEC.md, matching skill-creator's references/schemas.md ("input file paths (relative to skill root)"). This was wrong until 2026-07-25 - it read fixtures/SPEC.md, which only resolves relative to evals/. Nothing in skill-creator's code reads the field, so it happened to work; anything implementing the written spec would have failed to find the fixture and silently turned eval 4 into a no-op.

Why evals/ lives inside the skill directory

Not a stylistic choice, and don't relocate it to a top-level tests/:

• package_skill.py strips it positionally - ROOT_EXCLUDE_DIRS = {"evals"} matched against parts[1], where parts[0] is the skill folder. The exclusion exists because evals are expected inside the skill directory.
• skill-creator's spec names the path: "Located at evals/evals.json within the skill directory." Tooling and future sessions look there.
• It stays unambiguous if this repo ever ships a second skill; a root-level tests/ would not.

The scope gate is a feature, not a bug

SKILL.md opens with a scope gate routing small asks to inline substitutions only, and "nothing flagged" to a one-line null verdict. Demoing on a simple prompt will correctly produce an unimpressive diff. That is the gate working. Do not "fix" it by making the skill more eager - that is the same error as "be thorough": effort pointed at the wrong thing.

Commands

Skill-only plugins conventionally ship no build, lint, or test toolchain, and this one follows that convention. Anthropic's own marketplace publishes ~40 pure-markdown plugins with no CI, no tests, and no build step. Plugins that do carry tooling carry it because they ship executable code

• a statusline renderer, hook scripts, a registry generator. There is nothing here to compile and nothing to unit-test: every file is a manifest or a model-facing instruction payload.

So the absence below is deliberate, not a gap to fill. Verification is review plus the manual checklist further down, aided by two scripts that ship with the separate skill-creator plugin (install it with /plugin install skill-creator if missing).

Its install path varies - it may sit under plugins/marketplaces/... or plugins/cache/..., and more than one copy can coexist. Discover it rather than hardcoding a path. Run from the repo root:

SC=$(find ~/.claude/plugins -type d -path '*/skills/skill-creator' | head -1)
REPO=$(pwd)

# Structural validation: frontmatter, kebab-case name, 1024-char description cap.
# Standalone script, one arg. Exits 0/1.
python "$SC/scripts/quick_validate.py" "$REPO/skills/refine-prompt"

# Package for distribution - emits refine-prompt.skill into dist/.
# MUST run as a module from the skill-creator dir; the subshell avoids leaking cwd.
# PYTHONIOENCODING is required on Windows and harmless elsewhere.
mkdir -p "$REPO/dist"
( cd "$SC" && PYTHONIOENCODING=utf-8 \
    python -m scripts.package_skill "$REPO/skills/refine-prompt" "$REPO/dist" )

PowerShell equivalent for the packaging step:

$SC = (Get-ChildItem ~/.claude/plugins -Recurse -Directory -Filter skill-creator |
       Where-Object { Test-Path "$_/scripts/package_skill.py" } | Select-Object -First 1).FullName
$REPO = $PWD
$env:PYTHONIOENCODING = 'utf-8'
Push-Location $SC
python -m scripts.package_skill "$REPO/skills/refine-prompt" "$REPO/dist"
Pop-Location

package_skill.py excludes evals/ from the archive by design - ROOT_EXCLUDE_DIRS = {"evals"}, applied only at the skill root. The produced archive contains exactly SKILL.md and references/principles.md.

Manual checklist before publishing a change

Nothing enforces any of these. quick_validate.py catches only the first one, and only because the cap is part of the skill spec - the rest are this repo's own invariants, invisible to any external tool. Every one of them has a section above explaining why it matters.

If you find yourself running these often enough to resent it, that is the signal to write a validator - not before. The convention is no tooling; deviating from it needs a reason this repo's history actually supplies.

Windows failure modes

Every one of these is the same upstream bug class - Python defaulting to cp1252 instead of UTF-8. Do not re-debug them; they are not this repo's bugs.

Consequence: the skill description was hand-tuned for triggering, not optimizer-derived. Grade evals by hand, or run the optimizer on non-Windows.