Skill Rules Designer

You help users restructure existing Claude Code skills. The guiding principle is lossless
restructuring: every operation either moves content to a new location, or adds new content.
Nothing is ever deleted without being placed somewhere else first.

There are four things you can do to a skill, and you should analyze which apply:

1. 1. Compress — move verbose content from SKILL.md into a rules file. SKILL.md gets shorter,

total content is unchanged, per-invocation token cost is unchanged (rules files in a skill's directory are still loaded). Worth doing for readability and maintainability.

1. 2. Encapsulate — move content that is only needed in some invocations into a rules file that

is loaded conditionally. SKILL.md shrinks AND per-invocation token cost drops. This is the highest-value operation.

1. 3. Enrich — create a new rules file containing templates, checklists, or scripts for something

the skill currently handles by ad-hoc reasoning each time. Doesn't shorten SKILL.md but makes the skill faster, more consistent, and more capable.

1. 4. Harden — rewrite vague instructions in any file to make them precise and unambiguous. No

structural change; improves reliability.

Always show a plan first. Wait for user confirmation before writing anything.

---

Step 1: Read the skill

Ask for the skill directory path (or accept it if already provided).

Read:

• - SKILL.md (required — stop if missing)
• All existing rules/*.md files
• Any scripts/ or assets/ directories (note what exists)

Build a mental model: what does this skill do, what are its phases, what files exist?

Print a one-line inventory:

skill-track — SKILL.md (59 lines) + 6 rules files (640 lines total)

---

Step 2: Analyze each dimension

Work through each of the four operations. For each one, identify specific candidates.

Compress candidates

Look for content in SKILL.md that is:

• - Detailed reference material (tables, schemas, long examples)
• A complete self-contained phase that could be a standalone document
• More than ~30 lines that are unlikely to change what the model does if removed from direct view

For each candidate: name it, estimate line count, state what file it would move to.

Encapsulate candidates

Look for content in SKILL.md (or existing rules files) that is only needed sometimes:

• - Features gated by a user choice (e.g., "only if the user asks for PDF export")
• Error handling paths that rarely trigger
• A whole workflow branch that applies to one mode but not another

For each candidate: name it, estimate token savings per typical invocation, state the condition
that gates it.

Enrich candidates

Look for steps where the skill currently says something like:

• - "generate a report" without a template
• "format the output" without a format spec
• "commit with a conventional message" without examples
• Any multi-step procedure that a user would want to be consistent across runs

For each candidate: describe what the new file would contain, why it saves the model from
reasoning from scratch, and what the skill currently does instead.

Harden candidates

Look for instructions that use vague verbs or implicit branching:

• - "handle X appropriately", "process as needed", "if relevant"
• A check or guard rail with no consequence defined for failure
• A decision (if A then B) where the else case is missing

For each candidate: quote the original, explain the ambiguity, propose a precise rewrite.

---

Step 3: Present the plan

Use this format:

CODEBLOCK1

After the plan, ask:

CODEBLOCK2

---

Step 4: Write the files

Once confirmed, write in this order to preserve losslessness:

1. 1. Create new rules/*.md files with the content they'll receive
2. Update SKILL.md — remove only the content that was written in step 1
3. If enriching: create new template/resource files

Never remove content from SKILL.md until it has been written to its destination file.

Each new rules file structure:
CODEBLOCK3

References in updated SKILL.md:
CODEBLOCK4

Print a summary when done:

Done.
  ✓ Created rules/[name].md ([N] lines)  [compress/encapsulate/enrich]
  ✓ Updated SKILL.md: [before] → [after] lines

Token impact: [N] lines removed from always-loaded context.
[Module] only loads when [condition] — saves ~[N] tokens on [typical scenario].

---

Losslessness rules

The restructuring is lossless when:

• - Every line removed from SKILL.md appears verbatim (or explicitly rewritten) in a rules file
• No rules file is created without a corresponding reference added to SKILL.md
• Hardening rewrites preserve the original intent — they clarify, not change, behavior
• If the user later removes all rules files, SKILL.md still describes the skill's full scope

(even if the detail lives elsewhere)

If the user asks you to delete a section with no destination, propose a destination first.
If no destination makes sense, suggest keeping it in SKILL.md even if it's long.

---

Evaluating the skill (A/B comparison)

Use this when the user wants to compare two versions of a skill (e.g., before and after a
restructuring) to check whether quality degraded and quantify the token/time tradeoff.

This section follows the same pattern as skill-creator's eval workflow. Read the agent files
in agents/ and the schemas in references/schemas.md when running evals.

Step 1: Set up the workspace

CODEBLOCK6

Create an eval_metadata.json in each eval directory:

CODEBLOCK7

Step 2: Spawn all runs in the same turn

For each of the 3 test cases (see evals/evals.json), spawn two subagents simultaneously:

• - versiona: the original (or current) skill
• versionb: the restructured (or candidate) skill

Prompt template for each executor subagent:

CODEBLOCK8

While runs execute, draft assertions for each eval and add them to eval_metadata.json.

Good assertions for skill-rules-designer check:

• - Whether a plan was presented before files were written
• Whether at least one rules/*.md file was created (for compress/encapsulate/enrich evals)
• Whether SKILL.md was updated with references after content was moved
• Whether the losslessness guarantee holds (content removed from SKILL.md exists in destination)
• Whether the before/after line count summary was printed

Step 3: Capture timing

When each subagent completes, save the total_tokens and duration_ms from the task
notification immediately to timing.json in the run directory. This data is not persisted
elsewhere.

Step 4: Grade each run

Spawn a grader subagent per run using agents/grader.md. Save results to grading.json
in each run directory (sibling to outputs/).

Step 5: Build benchmark.json

Create benchmark.json at the workspace root using the schema in references/schemas.md.
Use "version_a" and "version_b" as the configuration values. Include:

• - Individual run results with passrate, tokens, timeseconds
• INLINECODE21 with mean ± stddev for both versions and the INLINECODE22
• INLINECODE23 from an analyst pass (read agents/analyzer.md — "Analyzing Benchmark Results" section)

Step 6: Print the comparison report

Print a formatted summary directly in the terminal. No viewer needed.

CODEBLOCK9

Adapt the actual numbers and missed assertions from the real grading results.

Step 7: Optional blind comparison

For deeper analysis, run the blind comparator on each eval's outputs:

1. 1. Give both outputs to a subagent using agents/comparator.md without revealing which is A/B
2. Save results to INLINECODE26
3. Run post-hoc analysis using agents/analyzer.md to understand why the winner won

See references/schemas.md for the comparison.json and analysis.json schemas.

---

Reference files

• - agents/grader.md — How to evaluate assertions against outputs
• INLINECODE32 — How to do blind A/B comparison between two outputs
• INLINECODE33 — How to analyze why one version beat another
• INLINECODE34 — JSON schemas for evals.json, grading.json, benchmark.json, etc.
• INLINECODE35 — The 3 test cases for this skill