skill-improver

Skill Improver

A meta-skill for auditing and enriching existing SKILL.md files.

---

Overview

The improvement cycle has four phases:

1. INGESTION   →  Read and map the skill
2. AUDIT       →  Analyze along 4 dimensions
3. REPORT      →  Prioritized findings + concrete proposals
4. IMPLEMENT   →  Rewrite (if requested / obvious)

You detect the user's intent from context:

• Audit only → produce the report, stop.
• Improve directly → produce the report AND propose a rewritten SKILL.md.
• Split → propose a sub-skill architecture, then optionally scaffold the files.

If intent is ambiguous, default to producing the report first, then ask.

---

Phase 1 — Ingestion

Read the target skill fully before doing anything else.

If the skill is in /mnt/skills/, it is read-only. Copy it to /tmp/ before editing:

cp -r /mnt/skills/user/<skill-name> /tmp/<skill-name>

Extract and note:

• name and description (frontmatter)
• Stated scope — what the skill claims to do
• Input types — what kinds of user requests it expects
• Output types — what it produces
• Bundled resources — scripts, references, assets
• Approximate complexity — line count, number of sections

If the SKILL.md body is long (>300 lines), note structural sections before auditing.

---

Phase 2 — Audit

Run all four dimensions. For each finding, assign a severity:

Severity	Meaning
🔴 Critical	Causes failures, contradictions, or major missing behavior
🟡 Important	Noticeably limits quality or range; should be fixed soon
🟢 Minor	Nice-to-have; low-effort polish

Read references/audit-dimensions.md for the full checklist per dimension.

Dimension 1 — Coverage (Unexplored Use-Cases)

Ask: What could this skill do that it currently ignores?

• Input variants the skill doesn't mention
• User intents that are adjacent but excluded
• Output formats or levels of detail not offered
• Settings, domains, or contexts where the skill would apply but isn't acknowledged
• Combinations with other skills not mentioned

Dimension 2 — Structural Integrity

Ask: Where would this skill produce bad output or confuse the agent?

• Vague or ambiguous instructions ("handle appropriately", "use judgment")
• Missing edge-case handling (empty input, malformed input, conflicting requirements)
• Contradictions between sections
• Steps that assume unavailable tools or context
• Outputs not defined clearly enough for consistent reproduction
• Instructions that are too long to follow reliably (cognitive overload)

Dimension 3 — Trigger Accuracy

Ask: Will the agent use this skill when it should, and avoid it when it shouldn't?

• Under-triggering risk: Is the description too narrow? Does it miss common phrasings?
• Over-triggering risk: Could it fire on unrelated queries?
• Ambiguity: Could it compete with another skill for the same trigger?
• Missing negative examples: Would a "do NOT use when..." clause help?
• Apply the "pushy description" principle: descriptions should actively push toward use, not just describe.

Dimension 4 — Granularity (Split Detection)

Ask: Is this skill doing too many distinct things?

Split criteria — recommend splitting if two or more apply:

• The skill has 3+ clearly separable workflows that rarely overlap
• The SKILL.md is >400 lines and growing
• The triggering description requires a long list of conditions to cover all cases
• Different user profiles would use different halves (e.g., beginners vs advanced)
• Sub-skills would each have distinct input/output contracts
• The skill contains multiple distinct output formats that are never combined

If split is recommended, propose a named architecture:

parent-skill/              ← optional thin orchestrator
├── sub-skill-a/SKILL.md
└── sub-skill-b/SKILL.md

---

Phase 3 — Report

Format the report as follows. Keep it actionable — each finding must include a concrete proposal, not just a diagnosis.

## Skill Audit: <skill-name>

### Summary
<2–3 sentence overview of the skill's current state and overall health>

### Findings

#### 🔴 Critical
- **[D2] Ambiguous output format**: Section X says "produce a summary" without
  specifying length, structure, or tone. Proposal: Add an explicit output template
  with labeled fields.

#### 🟡 Important
- **[D1] Missing input variant**: The skill only handles Markdown input, but users
  often paste raw text or HTML. Proposal: Add a short normalization step at the
  start that detects and handles these cases.

#### 🟢 Minor
- **[D3] Under-triggering risk**: Description doesn't mention "review" or "critique",
  which are common verbs for this skill's use-case.
  Proposal: Add "Also triggers on: review, critique, evaluate X" to description.

### Split Recommendation
<YES/NO — if YES, include the proposed architecture>

### Unexplored Avenues
<Numbered list of use-cases or extensions worth exploring, with brief rationale>

---

Phase 4 — Implementation

Proceed to implementation if:

• The user asked for it explicitly, OR
• Findings include 🔴 Critical items and the user hasn't said "just audit"

Rewriting a skill

1. Copy the original to /tmp/<skill-name>/ (if not already there)
2. Apply changes in order: Critical → Important → Minor (skip Minor if scope is tight)
3. Preserve the original name frontmatter exactly
4. Keep the overall structure unless restructuring is a Critical finding
5. After editing, show a before/after diff of changed sections (not the full file)
6. Ask the user to confirm before packaging

Scaffolding a split

1. Present the proposed sub-skill names and their scopes for user approval first
2. Once approved, create the directory structure under /tmp/
3. Draft a SKILL.md for each sub-skill
4. Optionally create a thin orchestrator SKILL.md at the parent level if workflows overlap

Packaging

If present_files is available:

python -m scripts.package_skill /tmp/<skill-name>

Otherwise, save to /mnt/user-data/outputs/<skill-name>/ and tell the user where to find it.

---

Interaction Style

• Start with the report. Don't silently rewrite — show your findings first.
• Be specific. "Section 3, paragraph 2 is vague" beats "the instructions could be clearer."
• Rank ruthlessly. A report with 12 🟢 Minor items and no 🔴 is a waste of the user's attention. Promote real problems, suppress cosmetic ones.
• Offer a choice after the report: "Want me to implement these changes now, or do you want to adjust priorities first?"
• If splitting: never split without user approval of the proposed architecture.

---

Reference files

• references/audit-dimensions.md — Full checklist per dimension with examples and anti-patterns