Skill Integrator

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

Pipeline:

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:

   deno run --allow-read scripts/analyze-project.ts --json

   Save output as project context.

4. Run scan-skills.ts to inventory all installed skills:

   deno run --allow-read scripts/scan-skills.ts --json

   Or for single skill mode:

   deno run --allow-read scripts/scan-skills.ts --skill <name> --json

5. Run generate-guidance.ts to produce the guidance section:

   deno run --allow-read scripts/generate-guidance.ts --project-context ctx.json --skills skills.json

   Or for single skill:

   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.

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.

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.

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.