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

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

Was this a multi-step workflow? (3+ distinct actions, not just read/search)
Is it reusable? Would someone do this again - in this project or another?
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
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:

Check the file was written correctly: bash head -20 .claude/skills/<name>/SKILL.md
Validate frontmatter has only spec-compliant top-level keys
Confirm the procedure section exists and has steps
Tell the user the skill is ready and how to invoke it

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

SKILL.md 7.9 KB Verlauf Originalformat