skill-integrator skill

---
name: skill-integrator
description: Integrate installed skill usage guidance into project CLAUDE.md/AGENTS.md based on project context. Use when skills are installed but agents don't know when to use them, when setting up a new project with skills, or when updating guidance after adding skills.
license: MIT
metadata:
  author: jwynia
  version: "1.0"
  domain: infrastructure
  type: utility
  mode: generative
---

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

### The Feature Echo
**Pattern:** Duplicating SKILL.md descriptions verbatim in the guidance.
**Problem:** Descriptions answer "what does this do?" instead of "when should I use this?" Agents need trigger context, not feature lists.
**Fix:** Transform descriptions into trigger-based guidance. "Use when [situation]" not "This skill [capability]."
**Detection:** Guidance text matches SKILL.md description word-for-word.

### The Static Guide
**Pattern:** Generating guidance once and never updating after adding/removing skills.
**Problem:** Guidance becomes stale. New skills go unused. Removed skills cause confusion.
**Fix:** Re-run skill-integrator after any skill installation. Use the timestamp comment to track freshness.
**Detection:** Timestamp in `<!-- Generated by skill-integrator` comment is more than 30 days old while skills were recently changed.

## Example Interaction

**User:** "I just installed a bunch of skills but my agent doesn't seem to know about them."

**Your approach:**
1. Identify State SI0 (no guidance section in CLAUDE.md)
2. Run `analyze-project.ts --json` to detect project type
3. Run `scan-skills.ts --json` to inventory installed skills
4. Run `generate-guidance.ts` with project context and skills data
5. Review output, adjust descriptions for project context
6. Present trigger-based guidance section to user
7. On approval, insert into CLAUDE.md with timestamped markers

**User:** "/skill-integrator code-review"

**Your approach:**
1. Identify State SI2 (single skill addition)
2. Run `scan-skills.ts --skill code-review --json`
3. Run `analyze-project.ts --json` for context
4. Run `generate-guidance.ts --skill code-review` for targeted scoring
5. Present the recommended guidance line and trigger category placement
6. On approval, insert into the existing guidance section

## What You Do NOT Do

- You do not rewrite SKILL.md files or modify skills themselves
- You do not install or uninstall skills
- You do not modify CLAUDE.md without user approval
- You do not include skills below the relevance threshold without explicit request
- You do not generate guidance for skills that don't have SKILL.md files
- You diagnose and generate; the user decides what goes into their config

## Integration Graph

### Inbound (From Other Skills)
| Source Skill | Source State | Leads to State |
|--------------|--------------|----------------|
| skill-builder | After creating a new skill | SI2: Single Skill Addition |
| find-skills | After installing a skill | SI2: Single Skill Addition |

### Outbound (To Other Skills)
| This State | Leads to Skill | Target State |
|------------|----------------|--------------|
| SI3: Wrong Fit | skill-builder | Quality issues found during analysis |

### Complementary Skills
| Skill | Relationship |
|-------|--------------|
| context-network | Guidance section lives in CLAUDE.md which context-network also manages |
| agent-bootstrap | New project setup benefits from immediate skill integration |
| skill-builder | After building a skill, integrate it into project guidance |
| find-skills | After discovering and installing skills, surface them via guidance |

## Reasoning Requirements

### Standard Reasoning
- Running scripts and interpreting output
- Matching skills to trigger categories
- Basic state identification (SI0-SI3)

### Extended Reasoning (ultrathink)
Use extended thinking for:
- Customizing trigger descriptions to project-specific contexts - [Why: requires understanding both skill capability and project needs]
- Evaluating threshold adjustments when many skills are borderline - [Why: trade-off analysis between coverage and noise]
- Resolving SI3 wrong-fit situations - [Why: requires reasoning about why current categorizations fail]

**Trigger phrases:** "customize guidance", "refine triggers", "adjust threshold"

## Execution Strategy

### Sequential (Default)
- analyze-project.ts must complete before generate-guidance.ts
- scan-skills.ts must complete before generate-guidance.ts
- State identification before running pipeline

### Parallelizable
- analyze-project.ts and scan-skills.ts can run concurrently
- Multiple single-skill scans can run concurrently

### Subagent Candidates
| Task | Agent Type | When to Spawn |
|------|------------|---------------|
| Project analysis | Bash | Running analyze-project.ts |
| Skill scanning | Bash | Running scan-skills.ts (especially for 100+ skills) |

## Context Management

### Approximate Token Footprint
- **Skill base:** ~3k tokens
- **With script outputs inline:** ~6k tokens
- **With full skill inventory (100+ skills):** ~15k tokens (write to file, don't inline)

### Context Optimization
- Always write script JSON output to temporary files rather than inlining
- Reference skills by name rather than embedding full metadata
- Use `--json` output mode for scripts, only inline the final guidance markdown

### When Context Gets Tight
- Prioritize: Current state diagnosis and generated guidance output
- Defer: Full skill inventory details, scoring breakdowns
- Drop: Raw project file type counts, individual skill metadata

## Output Persistence

### Output Discovery

**Before doing any other work:**

1. Check if CLAUDE.md exists in the project root
2. Check if it already has a `<!-- Generated by skill-integrator` section
3. If CLAUDE.md doesn't exist, ask the user where to place the guidance

### Primary Output

For this skill, persist:
- **Guidance section** - The trigger-based markdown inserted into CLAUDE.md/AGENTS.md
- **Timestamp marker** - HTML comment marking the section for surgical updates

### Conversation vs. File

| Goes to File | Stays in Conversation |
|--------------|----------------------|
| Trigger-based guidance section | Scoring breakdown and reasoning |
| Timestamp markers | State diagnosis discussion |
| CLAUDE.md updates | Threshold adjustment discussion |

### File Naming

Pattern: Inserted section within existing CLAUDE.md or AGENTS.md
Markers: `<!-- Generated by skill-integrator | Last updated: YYYY-MM-DD -->`