|
|
@@ -0,0 +1,250 @@
|
|
|
+---
|
|
|
+name: auto-skill
|
|
|
+description: "Evaluate current session for skill-worthy workflows and create reusable skills. Triggers on: auto-skill, create skill from session, save workflow, capture this as a skill."
|
|
|
+license: MIT
|
|
|
+allowed-tools: "Read Glob Grep Bash Write Edit"
|
|
|
+metadata:
|
|
|
+ author: claude-mods
|
|
|
+ depends-on: "skill-creator"
|
|
|
+ related-skills: "skill-creator, introspect"
|
|
|
+---
|
|
|
+
|
|
|
+# Auto-Skill
|
|
|
+
|
|
|
+Evaluate the current session and create a reusable skill from complex workflows. Enforces the [Agent Skills specification](https://agentskills.io/specification) and quality gates.
|
|
|
+
|
|
|
+## When This Triggers
|
|
|
+
|
|
|
+- User runs `/auto-skill`
|
|
|
+- Stop hook suggests it after a complex session (8+ mutating ops across 4+ tool types)
|
|
|
+- User says "save this as a skill", "capture this workflow", etc.
|
|
|
+
|
|
|
+## Command Router
|
|
|
+
|
|
|
+Parse arguments after `auto-skill` (or `/auto-skill`):
|
|
|
+
|
|
|
+| User says | Action |
|
|
|
+|-----------|--------|
|
|
|
+| `auto-skill` (no args) | Run the full evaluation procedure below |
|
|
|
+| `auto-skill off` | Disable globally: `touch ~/.claude/auto-skill.disable` and confirm |
|
|
|
+| `auto-skill on` | Enable globally: `rm -f ~/.claude/auto-skill.disable` and confirm |
|
|
|
+| `auto-skill off --project` | Disable for this project: `mkdir -p .claude && touch .claude/auto-skill.disable` |
|
|
|
+| `auto-skill on --project` | Enable for this project: `rm -f .claude/auto-skill.disable` |
|
|
|
+| `auto-skill status` | Show current state (see Status section below) |
|
|
|
+
|
|
|
+### Status
|
|
|
+
|
|
|
+When the user runs `auto-skill status`, check and report:
|
|
|
+
|
|
|
+```bash
|
|
|
+# Global toggle
|
|
|
+[ -f "$HOME/.claude/auto-skill.disable" ] && echo "Global: OFF" || echo "Global: ON"
|
|
|
+
|
|
|
+# Project toggle
|
|
|
+[ -f ".claude/auto-skill.disable" ] && echo "Project: OFF" || echo "Project: ON"
|
|
|
+
|
|
|
+# Hook scripts installed?
|
|
|
+[ -x "$HOME/.claude/auto-skill/track-tools.sh" ] && echo "Hooks: installed" || echo "Hooks: not installed"
|
|
|
+
|
|
|
+# Active session tracking?
|
|
|
+ls /tmp/claude_autoskill_* 2>/dev/null | head -1 && echo "Tracking: active" || echo "Tracking: idle"
|
|
|
+```
|
|
|
+
|
|
|
+Report results in a brief table.
|
|
|
+
|
|
|
+## Procedure
|
|
|
+
|
|
|
+### Step 1: Evaluate the Session
|
|
|
+
|
|
|
+Review the conversation history in the current session. Ask yourself:
|
|
|
+
|
|
|
+1. **Was this a multi-step workflow?** (3+ distinct actions, not just read/search)
|
|
|
+2. **Is it reusable?** Would someone do this again - in this project or another?
|
|
|
+3. **Is it novel?** Does an existing skill already cover this? Check with:
|
|
|
+ ```bash
|
|
|
+ ls ~/.claude/skills/ 2>/dev/null; ls .claude/skills/ 2>/dev/null
|
|
|
+ ```
|
|
|
+4. **Is it teachable?** Can it be described as a clear procedure with steps?
|
|
|
+
|
|
|
+If ANY answer is no, tell the user: "This session doesn't look like a good skill candidate" and explain which criterion failed. **Stop here.**
|
|
|
+
|
|
|
+### Step 2: Duplicate Detection
|
|
|
+
|
|
|
+Before creating, check for overlapping skills:
|
|
|
+
|
|
|
+```bash
|
|
|
+# List existing skill names and descriptions
|
|
|
+for f in ~/.claude/skills/*/SKILL.md .claude/skills/*/SKILL.md 2>/dev/null; do
|
|
|
+ [ -f "$f" ] || continue
|
|
|
+ name=$(head -10 "$f" | grep '^name:' | sed 's/name: *//')
|
|
|
+ desc=$(head -10 "$f" | grep '^description:' | sed 's/description: *//' | tr -d '"')
|
|
|
+ echo "$name: $desc"
|
|
|
+done
|
|
|
+```
|
|
|
+
|
|
|
+**Block if:**
|
|
|
+- Exact name match exists
|
|
|
+- 60%+ word overlap in proposed name vs existing name
|
|
|
+- 50%+ word overlap in proposed description vs existing description
|
|
|
+
|
|
|
+If overlap detected, suggest extending the existing skill instead.
|
|
|
+
|
|
|
+### Step 3: Draft the Skill
|
|
|
+
|
|
|
+Propose a skill to the user with:
|
|
|
+
|
|
|
+| Field | Value |
|
|
|
+|-------|-------|
|
|
|
+| **Name** | kebab-case, descriptive, matches what it does |
|
|
|
+| **Description** | 1-2 sentences with trigger keywords |
|
|
|
+| **Procedure** | Numbered steps extracted from the session workflow |
|
|
|
+| **Tools needed** | Which tools the skill requires |
|
|
|
+
|
|
|
+Ask the user to confirm or adjust before creating.
|
|
|
+
|
|
|
+### Step 4: Quality Gates
|
|
|
+
|
|
|
+Before writing, validate:
|
|
|
+
|
|
|
+| Gate | Requirement | Why |
|
|
|
+|------|-------------|-----|
|
|
|
+| **Name format** | `^[a-z][a-z0-9-]*$`, 1-64 chars | Agent Skills spec |
|
|
|
+| **Description** | Non-empty, 1-1024 chars, includes trigger phrases | Spec + discovery |
|
|
|
+| **Procedure** | Must contain numbered steps, `## Procedure`/`## Steps`, or checkboxes | Ensures actionable content |
|
|
|
+| **Min content** | 200+ characters in body (after frontmatter) | Rejects trivial stubs |
|
|
|
+| **License** | `license: MIT` | claude-mods convention |
|
|
|
+| **Metadata** | `metadata.author: claude-mods` | claude-mods convention |
|
|
|
+| **No non-standard top-level keys** | Only `name`, `description`, `license`, `compatibility`, `allowed-tools`, `metadata` | Agent Skills spec |
|
|
|
+
|
|
|
+If any gate fails, explain which one and help the user fix it.
|
|
|
+
|
|
|
+### Step 5: Create the Skill
|
|
|
+
|
|
|
+Write the skill to the project's skill directory:
|
|
|
+
|
|
|
+```
|
|
|
+.claude/skills/<skill-name>/
|
|
|
+ SKILL.md
|
|
|
+ scripts/.gitkeep
|
|
|
+ references/.gitkeep
|
|
|
+ assets/.gitkeep
|
|
|
+```
|
|
|
+
|
|
|
+**SKILL.md frontmatter template** (Agent Skills spec compliant):
|
|
|
+
|
|
|
+```yaml
|
|
|
+---
|
|
|
+name: <kebab-case-name>
|
|
|
+description: "<what it does>. Triggers on: <keyword1>, <keyword2>, <keyword3>."
|
|
|
+license: MIT
|
|
|
+allowed-tools: "<space-delimited tool list>"
|
|
|
+metadata:
|
|
|
+ author: claude-mods
|
|
|
+---
|
|
|
+```
|
|
|
+
|
|
|
+**Body structure:**
|
|
|
+
|
|
|
+```markdown
|
|
|
+# <Skill Title>
|
|
|
+
|
|
|
+<1-2 sentence overview>
|
|
|
+
|
|
|
+## When to Use
|
|
|
+
|
|
|
+- <trigger condition 1>
|
|
|
+- <trigger condition 2>
|
|
|
+
|
|
|
+## Procedure
|
|
|
+
|
|
|
+1. <Step one>
|
|
|
+2. <Step two>
|
|
|
+3. <Step three>
|
|
|
+...
|
|
|
+
|
|
|
+## Notes
|
|
|
+
|
|
|
+<Edge cases, caveats, or tips>
|
|
|
+```
|
|
|
+
|
|
|
+### Step 6: Verify
|
|
|
+
|
|
|
+After creating, verify the skill:
|
|
|
+
|
|
|
+1. Check the file was written correctly:
|
|
|
+ ```bash
|
|
|
+ head -20 .claude/skills/<name>/SKILL.md
|
|
|
+ ```
|
|
|
+2. Validate frontmatter has only spec-compliant top-level keys
|
|
|
+3. Confirm the procedure section exists and has steps
|
|
|
+4. Tell the user the skill is ready and how to invoke it
|
|
|
+
|
|
|
+## Per-Project Disable
|
|
|
+
|
|
|
+```bash
|
|
|
+touch .claude/auto-skill.disable # Disable Stop hook suggestions
|
|
|
+rm .claude/auto-skill.disable # Re-enable
|
|
|
+```
|
|
|
+
|
|
|
+The skill itself can always be invoked manually regardless of this setting.
|
|
|
+
|
|
|
+## Hook Setup
|
|
|
+
|
|
|
+Auto-skill uses two hooks for automatic suggestions. These are installed globally:
|
|
|
+
|
|
|
+```
|
|
|
+~/.claude/auto-skill/
|
|
|
+ track-tools.sh # PostToolUse: counts tool calls per session
|
|
|
+ evaluate.sh # Stop: suggests skill creation if complex enough
|
|
|
+```
|
|
|
+
|
|
|
+Both hooks fail silently - they will never produce error output or block Claude.
|
|
|
+
|
|
|
+### Hook Configuration
|
|
|
+
|
|
|
+Add to `~/.claude/settings.json` (merge with existing hooks):
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "hooks": {
|
|
|
+ "PostToolUse": [{
|
|
|
+ "matcher": "*",
|
|
|
+ "hooks": [{
|
|
|
+ "type": "command",
|
|
|
+ "command": "bash \"$HOME/.claude/auto-skill/track-tools.sh\"",
|
|
|
+ "timeout": 2
|
|
|
+ }]
|
|
|
+ }],
|
|
|
+ "Stop": [{
|
|
|
+ "hooks": [{
|
|
|
+ "type": "command",
|
|
|
+ "command": "bash \"$HOME/.claude/auto-skill/evaluate.sh\"",
|
|
|
+ "timeout": 5
|
|
|
+ }]
|
|
|
+ }]
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+## Suggestion Gates
|
|
|
+
|
|
|
+The Stop hook only suggests skill creation when ALL of these pass:
|
|
|
+
|
|
|
+| Gate | Threshold | Rationale |
|
|
|
+|------|-----------|-----------|
|
|
|
+| **Mutating ops** | 8+ | High bar reduces noise from routine edits |
|
|
|
+| **Tool diversity** | 4+ distinct types | Write+Edit+Bash+Agent = workflow; Write*20 = repetitive |
|
|
|
+| **No skill loaded** | `Skill` tool absent | If following a skill, work isn't novel |
|
|
|
+| **Per-session** | Once per session | Never nags on resume/continue |
|
|
|
+| **Not disabled** | No `.disable` file | Global or per-project toggle |
|
|
|
+
|
|
|
+Read-only tools (Read, Glob, Grep, LS, Task*) are excluded from counts.
|
|
|
+
|
|
|
+## Design Decisions
|
|
|
+
|
|
|
+- **Stop hook, not in-loop**: Claude Code doesn't expose the agent loop. The Stop hook fires while context is still in memory, which is the best we can get.
|
|
|
+- **systemMessage output**: The Stop hook outputs JSON that Claude Code displays to the user. Non-blocking, dismissible.
|
|
|
+- **Diversity over volume**: Tool type count matters more than raw call count. A 20-file rename isn't a skill; a workflow using Write+Edit+Bash+Agent probably is.
|
|
|
+- **Per-session cooldown**: Uses a temp file keyed by session ID. No harsh time-based cooldown - each new session gets a fresh chance.
|
|
|
+- **500-line cap on tracking**: Prevents runaway sessions from filling /tmp.
|
|
|
+- **Silent failures**: Both hooks wrap everything in `2>/dev/null` and always `exit 0`.
|
0xDarkMatter