Improve Skills
You are a Senior AI Skill Engineer running a systematic improvement pass over a skill library. For each skill: prune → fix gaps → link → research → rewrite → resize. Compression without improved quality is failure. All skills are in scope including meta skills.
Modes
FULL_PASS (default) — every skill in the library; runs Step 1 → 1b → 2 (looped) → 3 → 4.TARGETED — invoked as improve-skills TARGET=<skill> [SKIP_RESEARCH=true]. Entry point for learn-from-chat Step 5 escalation, and for user-driven single-skill fixes. Step 1 scopes validate-skills to TARGET only; Step 1b filters chat-learnings to TARGET; Step 2 runs once; Step 3 repairs cross-refs only for the modified skill. SKIP_RESEARCH=true skips only Step 2e — use when the change source is already trusted (chat-learning, prior research, user-supplied fix). Never skip 2b, 2h, 2j, 2k, 2l.
Hard Rules
Improve before compressing. Compressing a weak skill produces a smaller weak skill.
Split before compressing. Check for seams and duplication before trimming prose.
Fix structural gaps before rewriting. Gaps caught by validate-skills (missing category, missing Impact Report, missing file-output logging) are fixed in Step 2b — before the rewrite in Step 2e, so the rewrite doesn't have to undo them.
L3 examples mandate. External repo examples (e.g. addyosmani): secure-* SAFE first → full pairs in references/examples.md; never delete for line limits. Run build_examples_index.py.
Chat learnings are an input, not a mandate. docs/learnings/chat-learnings.md is consumed in Step 1b. Apply discretion — not every OPEN entry must land in a skill. Every entry must end the pass marked IMPLEMENTED, REJECTED, or DEFERRED with a reason. Silent skipping is a failure.
Workflow
Step 1 — Pre-flight via validate-skills
Invoke validate-skills across the full library. Use the report to:
- Fix any P0 failures (agentskills validate fails) before anything else
- Build the work queue ordered by score: lowest scores first
- Note all structural flags (missing category, Impact Report, file-output logging) — these are fixed in Step 2b for each skill
- Flag any skills scoring 0–5/14 as
deprecate-skill candidates (present to user, don't auto-deprecate)
Report the queue with scores and structural flags. Ask for confirmation before starting.
Step 1b — Ingest Chat Learnings
Read docs/learnings/chat-learnings.md (canonical log of chat-discovered learnings). For each entry with Status: OPEN (or missing), assign exactly one verdict:
IMPLEMENTED ([today], pre-existing in <skill> v<ver>) — already encoded in target skill as Hard Rule / Gotcha / workflow step.REJECTED (<reason>) — not generalizable; project- or context-specific.DEFERRED (<reason>) — target skill not in queue, or needs design work first.- keep
OPEN — generalizable, evidence-backed, fits a queued skill → attach to that skill as a Step 2g input.
In TARGETED mode, only entries whose affected skill matches TARGET are in scope; the rest stay OPEN. Present the triage table (date · summary · verdict · target skill) and wait for user confirmation before mutating the log or starting Step 2.
Step 2 — Per-Skill Improvement Cycle
Repeat for each skill in the queue:
2a — Prune first
Invoke prune-skill. Wait for prune report. Do not proceed until applied.
2b — Fix Structural Gaps
From the validate-skills report, fix any structural flags for this skill:
- Missing
metadata.category → add meta, project-specific, or domain (see docs/SKILL-INDEX.md)
- Missing `
Prune Log
Last pruned: 2026-07-04
- No changes — citation audit passed; content current (improve-skills full pass 2026-07-04)
Impact Report` section → add it (specific to what this skill produces)
- Skill generates files but no
docs/skill-outputs/SKILL-OUTPUTS.md logging → add the append instruction and terminal notification
- Stale rubric reference (e.g.,
improve-skills/references/scoring-rubric.md) → update to validate-skills/references/validation-rubric.md
- Orphaned
references/ file (not mentioned in SKILL.md) → add a specific load trigger or delete the file
- Missing load trigger on a
references/ file → add a specific trigger condition
- Missing P2 craft (project-specific): no
## Common Rationalizations and/or no ## Verification with ≥3 - [ ] items → add via add_p2_craft_project.py pattern or manual edit; run fix_craft_overflow.py if >200 lines
- addyosmani pattern pass (Meta B5): for
category: project-specific coding skills, verify rationalizations + verification + L3 references/examples.md ≥55 lines (not padding-only); relocate inline examples to L3, never delete
2c — Baseline Score (rubric: validate-skills/references/validation-rubric.md)
Score: Routing · Role Definition · Workflow · Gotchas · Output Format · Examples · Token Efficiency
Report: [skill]: X/14
2d — Link Check (scan before researching or rewriting)
Read all other skills in .agents/skills/. For each section of this skill:
- Does another skill already do this sub-workflow well? → link to it, remove the inline section.
- Does another skill do it partially? Could a small targeted change to that skill make it cover this fully, without pushing it over 200 lines or changing its core purpose? → make the minimal change to the target skill, then link.
- Does another skill benefit from calling this one? → add a caller note to that skill.
Link when: called skill's output is consumable by this skill (directly or after a marginal adaptation). Marginal adaptations to the target skill are allowed if: target stays under 200 lines, core purpose unchanged, existing callers unaffected.
Do NOT link when: the adaptation would require scope creep, a size violation, or breaking existing callers.
Document new links in AGENTS.md. Document target skill changes in the commit message.
2e — Research via research-skill (with security gate)
Invoke research-skill. Mandatory: any external content must be scanned by ALL secure-* skills in sequence before use (discover via ls .agents/skills/secure-*). SAFE only if every security skill returns SAFE. If any returns BLOCKED, discard. Cannot be skipped.
Use GOTCHAS → Gotchas, WORKFLOW PATTERNS → steps, FAILURE MODES → hard rules.
2f — Classify with SkillReducer Taxonomy
Tag every block: CORE · WORKFLOW · FORMAT · EXAMPLE · BACKGROUND · EDGE_CASE · DUPLICATE · STALE
BACKGROUND and EDGE_CASE move to references/ with specific load triggers.
2g — Rewrite in priority order
- Fix routing — add missing trigger phrases
- Merge any chat-learnings queued for this skill in Step 1b into the matching section (GOTCHA → Gotchas, FAILURE_MODE → Hard Rules or Gotchas, TECHNIQUE → Workflow). Cite:
Chat learning [YYYY-MM-DD].
- Add gotchas from research
- Sharpen workflow — imperative one-liners, MUST/NEVER
- Replace synthetic examples with realistic ones — if >1 or >15 lines total, write
references/examples.md and keep one teaser inline; never delete an example without an L3 home
- Tighten output format schema
- Move BACKGROUND to
references/background.md
- Bump
metadata.version
2h — Deconflict Name and Triggers
Invoke skill-deconflict in single-skill mode. If RENAME or REVISE verdict, apply fixes before proceeding. Report findings in the per-skill output.
2i — Post-Rewrite Score — report delta: X/14 → Y/14
2j — Size Check
wc -l .agents/skills/<skill>/SKILL.md
Under 200 → proceed to 2k.
Over 200 → invoke split-skill. It checks for link opportunities first, then extracts a new child only if needed, then compresses.
Exception: secure-skill — never compress, only split. Threshold is 180 lines (not 200). If secure-skill exceeds 180, invoke split-skill but instruct it to skip the compression step on the security skill.
2k — Validate and Commit
agentskills validate .agents/skills/<skill>/
git commit -m "improve: <skill> — <before>/14 → <after>/14\n\n- [change]\nSources: [source]"
2l — Close Chat Learnings
For every chat-learning entry merged into this skill in 2g, edit its entry in docs/learnings/chat-learnings.md: change Status: OPEN → Status: IMPLEMENTED ([YYYY-MM-DD], <skill> v<new-version>). For entries the pass triaged as REJECTED or DEFERRED in Step 1b, write the verdict and reason back to the log now. Every entry that started this pass with Status: OPEN MUST end the pass with a terminal status.
Step 3 — Cross-Link Repair
Invoke cross-link-skills with trigger rewired — [list of skills modified]. It scans all SKILL.md files for stale or missing cross-references caused by rewrites, renames, or new link wiring from Step 2d.
Step 4 — Library Summary
Report scores, structural gaps fixed, new links created, cross-references repaired, sources used, files modified, and chat-learnings closed (count by terminal status).
Gotchas
- Never move gotchas to
references/ — agent reads them before encountering the situation.
- Description rewrites must preserve all existing trigger phrases — only add, never remove.
- Link check: a relationship that requires transforming the called skill's output is not a clean delegation — keep inline.
- Structural gaps from validate-skills are fixed in 2b, not left for the rewrite in 2g.
- Chat learnings ingested in Step 1b inform Step 2g — they do not bypass
secure-* scans or the 200-line gate. A learning that can't fit is DEFERRED, not crammed.
- Triage verdicts (REJECTED / DEFERRED) must be written back to
chat-learnings.md in the same pass — leaving them OPEN re-surfaces them next cycle.
Example
<examples>
<example>
<input>Improve all skills in the repo</input>
<output>
Pre-flight validate-skills report:
brainstorming: 10/14 | structural: missing Prune Log (>30 days)
prd-writing: 9/14 | structural: none
research-skill: 12/14 | structural: none
Queue confirmed (all skills, lowest score first).
1b Chat learnings: 4 OPEN → 1 queued (prd-writing), 2 pre-existing, 1 deferred.
prd-writing (1): 2c 9/14 | 2g merged 1 chat-learning + 2 research gotchas → 12/14, 139 lines ✓ | 2l: 2026-04-12 → IMPLEMENTED (prd-writing v1.3)
brainstorming (2): Prune Log added; 13/14; 170 lines ✓
Summary: 2 skills improved (+3 avg); chat-learnings: 4 OPEN → 1 impl · 2 pre-existing · 1 deferred
</output>
</example>
</examples>
Common Rationalizations
| Excuse | Reality |
|---|
| "Skip validate pre-flight" | Improving blind wastes cycles on already-healthy skills. |
| "Research every skill" | SKIP_RESEARCH=true is valid when AO patterns already ingested. |
| "One skill is enough" | Batch structural gaps compound library quality. |
Verification
Red Flags
- Gotchas moved to references/ away from pre-encounter path
- Description rewrite removed existing trigger phrases
- External pattern applied before secure-* SAFE clearance
- Delegated link claimed where output transform is required
Reference Files
validate-skills/references/validation-rubric.md: Scoring rubric (single source of truth). Read during Step 2c.
Impact Report
Improvement cycle complete: YYYY-MM-DD Skills processed: N Skills improved: N (avg score delta: +N pts) Structural gaps fixed: N (list by skill) New skill links created: N (list re