skill-optimizer

name

skill-optimizer

description

"Optimize an existing agent skill by running /sensei --gepa, tightening agentskills.io compliance, moving bulky guidance out of SKILL.md into references/, and creating agentevals.io-style evals. Use this whenever the user asks to improve a skill's triggering, shrink an overgrown SKILL.md, refactor a skill into progressive disclosure, or add repeatable evals for a skill under skills/ or .agents/skills/."

Skill Optimizer

Use this skill to improve an existing agent skill without losing the original intent or public identity.

Core goals

• Improve the target skill with /sensei --gepa before doing large manual rewrites.
• Keep the main SKILL.md compact, triggerable, and focused on how the skill should be used.
• Move long examples, schemas, scoring rubrics, and extended recipes into references/ so they load on demand.
• Create evals/evals.json in an AgentEvals-style shape so the skill has repeatable evaluation coverage.
• When part of the workflow is deterministic, replace repeated free-form reasoning with small TypeScript scripts in the optimized skill's own ./scripts/ folder, developed through red/green TDD.

Workflow

1. Resolve the canonical skill path.
   • Accept a target under skills/<name>/ or .agents/skills/<name>/.
   • If the incoming path is a symlink, edit the canonical bundle rather than the compatibility link.
   • Preserve the existing skill name, folder name, and user-facing purpose unless the user explicitly asks to rename them.
   • Use scripts/resolve-optimization-plan.ts as the deterministic source of truth for canonical path resolution, expected bundle outputs, and the first-pass optimization plan.
2. Audit the target before changing it.
   • Check frontmatter shape, trigger clarity, line count, and whether the body has turned into a README instead of an activation guide.
   • Identify content that belongs in references/ rather than the main SKILL.md.
   • Identify deterministic work that would be safer or faster as executable code.
3. Run /sensei --gepa on the target skill first.
   • Use GEPA mode to improve frontmatter and routing before manual restructuring.
   • Review the proposed changes instead of accepting them blindly, especially if they weaken the user's intent or remove important disambiguation language.
4. Refactor for progressive disclosure.
   • Keep in SKILL.md: frontmatter, when to use the skill, the short workflow, the important constraints, and pointers to reference files.
   • Move to references/: long examples, schemas, benchmark guidance, migration recipes, scoring details, or troubleshooting that would dilute the main prompt.
   • Add clear references from SKILL.md so the model knows when to read deeper material.
5. Add or update AgentEvals-style coverage.
   • Create evals/evals.json with realistic prompts, expected outcomes, optional files, and concrete expectations.
   • Prefer prompts that test both core success paths and near-miss cases where the skill might overtrigger or undertrigger.
   • Keep evals realistic enough that a model would actually consult the skill instead of handling the task with generic tools alone.
6. Convert deterministic work into TypeScript.
   • When the workflow includes repeated parsing, validation, packaging, migration, reporting, or structural transforms, write a script in the optimized skill's ./scripts/ folder instead of describing the procedure vaguely.
   • Start with a failing test, implement the smallest passing script, then refactor while keeping tests green.
   • Keep scripts composable, documented, callable from the skill instructions, and stored beside the skill they support rather than in some shared unrelated location.
7. Validate the result.
   • Re-run the relevant sensei checks and any skill-specific tests.
   • Verify that reference links resolve and that the main SKILL.md is materially smaller and easier to trigger.
   • Summarize what changed in the skill, what moved into references/, and what deterministic helpers were added.

Deterministic work rule

If you notice yourself describing a mechanical series of steps that can be checked or reproduced, stop and turn it into a TypeScript script with tests in the optimized skill's ./scripts/ folder. Read references/deterministic-typescript.md before implementing it.

Deterministic workflow

scripts/resolve-optimization-plan.ts defines the canonical path resolution, the sparse-vs-reference section classification, and the expected output paths for references/, evals/, and scripts/. Use it before improvising the optimization plan by hand.

Reference map

• Read references/agentskills-checklist.md when checking spec compliance and frontmatter shape.
• Read references/agentevals-checklist.md when creating or revising evals/evals.json and benchmark artifacts.
• Read references/progressive-disclosure.md when deciding what stays in SKILL.md versus what moves into references/.
• Read references/deterministic-typescript.md when the optimization should produce executable TypeScript helpers.

Expected outputs

• An updated skill bundle that still triggers for the original use case.
• A leaner SKILL.md plus supplemental docs in references/.
• An evals/evals.json file that exercises the optimized behavior.
• TypeScript scripts and tests in the optimized skill's ./scripts/ folder for any deterministic workloads discovered during optimization.

Example requests

Input: "Use /sensei --gepa on skills/release-manager, keep the skill name, shrink the huge SKILL.md, move the long rollout examples into references, and add evals."

Output: An optimized skills/release-manager/ bundle with a compact SKILL.md, new references/ docs, and evals/evals.json.

Input: "Tighten .agents/skills/pdf-cleanup so it stops undertriggering, and script the markdown-to-json validation instead of repeating it manually."

Output: The canonical skill bundle is updated, /sensei --gepa is applied, a deterministic TypeScript validator is added under the optimized skill's ./scripts/ folder with tests, and eval coverage reflects the new behavior.