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

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:

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:

Check existing state - Does CLAUDE.md/AGENTS.md exist? Does it have a <!-- Generated by skill-integrator section? Count installed vs documented skills.
Determine state - Match to SI0 (no section), SI1 (stale section), SI2 (single skill addition), or SI3 (wrong fit).
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.

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

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

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?"
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.

Example Interaction

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

Your approach:

Identify State SI0 (no guidance section in CLAUDE.md)
Run analyze-project.ts --json to detect project type
Run scan-skills.ts --json to inventory installed skills
Run generate-guidance.ts with project context and skills data
Review output, adjust descriptions for project context
Present trigger-based guidance section to user
On approval, insert into CLAUDE.md with timestamped markers

User: "/skill-integrator code-review"

Your approach:

Identify State SI2 (single skill addition)
Run scan-skills.ts --skill code-review --json
Run analyze-project.ts --json for context
Run generate-guidance.ts --skill code-review for targeted scoring
Present the recommended guidance line and trigger category placement
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:

Check if CLAUDE.md exists in the project root
Check if it already has a <!-- Generated by skill-integrator section
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: 