0xDarkMatter/auto-skill

Auto-Skill

Evaluate the current session and create a reusable skill from complex workflows. Enforces the Agent Skills 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) | | auto-skill pending | Show all entries in ~/.claude/auto-skill/pending.log (past suggestions the user may have missed) | | auto-skill clear | Truncate ~/.claude/auto-skill/pending.log after confirming with user |

Status

When the user runs auto-skill status, check and report:

# 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:

   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:

# 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):

---
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:

# <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:

   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

Pending Log

Because systemMessage output from the Stop hook is delivered to Claude (not directly to the user), suggestions often die silently when the user's next prompt doesn't invite them to be mentioned. To solve this, the hook also appends a line to ~/.claude/auto-skill/pending.log each time it fires:

2026-04-24T19:28:03+10:00|9dc8576c|/x/forge/axiom|12|5|28|Write(4) Edit(3) Bash(3)

Fields (pipe-delimited):

| # | Field | Example | |---|-------|---------| | 1 | ISO8601 timestamp | 2026-04-24T19:28:03+10:00 | | 2 | Short session ID | 9dc8576c | | 3 | CWD when suggestion fired | /x/forge/axiom | | 4 | Mutating op count | 12 | | 5 | Unique tool type count | 5 | | 6 | Total tool calls | 28 | | 7 | Top-6 tool histogram | Write(4) Edit(3) Bash(3) |

/sync reads this log at session start and surfaces any entries from the last 72 hours under a "Skill Suggestions" section — the one place the user will reliably see them.

Viewing and clearing

• auto-skill pending — cat ~/.claude/auto-skill/pending.log (or show "no pending suggestions" if absent/empty)
• auto-skill clear — truncate after confirming with the user

Per-Project Disable

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):

{
  "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 non-harness skill loaded | Skill tool absent OR only harness skills | If following a domain skill, work isn't novel. Harness skills (sync, save, introspect, auto-skill, setperms, tool-discovery) are whitelisted — they're bootstrap/meta, not recipes. | | 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.