/skill-distiller

name: skill-distiller
description: >-
  Fetches top-rated skills from skills.sh, analyzes them, and synthesizes one
  token-efficient skill combining the best elements. Use when the user asks to
  "distill skills for X", "find and combine skills for X", "synthesize skills",
  "merge skills", "make a skill for X from skills.sh", "update distilled skill",
  or mentions combining, distilling, or synthesizing multiple skills into one
  token-efficient skill.

Skill Distiller

Fetches top-rated skills from skills.sh for a task, analyzes them, and synthesizes one token-efficient skill combining the best elements.

Modes

Distill `<query>`

**1. Search** — Find qualifying skills:

python3 distillery/scripts/distiller.py search "<query1>" "<query2>" ...

Returns JSON array of qualifying skills (filtered to `installs >= 100`, top 10, deduplicated). If fewer than 3 qualify, threshold drops to 50. Save this output — it feeds into Step 2.

**1b. Triage before fetching** — High install count does not correlate with quality. Before fetching, scan the search results: read skill descriptions and source repo names. Skip sources that are clearly generic checklists, project-specific tools, or domains outside the target skill's scope. Only fetch sources that suggest genuinely new patterns or techniques.

**2. Fetch** — Stage sources and compute checksums:

python3 distillery/scripts/distiller.py fetch --skills '<JSON from Step 1>'

Handles grouping by source, running `npx skills add`, staging to `distillery/.skill-distiller/sources/`, removing symlinks, and computing SHA-1 checksums. Returns JSON array with `id`, `skillId`, `installs`, `sha1`, and `path` for each staged source.

**Fetch fallback:** If `distillery/scripts/distiller.py fetch` fails (subprocess issues with `npx skills add`), run `npx skills add <source_url> -s <skillId> -y --agent claude-code` directly from the project root. The skill will be installed to `.claude/skills/<skillId>/`. Read the SKILL.md from there, then clean up the directory after analysis.

**2b. Grok query** — Query recent X posts for practitioner insights:

python3 distillery/scripts/distiller.py grok-query "<topic>" --top-installs <N>

Pass `--top-installs` using the highest install count from Step 1 results (sets engagement threshold: >=10k→50 likes, >=1k→10 likes, <1k→3 likes). Optionally pass `--instructions` if user provided scope/exclusion rules. Returns JSON with `findings` (categorized as `breaking_change`, `emerging_pattern`, `pitfall`, `new_tooling`) and a `summary`. Use findings as supplementary context during analysis — not a formal source, but a "did we miss anything?" signal. If no findings, skip with no impact.

**3. Analyze** — Read each staged `SKILL.md`. Extract per skill:

• Core techniques (actionable patterns unique to this skill)
• Unique value (what others lack)
• Failed approaches / anti-patterns with reasons — these are high-value; failure paths save more time than success paths
• Filler ratio (verbose examples, generic advice, redundancy)
• "Claude already knows this" — flag content that explains things Claude inherently knows (what a PDF is, how HTTP works, what a database does). This is the highest-signal filler detector.

**3b. Resolve conflicts** — When sources contradict each other (e.g., opposing patterns, mutually exclusive approaches), do NOT silently pick one. For each conflict, prompt the user with:

• The conflicting positions and which source skills hold them
• A recommendation with brief rationale
• Let the user decide before proceeding to synthesis

**Clarification discipline** — Do not over-clarify. Ask only when critically needed:

• **Ask if**: sources fundamentally contradict on architecture (e.g., class-based vs functional), the user's scope is ambiguous enough to produce a wrong skill, or a decision irreversibly shapes the output
• **Don't ask if**: you can infer from context, the choice is low-impact and easily revised, you have a clear best default, or asking would just be seeking permission to proceed

**4. Synthesize** — Generate `SKILL.md` with YAML frontmatter. Use this exemplar as the structural reference:

---
name: simplifying-code
description: >-
  Simplifies, polishes, and declutters code without changing behavior. Use when
  asked to "simplify code", "clean up code", "polish code", "refactor",
  "declutter", "reduce complexity", "remove dead code", "remove AI slop",
  "improve readability", or "tighten up this file".
---

# Simplifying Code

## Principles

| Principle | Rule |
|-----------|------|
| **Preserve behavior** | Output must do exactly what the input did — no silent feature additions or removals |
| **Surgical changes** | Touch only what needs simplifying. Match existing style |

## Process

1. **Read first** — understand the full file and its dependents before changing anything
2. **Identify invariants** — what must stay the same? Public API, return types, side effects
3. **Apply in order** — structural changes first, cosmetic last
4. **Verify** — confirm no behavior change: tests pass, types check

## Smell → Fix

| Smell | Fix |
|-------|-----|
| Deep nesting (>2 levels) | Guard clauses with early returns |
| Long function (>30 lines) | Extract into named functions by responsibility |
| Dead code / unreachable branches | Delete entirely — no commented-out code |

## Constraints

- Only simplify what was requested — do not add features or expand scope
- If a simplification would make the code harder to understand, skip it
````

Notice: keyword-saturated description with synonyms, imperative voice throughout, tables for dense pattern→action mappings, measurable criteria (">2 levels", ">30 lines"), no filler. Match this density and structure.

Frontmatter: only `name` and `description`. Strip all inert metadata (triggers, role, scope, domain, output-format, author, version, license, related-skills) — Claude Code ignores these and they waste token