Fuse skills

Fuse Skills

Create one fused skill that keeps the useful behavior from all source skills, removes overlap, and stays cheap to load.

Use this skill for

• merging multiple skill folders into one new skill
• combining local repo skills with explicitly named skills.sh skills
• removing duplicated rules across overlapping skills
• creating a stronger portable skill while preserving local value when local skills are part of the input

Not for

• runtime composition of several skills without creating a new fused skill
• choosing which existing skills to load for a task when no merged output is wanted
• revising only one skill in place unless the goal is to fold other skills into it
• broad discovery of related remote skills the user did not ask for

Required inputs

The user must provide all source skills to combine.

Allowed source-specification levels:

• fully specified source: exact local skill path/name, exact inline content, or exact remote owner/repo plus skill name(s)
• package-specified remote source: exact remote owner/repo, but the user has not yet pinned the skill name(s) inside that package
• bounded local-family source: a named local skill family such as backend-*, ui-*, or "the development-contract skills" where the user is explicitly asking to fuse local skills from this repo and the family can be resolved by inspecting local folders only

Do not accept open-ended discovery beyond those bounds. If the user has not identified either a specific local skill/family, a specific remote skill, or a specific package to inspect, stop and ask for that missing scope.

For each source, identify whether it is:

• a local repo skill
• a bounded local repo skill family that must be resolved to explicit local skill names before fusion
• an explicit skills.sh skill from a named owner/repo package
• raw skill content provided inline

Do not expand scope beyond the provided sources or explicitly named packages.

For remote sources, capture both:

• the package identity in owner/repo form
• the specific skill name or names to fuse from that package

If the user provides a GitHub URL instead of owner/repo, normalize it to owner/repo before continuing.

If the user provided only a package-specified remote source, you may inspect that package only to resolve the intended skill name(s). Do not broaden into general package discovery or substitute a different package.

Core workflow

1. Inspect the local repo first for relevant conventions, nearby skills, and any existing skill-generation guidance.

2. Classify each source as local repo skill, remote skills.sh skill, or inline content. If the user named a bounded local family, inspect only matching local folders, resolve the exact skill names, and report that resolution before continuing. Read local sources immediately. For remote sources, proceed to step 3.

3. Acquire remote sources through this fallback chain. Stop at the first tier that succeeds for each source.

   Tier 1 — local copies. Check skills-lock.json and npx skills list --json for already-installed copies of the requested skills. If found, read them directly. This is the preferred path because it avoids repo mutations.

   Tier 2 — CLI fetch. If not installed locally:

   • Verify the CLI is available with npx skills --help. If the CLI is missing or Node/npm is unavailable, skip to Tier 3.
   • Treat remote sources as package-scoped skills in a named owner/repo. If the user provided a GitHub URL, normalize it to owner/repo first.
   • If the user specified only the package, use npx skills add <owner/repo> -l only to list that package's skills so you can resolve the exact skill name(s). Once resolved, continue with explicit names.
   • Use npx skills add <owner/repo> --skill <skill-names> to fetch only the named skills.
   • Prefer the least invasive acquisition path available. Use project-local installation only when read-only local inspection is unavailable. Do not use --global unless the user explicitly asked for it.
   • Do not use skills find or broad package discovery unless the user asked for discovery rather than fusion.
   • Treat fetches as repo mutations. Before any install, note whether the worktree is already dirty. After fetching, isolate or clearly report any files added or changed as acquisition artifacts, and do not fold them into the final deliverable unless the user asked for that.

   Tier 3 — user-provided content. If both Tier 1 and Tier 2 fail (no local copy, CLI unavailable, network blocked, policy constraints), ask the user to provide the skill content inline or as file paths. Do not proceed with incomplete sources.

4. Load every source skill (local, fetched, and inline) and record:

   • its trigger scope
   • core workflow steps
   • high-value decision rules
   • references, scripts, or assets that materially matter
   • obvious repetition, drift, or weak sections
   • remote baggage that should probably not ship: giant catalogs, data dumps, installer-specific metadata, broad stack assumptions, or helper scripts whose value does not survive the fusion

5. Check fusion compatibility before proceeding.

   • Compare the trigger scopes across sources. If one skill says "use for X" and another says "never use for X," flag the conflict.
   • Compare capability requirements. If one source needs code execution and another needs web search with no overlap in workflow, note the mismatch.
   • Compare abstraction levels. A meta-skill (how to design skills) and a domain skill (how to deploy containers) rarely fuse well.
   • If sources are incompatible, recommend against fusion or propose partial fusion: a fused core for the compatible subset, plus a companion skill for the rest. Do not proceed to the matrix with incompatible sources unless the user explicitly overrides.
   • Fast path: if all sources are local, there are only 2–3 of them, and compatibility is clear (no conflicts, same abstraction level, overlapping triggers), use the compact fusion matrix path:
     • write a compact fusion matrix instead of the full matrix: source → keep / merge / drop + reason
     • keep the same compatibility, stance, generation, and review standards
     • escalate to the full matrix only if a conflict, overlap ambiguity, or scope split appears during drafting

6. Build a fusion matrix. For each source skill, extract rows into this structure:

   Source	Element type	Content summary	Verdict
   skill-a	trigger	"use when merging…"	keep — broadest scope
   skill-a	workflow-step	"load sources"	merge with skill-b step 1
   skill-b	decision-rule	"prefer local naming"	keep — unique
   skill-b	reference	"checklist.md"	drop — subsumed by fused review

   Element types: trigger, workflow-step, decision-rule, reference, example, anti-pattern.

   Verdicts: keep (into fused core), merge (combine with another row), move-to-ref (demote to references), drop (with reason: duplicate / weaker / stale / out-of-scope).

   After filling the matrix, confirm:

   • Every high-value behavior has a keep or merge verdict
   • Every drop has an explicit reason
   • Conflicting rows are resolved with a winner and rationale

7. Choose the fusion stance:

   • if any source is a local repo skill, prefer naming, structure, and heuristics closer to the local repo when that produces a better local result
   • otherwise prefer the most portable wording and structure that preserves execution quality

8. Generate a new fused skill package.

   • Default output: a new skill folder with SKILL.md
   • In this repo, place new local skills under .agents/skills/<skill-name>/
   • If the requested destination already exists, revise it in place only when the user clearly asked to replace or extend that skill. Otherwise choose a new narrow name and say why.
   • Add references/ only when detailed audit or variant-specific material would bloat the main file
   • Add scripts/ only when deterministic fetching or transformation is meaningfully better than prose
   • If any source is a local repo skill, name the fused result in the same local style:
     • use kebab-case
     • avoid generic merged-*, combined-*, or fused-* prefixes unless the user asked for them
     • if one local skill is the clear base, keep its naming family and extend it narrowly
   • If acquisition created temporary comparison material, keep it out of the shipped skill package unless it materially improves repeatable execution
   • If remote acquisition installed or copied local artifacts only for inspection, remove those artifacts before finalizing unless the user explicitly asked to keep the fetched skill itself

9. Run the review pass in references/fusion-review-checklist.md. The checklist includes simulation validation and precision-density tightening as final quality gates. Do not skip them — they catch execution-path bugs and bloat that static review misses. If any check fails, revise before finalizing.

Fusion rules

• Keep one canonical version of each rule or workflow step.
• Prefer the clearest and most actionable wording, not the longest wording.
• Preserve valuable capability even when the wording changes.
• Apply the precision-density test: every surviving sentence must change agent behavior in at least one realistic scenario. Cut generic filler, repeated best-practice text, and examples that do not teach anything new.
• Review remote skills before trusting them. Preserve only guidance that holds up after reading the actual skill contents.
• For fetched remote skills, default to keeping heuristics and workflow rules while dropping bulky catalogs, datasets, helper scripts, or stack-specific assumptions unless they materially improve repeatable execution in the fused result.
• Treat cleanup as part of fusion completion: if remote inspection created local install artifacts, remove them unless the user asked to keep them.
• If the result still reads like several skills pasted together, refactor again until it has one voice and one workflow.
• If two sources disagree, prefer:
  • stronger local heuristics for local-repo use
  • otherwise the more portable and less assumption-heavy rule
• Keep the fused skill focused on one coherent job. If the compatibility gate (step 5) was not run or was overridden, re-check here: if sources cover genuinely different jobs, recommend separate skills or partial fusion instead of forcing a bad merge.

Review standard

Review the fused result like a senior agent-skill designer.

When local guidance exists, use it during review, especially:

• .agents/skills/agent-skill-generator/SKILL.md
• .agents/skills/agent-skill-generator/references/skill-design-checklist.md
• .agents/skills/agent-skill-generator/references/token-optimization.md
• skills-lock.json when remote package identity or installed skill naming needs a local cross-check

If those files are unavailable, apply the bundled review checklist and the same standards: strong triggers, explicit workflow, portability, no important loss, and high precision density.

Output requirements

The fused skill should include:

• a kebab-case skill name
• frontmatter with only name and description
• a trigger-bearing description that says what the fused skill does and when to use it
• one procedural SKILL.md that another agent can execute without guessing
• optional references only when they reduce token cost

The final response should also summarize:

• where each source came from: local repo, existing local skills install, new package fetch, or user-provided content
• whether a compact or full fusion matrix was used, and why
• which source behaviors were merged into the core workflow
• which overlapping sections were removed
• which conflicts were resolved in favor of local conventions or portability
• whether any repo mutations occurred during acquisition and how they were handled
• any functionality intentionally excluded and why

Examples

Example: local fusion

User request: Fuse these local skill folders into one new skill and remove overlap.

Expected behavior:

1. Read the local skills and nearby repo conventions.
2. Prefer local naming and structure.
3. Produce one fused skill package with duplicate guidance removed.
4. Explain what was preserved, dropped, and rewritten.

Example: mixed local and remote fusion

User request: Combine this local skill with these two skills.sh skills into one portable skill.

Expected behavior:

1. Read the local skill first.
2. Acquire remote skills via the fallback chain: check local installs, then CLI fetch, then ask the user for content.
3. Run the compatibility gate before building the fusion matrix.
4. Preserve useful remote guidance, but prefer local heuristics when they better fit the local repo.
5. Simulate execution against representative prompts from each source.
6. Emit one fused skill package and a short merge rationale.

Example: remote package named, skill unresolved

User request: Fuse this local skill with the right skill from owner/repo that handles release docs.

Expected behavior:

1. Treat owner/repo as in scope, but do not inspect unrelated packages.
2. Use package inspection only to resolve the exact remote skill name.
3. Once resolved, continue with explicit skill names and the normal fusion flow.
4. Report any acquisition-side repo mutations separately from the shipped skill.

Example: not a fusion request

User request: Which two existing skills should I load together for this task?

Expected behavior:

1. Do not trigger fuse-skills.
2. Treat this as ordinary skill selection or composition, not creation of a new merged skill.