| name | self-skill |
| description | Meta-skill for detecting when a solved problem is worth packaging as a reusable skill, then scaffolding it. Runs automatically after completing any non-trivial task. Also use when explicitly asked to create, draft, or propose a new skill from something just built. |
| category | meta |
| maturity | stable |
| tags | ["skill-scaffolding","self-tooling","heuristics","draft-skill","automation"] |
Self-Skill — Autonomous Skill Creation
When This Runs
Automatically — after every non-trivial task, run the 5-question filter mentally:
- Will this come up again?
- Did I have to look something up or think hard?
- Did I write more than 20 lines of non-trivial code?
- Does it involve a specific tool/API with non-obvious usage?
- Would the user benefit from knowing how to trigger this?
2+ yes answers → create or propose a skill.
See references/heuristics.md for the full decision framework.
Improve an Existing Skill (patch-on-friction)
Creating skills is only half the loop — maintaining them matters just as much. Right
after you used a skill this turn, run a quick friction check:
- Missing steps — did you have to do something the skill didn't mention?
- Outdated / wrong — a stale command, wrong path, or wrong flag?
- Boilerplate — did you hand-write something the skill could have provided?
- Unclear — did you misread an instruction that should be clearer?
2+ yes → patch it now. Edit that skill's SKILL.md with the smallest diff that fixes
it, add/refresh a patched: YYYY-MM-DD line in the frontmatter, and keep it to one skill per
turn (don't go on a refactor spree mid-task). Don't wait to be asked — an unmaintained skill
is a liability.
The self-edit gate (a PostToolUse hook) automatically audits every SKILL.md you edit —
frontmatter, ≤15 KB size, external-path leaks, and secrets — and warns you if a patch breaks
something. So patch freely; the gate is your safety net.
Scaffold a New Skill
bash ${CLAUDE_SKILLS_DIR:-$HOME/.claude-agent/.claude/skills}/self-skill/scripts/draft-skill.sh <name> \
--desc "what it does in plain language" \
--resources "scripts,references"
This creates the full directory structure and pre-fills SKILL.md.
Full Skill Creation Checklist
When creating a skill (auto or on request):
[ ] 1. Run draft-skill.sh to scaffold the structure
[ ] 2. Write SKILL.md — description, triggers, quick reference
[ ] 3. Write scripts/ — working, tested, standalone
[ ] 4. Write references/ — detailed docs for complex topics
[ ] 5. Test all scripts before documenting them
[ ] 6. Write <skill-name>-guide.md in workspace (plain language, user-facing)
[ ] 7. Send guide as Telegram file attachment
[ ] 8. Paste raw guide markdown in chat — ONE continuous code block (split max 2 if too long)
[ ] 9. Commit: git add -A && git commit -m "feat: add <name> skill"
Auto-Create vs Propose
Auto-create (just do it, mention at end of task):
- Already wrote non-trivial scripts during the task
- Obvious extension of what was just built
- Scaffolding takes < 2 minutes
Propose first ("I should make a skill for this — want me to?"):
- Uncertain if pattern is stable
- Would require significant extra work
- Task was exploratory
Trigger Phrases
These will activate this skill:
- "Make a skill for this"
- "Turn this into a skill"
- "Save this as a skill"
- "We should have a skill for that"
- (automatically after any non-trivial task)
