Skill Optimizer

Skill Optimizer

Audit the current thread and the locally visible skill set, then turn findings into a clear action queue that the user can review and choose from.

This skill is for governance and optimization, not for silently changing skills. Start with analysis, produce a report, and only edit files after the user chooses actions.

Default Scope

Unless the user explicitly provides extra logs or transcript files, use:

• the current conversation history
• the current workspace's local skill directories
• installed skill directories that are directly visible from the environment

Do not claim global usage statistics unless the user provided cross-thread logs or telemetry.

What To Look For

Audit for these issue types:

• missed_trigger A task in the current thread clearly matched an existing skill, but that skill was not used.
• weak_metadata name or description likely under-trigger because they miss common user phrasing or contexts.
• duplicate_skill The same skill, or near-identical copies, exist in multiple active places.
• overlap_skill Two or more skills cover nearly the same job and create ambiguity.
• stale_skill The skill description, instructions, bundled files, or agents/openai.yaml are out of sync.
• risky_skill The skill enables dangerous actions but lacks guardrails, warnings, or confirmation points.
• install_flow_issue The install, sync, backup, or directory workflow is confusing or inconsistent.
• unused_candidate Based on the current thread and local structure, a skill appears low-value or inactive. Phrase this carefully; it is not proof of never being used globally.

Working Rules

Follow this sequence.

Step 1: Inventory The Skills

Identify the skill roots that are relevant to the current workspace. Typical places include:

• ./.agents/skills
• ./.claude/skills
• project-local skills/ directories
• directly relevant global skill directories if they are part of the current environment

For each skill, capture at least:

• path
• skill name
• description
• whether agents/openai.yaml exists
• whether bundled scripts or references exist

Step 2: Read Current-Thread Evidence

Review the current conversation history and extract:

• the user's goals
• phrases the user used naturally
• where a skill was used
• where a skill should probably have been used but was not
• repeated confusion that suggests weak metadata or poor boundaries

Use exact evidence from the thread when possible, but keep quotations short.

Step 3: Diagnose

Compare the thread evidence against the local skill inventory.

Pay special attention to:

• user phrasing that should have triggered a skill but did not
• skills with duplicate names or nearly identical descriptions
• skills whose body promises more than the bundled files support
• skills with risky capabilities and no explicit safety language
• local backup or fork directories that may confuse maintenance

Step 4: Produce The Audit Report

Structure the report using the schema in report-schema.md.

The report must include:

• executive summary
• findings grouped by issue type
• an action queue with one item per proposed intervention

Keep findings evidence-based. If something is an inference rather than a direct fact, say so.

Step 5: Offer Only Four Actions

Every action item must expose exactly these user-facing actions:

• Fix
• Merge
• Delete
• Keep and Skip

Do not introduce extra action labels like archive or disable in the user-facing menu. If you internally think a "soft delete" is safer, explain that inside the recommendation, but keep the action menu limited to the four agreed options.

Step 6: Wait Before Editing

Do not modify any skill during the audit step.

Only after the user selects action items should you:

• rewrite metadata
• sync agents/openai.yaml
• merge overlapping skills
• delete duplicates or obsolete skills

If the user selects Delete, confirm the exact target before removing files when there is any ambiguity.

Recommendation Heuristics

Use these defaults unless the evidence strongly suggests otherwise:

• missed trigger or weak metadata -> recommend Fix
• duplicate or high-overlap skill copies -> recommend Merge
• clearly obsolete duplicates or user-rejected leftovers -> recommend Delete
• uncertain or disputed findings -> recommend Keep and Skip

For unused_candidate, be conservative. Prefer Keep and Skip or Fix over Delete unless the user explicitly wants aggressive cleanup.

Report Style

• Be detailed, but not vague.
• Put findings before summaries.
• Make every action item independently understandable.
• Separate facts from recommendations.
• Use absolute file paths when referencing files.

Output Contract

When running the audit, return:

1. A concise summary of the top themes
2. A detailed findings section grouped by category
3. An action queue using the schema in report-schema.md
4. A short prompt telling the user how to respond with their chosen actions

Example response pattern:

Action Queue
- I01: Recommend `Fix`
- I02: Recommend `Merge`
- I03: Recommend `Keep and Skip`

Reply with selections such as:
- `I01 -> Fix`
- `I02 -> Merge`
- `I03 -> Keep and Skip`

Boundaries

• Do not pretend the current thread represents all historical usage.
• Do not delete anything during analysis.
• Do not collapse separate findings into one vague item if the fixes differ.
• Do not overclaim certainty on "unused" skills.

Bundled Resources

• report-schema.md Read this when drafting the audit report and action queue.