Make skills more usable, not more complex.
Your task: diagnose, refactor, optimize, and publish Agent Skills.
Six refactoring modes
| Mode | Trigger | What it does |
|---|---|---|
| Diagnosis | "Help me look at this skill" | Analyze problems, do not modify |
| Optimization | "Token consumption is too high" "too slow" | Reduce redundancy, improve efficiency |
| Trigger optimization | "Skill triggering is inaccurate" | Rewrite the description and trigger words |
| Boundary optimization | "The skill did things it should not do" | Narrow the boundary, clarify the boundary |
| Evaluation | "Help me evaluate the effectiveness of this skill" | Generate test cases → execute → measure → improve |
| Refactoring | "The skill is too complex" | Split/merge/simplify |
Diagnostic dimensions
- Trigger rate: Does the description cover enough triggering scenarios?
- Boundary clarity: Is the boundary declaration clear?
- Token efficiency: Is there redundant content?
- Routing completeness: Is downstream collaboration covered?
- Context efficiency: Is there content that can be loaded on demand instead of preloaded? For a SKILL.md over 150 lines, consider moving some content to references/ and read it only when needed. Context is a limited resource; every token consumes attention budget.
- Process clarity: Are the steps executable?
Optimization principles
- Trigger words must be specific: Not "help me," but "help me split this" or "help me look at this skill"
- Boundaries must be clear: What not to do is more important than what to do
- Tokens must be concise: Every word must have a reason to exist
- Processes must be executable: Steps must be specific, not abstract
Self-diagnosis
When the target is set to its own path, fully execute the six diagnostics, output a self-diagnosis report, and then directly modify itself.
Evaluation mode
To evaluate whether a skill is actually usable, the fastest way is to let it run through real scenarios.
First prepare the test cases. Not many are needed; 10 to 20 is enough. Each case should clearly state three things: what the user will say, what the skill should do, and what the skill should not do. Seventy percent common scenarios, twenty percent edge cases, ten percent abnormal inputs—this ratio is fine.
Then run them one by one. Look at a few things: whether it triggers or routes correctly, whether the output can be used directly, and whether there are omissions or filler.
After running it, calculate three numbers. Whether routing is accurate—the proportion of correct triggers. Whether the output can be used directly—the proportion that does not require follow-up questions or corrections. The average token consumption per run. The common patterns among low-scoring cases are where the problem lies. Make targeted changes to SKILL.md, run it again, until both metrics meet the standard: routing accuracy above ninety percent, output usability above eighty percent.
A few key points. Observe the skill's behavior in real scenarios, iterate based on observations, and do not presuppose what the agent needs. Let the agent run through it itself and see where it gets stuck, where it skips steps it should not skip, and where it gives vague advice—these are more useful than any preset direction for improvement.
Next-step suggestions (conditionally triggered)
After diagnosis is complete, determine based on the results whether to recommend a next step.Do not recommend every time, only say a sentence when the results clearly point to another skill.
| Result condition | Recommended wording |
|---|---|
| Diagnosis finds the skill has too many problems, and it is better to rebuild from scratch | "Fixing is not as good as rebuilding. Use /taxue-build to build a new one." |
| Need to create a brand-new skill (not optimize an existing one) | "What you want is to create new, not optimize. Use skill-creator。」 |
DO NOT
- Create a new skill from scratch →
skill-creator(taxue-skill does preliminary diagnosis and routing, not the full creation process) - Need a deep structural audit →
skill-auditor(taxue-skill does problem classification, auditor does deep execution)
taxue-skill v2.8