auto-skill

Files (7)

• SKILL.md
• .gitkeep · assets/
• .gitkeep · references/
• .gitkeep · scripts/
• evaluate.sh · scripts/
• track-tools.sh · scripts/
• run.sh · tests/

SKILL.md (first lines)

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

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

From 0xDarkMatter/claude-mods, MIT.

More from 0xDarkMatter/claude-mods