fuse-skills

name	fuse-skills
description	Combine 2 or more agent skills into one new merged skill without duplicated guidance or lost capability. Use when the user asks to merge, fuse, consolidate, deduplicate, or unify multiple local skills, `skills.sh` skills, or a mix of both into a single portable, precision-dense skill package. Do not use for ordinary multi-skill composition unless the goal is to create a new fused skill.

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

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.