skill-integrator

What this skill does

# Skill Integrator: Surface Skills Where They're Needed

You bridge the gap between installed skills and agent awareness. Your role is to analyze project context, score installed skills for relevance, and generate actionable trigger-based guidance that gets inserted into CLAUDE.md or AGENTS.md.

## Core Principle

**Skills only help when agents know to reach for them.** A hundred installed skills are useless if the agent doesn't know when each one applies. This skill transforms a silent inventory into active, contextual guidance.

## Quick Reference

| Situation | Command |
|-----------|---------|
| First-time setup | `/skill-integrator` → generates full guidance section |
| After installing a skill | `/skill-integrator <skill-name>` → adds single skill |
| Guidance feels stale | `/skill-integrator` → regenerates with current inventory |
| Check what scripts do | `--help` flag on any script |

**Pipeline:**
```bash
deno run --allow-read scripts/analyze-project.ts --json > /tmp/ctx.json
deno run --allow-read scripts/scan-skills.ts --json > /tmp/skills.json
deno run --allow-read scripts/generate-guidance.ts --project-context /tmp/ctx.json --skills /tmp/skills.json
```

## The States

### State SI0: No Integration
**Symptoms:** Project has skills installed in `.claude/skills/` but CLAUDE.md/AGENTS.md has no skill guidance section. Agents work without awareness of available tools.
**Key Questions:** How many skills are installed? What project type is this? Does CLAUDE.md even exist?
**Interventions:** Run full analysis pipeline: analyze-project → scan-skills → generate-guidance. Generate comprehensive trigger-based section. Present to user for insertion.

### State SI1: Stale Integration
**Symptoms:** A skill guidance section exists (look for `<!-- Generated by skill-integrator` comment) but skills have been added or removed since it was last generated. Installed skill count doesn't match documented count.
**Key Questions:** Which skills were added since last generation? Which were removed? Has the project type changed?
**Interventions:** Run pipeline again with current state. Diff against existing section. Present changes for approval. Surgically update the marked section.

### State SI2: Single Skill Addition
**Symptoms:** User just installed one skill and wants it integrated into existing guidance. Or user invokes `/skill-integrator <skill-name>`.
**Key Questions:** What does this skill do? Which trigger category does it belong in? Where in the existing guidance should it go?
**Interventions:** Run single-skill mode: scan the new skill, score against project context, generate a single guidance line with trigger category placement. Insert into existing section at the right location.

### State SI3: Wrong Fit
**Symptoms:** Guidance references irrelevant skills, wrong trigger categories, or generic descriptions that don't help agents decide when to use a skill. Skills are listed but not effectively surfaced.
**Key Questions:** Are trigger categories appropriate for this project type? Are descriptions actionable or just echoing SKILL.md? Does the threshold need adjusting?
**Interventions:** Re-run with adjusted threshold. Review trigger category assignments. Customize descriptions to project-specific contexts rather than generic skill descriptions.

## Diagnostic Process

When invoked:

1. **Check existing state** - Does CLAUDE.md/AGENTS.md exist? Does it have a `<!-- Generated by skill-integrator` section? Count installed vs documented skills.

2. **Determine state** - Match to SI0 (no section), SI1 (stale section), SI2 (single skill addition), or SI3 (wrong fit).

3. **Run analyze-project.ts** to detect project type, domains, and tech stack:
   ```bash
   deno run --allow-read scripts/analyze-project.ts --json
   ```
   Save output as project context.

4. **Run scan-skills.ts** to inventory all installed skills:
   ```bash
   deno run --allow-read scripts/scan-skills.ts --json
   ```
   Or for single skill mode:
   ```bash
   deno run --allow-read scripts/scan-skills.ts --skill <name> --json
   ```

5. **Run generate-guidance.ts** to produce the guidance section:
   ```bash
   deno run --allow-read scripts/generate-guidance.ts --project-context ctx.json --skills skills.json
   ```
   Or for single skill:
   ```bash
   deno run --allow-read scripts/generate-guidance.ts --skill <name> --project-context ctx.json --skills skills.json
   ```

6. **Review and refine** - The scripts produce structured data; use your judgment to:
   - Adjust trigger descriptions to be project-specific
   - Verify trigger category assignments make sense
   - Ensure descriptions answer "when should I use this?" not "what does this do?"

7. **Present to user** - Show the generated guidance section. Apply on approval by inserting/replacing the marked section in CLAUDE.md or AGENTS.md.

## Two Modes

### All-Skills Mode (default)
Invoked with `/skill-integrator` or when diagnosing SI0/SI1.
- Analyzes all installed skills against project context
- Generates comprehensive trigger-based section
- Groups skills by trigger category (When Planning, When Writing Code, etc.)
- Only includes skills scoring >= threshold (default 0.3)

### Single-Skill Mode
Invoked with `/skill-integrator <skill-name>` or when diagnosing SI2.
- Analyzes one specific skill against project context
- Generates a single guidance line with placement recommendation
- Shows scoring breakdown for transparency

## Available Tools

### analyze-project.ts
Detects project type from indicator files, file extensions, and installed skills.
```bash
deno run --allow-read scripts/analyze-project.ts
deno run --allow-read scripts/analyze-project.ts --path /some/project
deno run --allow-read scripts/analyze-project.ts --json
```
**Output:** ProjectContext JSON with type, domains, techStack, fileTypes, hasContextNetwork, skillsInstalled.

### scan-skills.ts
Parses all installed skill SKILL.md files and extracts metadata.
```bash
deno run --allow-read scripts/scan-skills.ts
deno run --allow-read scripts/scan-skills.ts --skill code-review
deno run --allow-read scripts/scan-skills.ts --json
```
**Output:** Array of SkillInfo objects with name, description, domain, type, mode, keywords, triggerPhrases.

### generate-guidance.ts
Scores skills for relevance and generates formatted guidance.
```bash
deno run --allow-read scripts/generate-guidance.ts --project-context ctx.json --skills skills.json
deno run --allow-read scripts/generate-guidance.ts --format trigger --threshold 0.3 --project-context ctx.json --skills skills.json
deno run --allow-read scripts/generate-guidance.ts --skill code-review --project-context ctx.json --skills skills.json
deno run --allow-read scripts/generate-guidance.ts --format table --json --project-context ctx.json --skills skills.json
```
**Formats:** `trigger` (default, grouped by when-to-use), `domain` (grouped by skill domain), `table` (relevance score table).

## Key Questions

### For Initial Integration (SI0)
- How many skills are installed?
- What is the primary project type?
- Does CLAUDE.md already exist, or does it need to be created?
- Are there project-specific trigger contexts beyond the defaults?

### For Updates (SI1, SI2)
- Which skills changed since last integration?
- Has the project type or tech stack changed?
- Are existing trigger descriptions still accurate?

### For Quality (SI3)
- Are agents actually using the guided skills?
- Are trigger descriptions actionable or just descriptive?
- Is the threshold too low (too many irrelevant skills) or too high (missing useful ones)?

## Anti-Patterns

### The Skill Dump
**Pattern:** Listing all installed skills regardless of relevance.
**Problem:** Information overload. Agents can't distinguish useful from irrelevant. Guidance becomes noise.
**Fix:** Use threshold-based scoring. Only include skills with relevance >= 0.3. Quality over quantity.
**Detection:** More than 30 skills in the guidance section, or skills with no domain overlap appearing.