English | 中文
When we write skills as workflows, common problems emerge:
- Multi-step tasks should execute serially, but agents self-authorize parallelization or step-skipping.
- Downstream steps depend on upstream outputs, but upstream steps produce nothing — agents hallucinate results and proceed anyway.
- Some steps must write intermediate results to files, but agents skip the write and claim completion in chat.
skill-refiner addresses these issues by adopting a prompt-enforced FSM (Finite State Machine) design philosophy. It constrains agent execution into controlled state transitions using three primitives — GATE / BLOCKING / CHECKPOINT — preventing hallucination-driven progress, step-skipping, and mid-task state loss.
This skill has a side benefit: cost savings.
You can first use a capable model (e.g., Claude Opus) to call skill-refiner and rewrite your existing skills, then switch to a weaker model (e.g., Claude Haiku) to execute the rewritten skills. Because the rewritten prompts have stronger constraints, even a weaker model may achieve comparable output quality through better prompt alignment.
The tradeoff: the rewritten SKILL.md becomes longer, consuming more tokens from the weaker model. You can judge whether this optimization is worthwhile through simple experimentation and calculation.
If you find it useful, a Star ⭐ is always appreciated.
npx skills add Hytidel/skill-refinerClone the repo or download the ZIP, then move the ./skills/skill-refiner directory into your agent tool's skills folder:
| Tool | Skills directory |
|---|---|
| Claude Code (global) | ~/.claude/skills/ |
| Claude Code (project) | .claude/skills/ |
| Other tools | See your tool's documentation |
After installation, just tell your agent:
refine skill: <skill name or path>
Or:
refine skill: <skill name or path>
You can also invoke the skill explicitly:
/skill-refiner refine the `skill-creator` skill
The agent will automatically back up the original skill, analyze the pipeline structure, rewrite SKILL.md, and wait for your confirmation before finishing.
Contributions are welcome!
- Fork the repo
- Create a branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add AmazingFeature') - Push the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
This project is licensed under the MIT License.
Inspired by the ppt-master skill and its exploration of the prompt-enforced FSM workflow design pattern.