skill-distill

name	skill-distill
description	Audit skills and tools installed in the system, classify what to keep or remove, extract the essence, and simplify. The inward counterpart to repo-analyst. Use when asked to "clean up skills", "audit my system", "are any skills redundant", "distill skills", "simplify skills", "盤點技能", "整理 skills", "清理工具", or "/skill-distill".

/skill-distill: Skill & Tool Audit

You are a systems curator. Your job is to audit what's installed, classify each item honestly, present a clear report, and execute only user-approved actions.

Symmetric pair with repo-analyst:

repo-analyst:   external repo  → analyze → should we adopt?
skill-distill:  internal system → audit   → should we keep?

Modes

Mode	Trigger	Scope
Full system	/skill-distill (no args)	All skills in ~/.claude/skills/
Single tool	/skill-distill <path>	All sub-features within that tool/skill pack

Parse the invocation to determine the mode before starting Phase 1.

---

Phase 1: Inventory

Full System Mode

Enumerate every entry in ~/.claude/skills/:

• Use Glob tool with pattern ~/.claude/skills/*/SKILL.md to list all skills

For each entry, collect the following fields:

Name — directory name.

Purpose — Use Read tool to read each skill's SKILL.md frontmatter description field.

Origin — Use Bash ls -la ~/.claude/skills/ | grep "^l" to identify symlinks vs. self-built directories.

Complexity — Use Read tool to read each SKILL.md (line count from output). Use Glob with pattern ~/.claude/skills/<skill>/prompts/* to check for prompts/ subdirectory.

Dependencies — Use Grep tool to search across all SKILL.md files:

• Pattern ~/bin/ to find binary dependencies
• Pattern API|api_key|ANTHROPIC|GEMINI|OPENAI to find API dependencies

Build and present the full inventory table before proceeding:

## Inventory: ~/.claude/skills/

| # | Skill | Origin | Lines | Has prompts/ | Dependencies | Overlap |
|---|-------|--------|-------|-------------|-------------|---------|
| 1 | qa | self-built | 248 | no | ~/bin/browse | unique |
| 2 | repo-analyst | self-built | 48 | yes (3) | none | pair: skill-distill |
...

Note: This audit covers ~/.claude/skills/ only. Skills from other sources (e.g., superpowers:* skills) are outside the managed scope. Mention their existence in the report if relevant to overlap detection.

Single Tool Mode

Read the tool's directory structure and enumerate all sub-features:

• Use Glob tool with pattern <target-path>/**/*.md to find all markdown files
• Use Glob tool with pattern <target-path>/**/SKILL.md to count sub-skills

For bundled skill packs (multiple SKILL.md files or a skills/ subdirectory inside):

• Use Read tool to read the frontmatter of each discovered SKILL.md

List each sub-skill separately. Read its description from the file header. Note if the parent pack has telemetry, config systems, or heavy runtime dependencies.

---

Phase 2: Classify

Assign exactly one tag per item using this priority order. Never skip steps — start at priority 1 and work down.

Priority	Question	Tag	Meaning
1	Does another skill or system feature already do this?	[REDUNDANT]	Has replacement — name it
2	Is the process simple enough to execute directly without a skill?	[INTERNALIZE]	No skill needed — record to memory
3	Does it contain unique, reusable workflow worth extracting?	[DISTILL]	Extract as a standalone skill
4	Is it actively useful as-is?	[KEEP]	Leave alone
5	None of the above	[INERT]	Installed but no clear value

Overlap Detection

Compare descriptions across the full inventory. When two or more skills cover the same domain or offer similar actions, flag them as a group:

### Overlap Groups
- Group A: skill-x, skill-y — both do Z. Recommend keeping skill-x because [reason].

Per-item Classification Output

For each item, write:

• The tag
• One-sentence reason
• If [REDUNDANT]: name the replacement skill
• If [DISTILL]: describe what the new standalone skill would contain
• If [INTERNALIZE]: describe what to record in memory

---

Phase 3: Report + Action Menu

Present the Report

## Audit Report: <target>

**Summary:** N scanned — K keep, R redundant, D distill, I internalize, X inert

| # | Skill | Tag | Reason | Suggested Action |
|---|-------|-----|--------|------------------|
| 1 | ... | [REDUNDANT] | replaced by X | Remove |
| 2 | ... | [DISTILL] | unique QA workflow | Extract as /new-name |
| 3 | ... | [KEEP] | working well | No action |
| 4 | ... | [INERT] | unused, no clear value | Remove |
...

### Overlap Groups
(list if any detected)

### Dependency Map
- ~/bin/browse: used by qa, design-review
- Gemini API: used by meetingscribe

Action Menu

After the report, ask:

Which items to execute? Enter numbers (e.g., 1,2,5) or "all":
(KEEP items are excluded — they require no action)

Wait for the user's response before executing anything.

Execute Selected Items

Execute one item at a time. Confirm before each removal. Do not batch.

---

[REDUNDANT] — Remove with backup:

1. Use Read tool to read the full skill content (~/.claude/skills/<skill>/SKILL.md)
2. Append the complete content to the decision note (full text, not summary)
3. State: "Removing — replaced by . Confirm? (y/n)"
4. On confirm:

   # If symlink: unlink only, never delete target
   if [ -L ~/.claude/skills/<skill> ]; then
     unlink ~/.claude/skills/<skill>
   else
     mv ~/.claude/skills/<skill> ~/.Trash/
   fi
   

---

[INTERNALIZE] — Record to memory, then remove:

1. Use Read tool to read the full skill content (~/.claude/skills/<skill>/SKILL.md)
2. Write the process/knowledge to a memory file:
   • Cross-project pattern (applicable everywhere) → write to ~/.claude/instincts/
   • Project-specific process (only relevant to one project) → write to the current project's memory directory Write a concise, actionable memory entry. Not a copy of the skill — extract the key steps.
3. Append the complete original content to the decision note (backup)
4. State: "Removed — process saved to memory at <memory-path>. Confirm removal? (y/n)"
5. On confirm:

   mv ~/.claude/skills/<skill> ~/.Trash/
   

---

[DISTILL] — Extract, then remove:

1. Use Read tool to read the full skill content. Use Glob to list all files in the skill directory.
2. Create a new standalone skill in ~/.claude/skills/<new-name>/SKILL.md:
   • Consult pipeline-skill-pattern if the new skill needs stages/phases
   • Strip tool-specific dependencies (telemetry, runtime config systems, etc.)
   • Keep only the core workflow and reusable knowledge
   • Write proper YAML frontmatter with name and description
3. Use Read tool to verify the new skill file exists and has content.
4. Append the complete original content to the decision note (backup)
5. State: "Created /new-name. Removing original . Confirm? (y/n)"
6. On confirm:

   mv ~/.claude/skills/<skill> ~/.Trash/
   

---

[INERT] — Remove with backup:

1. Use Read tool to read the full skill content. If no SKILL.md, use Glob to list directory contents.
2. Append the complete content to the decision note (backup)
3. State: "Removing — unused, no clear value. Confirm? (y/n)"
4. On confirm:

   if [ -L ~/.claude/skills/<skill> ]; then
     unlink ~/.claude/skills/<skill>
   else
     mv ~/.claude/skills/<skill> ~/.Trash/
   fi
   

---

Decision Note

After all executions are complete (or at end of session if no removals), write a decision note for future reference.

Where to write: Ask the user where they keep decision logs (e.g., an Obsidian vault, a docs/ directory, or any preferred location). If the user has a notes directory configured in their CLAUDE.md, use that.

Filename pattern:

skill-distill <target> audit YYYY-MM-DD.md

Note structure:

---
type: permanent
tags: [skill-audit, decision-log]
related: [skill-distill]
date: YYYY-MM-DD
---

# skill-distill Audit Report: <target>

## Summary

- Scanned: N
- KEEP: K | REDUNDANT: R | DISTILL: D | INTERNALIZE: I | INERT: X
- Actions taken: [list actions taken]

## Full Classification Table

[paste full classification table here]

## Removed Skill Backups

### <skill-name>

**Reason:** [classification reason]

**Full content:**

```
[full original skill content]
```

---

[repeat for each removed skill]

---

Safety Rules

1. Always confirm before removing — never auto-delete any skill
2. Backup before remove — full original content in decision note, not summaries
3. [DISTILL]: create BEFORE delete — verify new file exists and has content before deleting source
4. Symlinks: unlink only — unlink <path>, never delete the symlink target directory
5. Prefer trash over delete — use mv <path> ~/.Trash/ instead of rm -rf for recoverability
6. One item at a time — execute sequentially, confirm each before proceeding to next

---

Important Rules

1. Read every SKILL.md before classifying — never classify by name alone
2. For overlap detection: compare actual functionality, not just descriptions
3. Classification must follow priority order 1–5 — no skipping ahead
4. When extracting ([DISTILL]), strip framework-specific dependencies; keep only the workflow
5. The decision note is the safety net — make it complete with full original content
6. If unsure about a classification, ask the user before committing
7. Never remove a skill that other skills depend on without addressing the dependency first
8. In full system mode, include this skill (skill-distill) in the inventory and classify it normally using the same priority order

---

Completion Status

Report using: DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT