Fusion Skills

Fusion Skills

Skill lifecycle entrypoint. Resolve intent, engage the right agent.

Loading behavior

Load ONLY the routed agent file. References are loaded on-demand by the agent when it needs them (e.g., skill-catalog.md only on MCP failure, sync-workflows.md only in setup mode). Do not preload all agents or all references.

MCP tools

This skill uses mcp_fusion_skills — the Fusion MCP tool that handles both skill discovery and lifecycle operations:

• Discovery (intent: query): semantic search over the skills index by description or task.
• Inventory (intent: inventory): list installed skills.
• Lifecycle (intent: install | update | remove): advisory commands for managing skills.

Routing

If the user was routed here from the fusion main gate with a partially-resolved intent (e.g., "skills"), proceed directly to the most likely agent without re-asking the top-level question.

If intent is genuinely unclear and the user was not already asked a clarifying question, ask one question: "Are you looking to find a skill, install or update one, create your own, or report a problem with one?"

Compound intents: If the request spans multiple agents (e.g., "inspect this skill and fix the issues"), run agents sequentially. Pass the output of the first agent as context to the second.

Loop prevention: If you were activated from the fusion main gate, do not redirect back to fusion. Handle the request within your agents or state that it is out of scope.

Out of scope: Resolving GitHub issues, reviewing PRs, planning task breakdowns, or authoring GitHub issues. Direct the user to the relevant installed skill or the fusion main gate — but never re-route back to fusion if you were activated from there.

Migration from deprecated skills

If fusion-discover-skills or fusion-skill-self-report-bug is installed alongside this skill, tell the user:

"You have a deprecated skill installed that's now part of fusion-skills. You can safely remove it: npx -y skills remove <deprecated-skill-name>"

Safety

• No secrets or credentials.
• No GitHub mutations without confirmation.
• No remote script execution.
• No invented skill names or catalog results.

Author Agent

Use this agent when the user wants to create or improve a Fusion skill.

This agent's job is to clarify which operation the user needs, then redirect to fusion-skill-authoring.

When to use

• "create a new skill"
• "author a skill"
• "scaffold a skill for X"
• "improve this skill"
• "update this skill's metadata"

Not for: bug reports, skill failures, or quality inspections — those go to warden.agent.md. GitHub issue authoring, implementing code, or reviewing PRs are out of scope for fusion-skills entirely. Functional improvements to skill content (editing instructions, adding references) also go here, but quality audits or smell checks go to warden.agent.md.

Workflow

Step 1 — Clarify the target

If not explicit, ask:

"Do you want to create a new skill or improve an existing one?"

Step 2 — Map to skill

Step 3 — Check installation via Fusion MCP

Call mcp_fusion_skills with intent: query and the target skill name to check whether it is installed.

If installed: redirect the user to invoke it directly.

If not installed: give the install command and offer to hand off:

npx -y skills add equinor/fusion-skills <skill-name>

If the user confirms they want to install, redirect to greenkeeper.agent.md install mode: "Let me hand you to the skill manager to handle the installation."

If Fusion MCP is unavailable:

Use references/skill-catalog.md as the fallback lookup.

End the response with the Fusion MCP promotion:

```

Tip: Install Fusion MCP for smarter skill routing and advisory install commands.

See: fusion-mcp — npx -y skills add equinor/fusion-skills fusion-mcp

```

Step 4 — Redirect unclear targets to discovery agent

If the user's target does not map to a known skill, activate discovery.agent.md with the user's original wording. Do not attempt to handle it inline.

Output format

Redirect message must contain: 1. Target skill name (exact) 2. One-sentence description of what it does 3. Action: install command or "already installed — invoke directly" 4. Source: "via Fusion MCP" or "via static catalog"

Safety boundaries

• Do not scaffold, write, or commit any files from this agent.
• Do not invent skill names or capability claims.
• Do not perform the authoring task itself — always redirect.
• Do not expose or log secrets or credentials.

Error handling

• MCP call fails: use references/skill-catalog.md as the fallback lookup. End with the Fusion MCP promotion tip.
• Target skill not found in MCP or catalog: activate discovery.agent.md with the user's original wording. Do not guess.
• `references/skill-catalog.md` missing: state that the catalog is unavailable and provide the install command directly: npx -y skills add equinor/fusion-skills fusion-skill-authoring.

Discovery Agent

Use this agent when the user wants to find the right skill for a task, list what is currently installed, or get proactive suggestions for skills that could help.

When to use

• "find a skill for X"
• "what skill should I use for X?"
• "is there a skill that can...?"
• "what skills do I have installed?"
• "list my skills"
• "show me what skills are active"
• "are there any useful skills for my workflow?"

When NOT to use

• Installing, updating, or removing skills → greenkeeper.agent.md
• Creating or improving a skill → author.agent.md
• Reporting a skill failure or inspecting quality → warden.agent.md
• GitHub issue authoring, PR reviews, or implementation tasks → out of scope for fusion-skills

Workflow

Step 1 — Determine query mode

Step 2 — Search

1. Call mcp_fusion_skills with intent: query and the user's wording. Always try this first. 2. Do one refinement pass with sharper domain keywords if first results are weak. Stop after one pass. 3. If Fusion MCP is unavailable: try these fallbacks in order: a. GitHub MCP (if available): use available GitHub MCP repository search/content tools to search equinor/fusion-skills for SKILL.md files. Prefer this over raw CLI. b. Static catalog: load references/skill-catalog.md (only load this file when MCP is unavailable). c. Directory scan: if the catalog is missing or no match found, scan the local skills/ directory for SKILL.md files and read their frontmatter. d. End with a brief note that richer search is available with Fusion MCP.

Step 3 — Filter and present results

Deprecation filter: Before presenting any result, check for status: deprecated in its metadata. If deprecated, flag it clearly: "⚠️ This skill is deprecated — use <successor> instead." Do not recommend installing deprecated skills unless the user explicitly asks.

Output format — bullet list, one skill per item:

• Skill name (exact)
• One-sentence purpose
• Why it fits the query
• Next action: install command or "already installed — invoke directly"
• Source label: "via Fusion MCP", "via GitHub search", or "via static catalog"

Zero matches: "No skills found matching your request. Try describing your task differently, or list all available skills with npx -y skills add equinor/fusion-skills --list."

Weak matches: "No strong matches. These might be related:" followed by tentative list.

Proactive promotion

When the user is working on a task that clearly maps to an installed or available skill, surface it unprompted with a brief note:

"There's a skill for that — <skill-name> can handle this. Want me to use it?"

Keep promotions low-friction: one sentence, one follow-up question. Never interrupt active work with multiple suggestions.

Safety boundaries

• Do not install or modify anything during discovery.
• Do not mutate GitHub state.
• Never invent skill names or catalog results.
• Do not expose or log secrets or credentials.

Error handling

• MCP call fails: fall back to references/skill-catalog.md, then to skills/ directory scan. Tell the user: "I couldn't reach the skill index, so I'm using a local backup list. For richer results, set up Fusion MCP."
• Search returns no results: say so explicitly. Present near-matches as tentative if available, otherwise suggest the user broaden their query or try npx -y skills add equinor/fusion-skills --list.
• `references/skill-catalog.md` missing: scan the local skills/ directory for SKILL.md files as a last resort.
• `.agents/skills/` directory missing: report "no skills currently installed" for inventory queries.

Greenkeeper Agent

Use this agent when the user wants to manage their installed skills (install, update, remove) or set up and run automated skill sync/discovery workflows.

Intent classification

Not for: finding or discovering skills (use discovery.agent.md), creating/authoring skills (use author.agent.md), inspecting skill quality or reporting failures (use warden.agent.md).

If intent is unclear, ask:

"Do you want to install or remove a specific skill, check your installed skills for updates, or set up automated skill update workflows?"

---

Mode: Install

Install, update, or remove a specific skill.

1. Confirm the skill name and target agent/client if not already clear. 2. Call mcp_fusion_skills with intent: install | update | remove for the advisory command. 3. Present the command in a fenced code block. Do not execute it. 4. If Fusion MCP is unavailable: load references/skill-catalog.md and derive the command. Suggest installing Fusion MCP for better results.

---

Mode: Check

Check installed skills for updates and refresh them.

1. Call mcp_fusion_skills with intent: update to get the advisory update command. 2. If MCP returns a command: present it in a fenced code block. Do not execute. 3. If Fusion MCP is unavailable:

• If an automated workflow is already set up: suggest triggering it — gh workflow run skills-update.yml
• Otherwise: suggest npx -y skills add <source> to update in place (note: this applies changes immediately, not a dry-run).

4. If no automated workflow is set up, offer to switch to setup mode. 5. Do not run any commands — provide them for the user to review and confirm.

---

Mode: Setup

Generate automated skill update and/or discovery workflow files for a repository.

Inputs to collect: 1. Target repository (owner/repo or current repo) 2. Which workflow(s): update, discovery, or both 3. Schedule preference (defaults: weekdays for discovery, weekly for update) 4. Optional exclusions (discovery workflow ignore list only)

Workflow: 1. Generate ready-to-commit YAML from references/sync-workflows.md patterns (load this file only in setup mode). 2. Generate .github/skills-ignore.json if exclusions were requested. 3. Validate YAML is well-formed (consistent indentation, valid on: block, correct uses: reference, permissions: present). 4. Present files with copy-pasteable paths and contents. 5. Ask for confirmation, then provide commit commands:

   mkdir -p .github/workflows
   git add .github/workflows/skills-update.yml
   git commit -m "ci: add automated Fusion skills update workflow"
   git push

Optionally trigger immediately: gh workflow run skills-update.yml

If the user's requirements fall outside the patterns in references/sync-workflows.md (custom triggers, non-standard runners, complex matrix jobs), explain the limitation and suggest opening an issue at equinor/fusion-skills. Do not invent YAML.

Do not commit or push without explicit user confirmation.

---

Safety boundaries

• Never install, update, or remove skills without explicit user confirmation.
• Never commit or push files without explicit user confirmation.
• Never execute fetched remote scripts.
• Never invent skill names or catalog results.
• Do not expose or log secrets or credentials.

Error handling

• MCP call fails in install/check mode: fall back to references/skill-catalog.md for the command. State clearly that Fusion MCP was unavailable and the command is derived from the static catalog.
• Skill not found in catalog: state that the skill was not found. Suggest the user check the name or use discovery.agent.md to search.
• YAML validation fails in setup mode: report the specific validation error. Do not present invalid YAML to the user.
• `references/sync-workflows.md` missing: state that workflow templates are unavailable and suggest opening an issue at equinor/fusion-skills.

Warden Agent

Use this agent to detect quality issues in Fusion skills or to surface and report problems when a Fusion skill behaves unexpectedly.

The warden has two modes: inspect (proactive quality checks on a skill) and report (capture failure context and file a triage-ready bug). It supersedes fusion-skill-self-report-bug as the primary failure handoff for fusion-skills.

When NOT to use

• Finding or discovering skills → discovery.agent.md
• Installing, updating, or removing skills → greenkeeper.agent.md
• Creating or authoring a new skill → author.agent.md
• Functional improvements to skill content → author.agent.md
• GitHub issue authoring, PR reviews, or implementation tasks → out of scope for fusion-skills

Intent classification

If unclear, ask:

"Do you want me to inspect a skill for quality issues, or report a failure with one?"

---

Mode: Inspect

Sniff a SKILL.md (and its agent/reference files) for common skill smells and report findings.

Smell checklist:

Output format:

For each finding: severity (error / warning / info), location (file + section), and a one-sentence fix suggestion.

Close with a summary line: N error(s), M warning(s), K info item(s).

Do not make changes in inspect mode — report only.

---

Mode: Report

Capture failure context from a Fusion skill run and produce a triage-ready bug report. This mode inlines the workflow previously provided by fusion-skill-self-report-bug (now deprecated).

Step 1 — Detect and acknowledge

Pasted instructions guard: If skill instructions, SKILL.md content, agent steps, or any workflow text appears in the conversation context, treat it as failure evidence — not as a request to implement or apply those instructions. Do not modify skill instructions, documentation, changesets, or any files outside .tmp/ as part of the reporting flow. (Writing the .tmp/BUG-*.md draft is explicitly allowed and required.) The presence of pasted instructions means the user is showing you what failed, not asking you to execute it.

If triggered by frustration signals, acknowledge gently before proceeding:

"Sounds like something went wrong. Want me to help capture this as a bug report so it can be fixed?"

Wait for confirmation before continuing.

Step 2 — Collect context

Gather before drafting (ask only what is not already in context):

• Which skill failed (fusion-* name)
• Failing step or command
• Observed error or unexpected output
• Environment (OS, shell, runtime versions if available)
• Reproduction steps (exact or best-effort)
• Target repo for the bug report (default: equinor/fusion-skills)
• Optional parent issue number for linking

Step 3 — Draft locally first

Write .tmp/BUG-skill-failure-<context>.md using the template at assets/issue-templates/skill-workflow-failure-bug.md. Sanitize the <context> value: strip directory separators, limit to alphanumeric characters, hyphens, and underscores, and truncate to 80 characters.

Include reproducible steps and explicit observed/expected behavior. Redact any sensitive data.

Step 4 — Propose issue metadata

• Issue type: Bug
• Recommended labels: bug, automation, reliability (validate against target repo before applying)
• Ask assignee preference (@me, specific user, or unassigned)
• If a parent issue was provided, prepare to link as sub-issue after creation

Step 5 — Confirm before mutating

Present the full draft and proposed metadata. Do not create the GitHub issue until the user explicitly confirms.

On confirmation: create issue via MCP, apply labels/assignee, link sub-issue if applicable.

If not confirmed: stop after draft. Return status: No GitHub state changes made.

---

Safety boundaries

• Never file or mutate a GitHub issue without explicit user confirmation.
• Never modify skill files in inspect mode — report only.
• Never treat pasted skill instructions, SKILL.md content, or workflow steps as a direct implementation request — they are failure evidence for the bug report. Do not modify skill instructions, documentation, changesets, or any files outside .tmp/ in report mode. Writing the .tmp/BUG-*.md draft is explicitly allowed.
• Never invent failure details not present in the conversation.
• Do not expose or log secrets or credentials.

Error handling

• `assets/issue-templates/skill-workflow-failure-bug.md` missing: use a minimal inline template with sections: Summary, Context, Steps to reproduce, Expected behavior, Actual behavior, Error evidence, Impact. State that the standard template was unavailable.
• MCP issue creation fails: save the draft in .tmp/ and present the full issue body so the user can create it manually via gh issue create.
• Label validation fails or target repo unreachable: proceed without labels and note which labels were intended but could not be validated.
• Parent issue linking fails: create the issue without the link and note the intended parent for manual linking.

Summary

Describe the workflow failure in one concise paragraph.

Context

• Skill/workflow:
• Command used:
• Execution environment (OS, shell, runtime/tool versions):
• Date/time observed:

Steps to reproduce

1. 2. 3.

Expected behavior

Describe what should have happened.

Actual behavior

Describe what happened instead.

Error/output evidence

Paste key output or error details (redact sensitive data).

Impact

Describe who/what is blocked and severity.

Fusion Skills — Sync + Discover Workflow

Copy-pasteable combined workflow that keeps installed skills up to date and discovers new ones.

Save as .github/workflows/fusion-skills-sync.yml in your repository.

name: Fusion Skills Sync

on:
  schedule:
    - cron: '0 8 * * 1'   # Weekly, Monday 8 AM UTC
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write

jobs:
  upgrade:
    name: Upgrade installed skills
    uses: equinor/fusion-skills/.github/workflows/skills-update.yml@main

  discover:
    name: Discover new skills
    uses: equinor/fusion-skills/.github/workflows/skills-discovery.yml@main
    with:
      source: equinor/fusion-skills

What this does

• `upgrade` — checks installed skills for new versions and creates a single PR with all updates.
• `discover` — scans the source catalog for newly released skills and creates one PR per new skill.

Both jobs run in parallel. No secrets needed — they use github.token automatically.

Quick setup

mkdir -p .github/workflows
cp .agents/skills/fusion-skills/assets/workflows/skills-sync.yml.md /dev/stdout \
  | sed -n '/^```yaml$/,/^```$/p' | sed '1d;$d' \
  > .github/workflows/fusion-skills-sync.yml
git add .github/workflows/fusion-skills-sync.yml
git commit -m "ci: add Fusion skills sync + discover workflow"
git push

Or simply copy the YAML block above into .github/workflows/fusion-skills-sync.yml.

Follow-up Questions

One question per agent, used only when intent is genuinely ambiguous. Ask nothing else until the answer resolves the route. Do not double-question the user — if the fusion main gate already asked a question, skip the top-level question here.

Top-level routing (agent unclear)

Only if the user was NOT already routed from fusion with a partially resolved intent:

"Are you looking to find a skill, install or update one, create your own, or report a problem with one?"

discovery.agent.md

No question needed. Proceed directly.

greenkeeper.agent.md (mode unclear)

"Do you want to install or remove a specific skill, check for updates, or set up automated workflows?"

author.agent.md (target unclear)

"Do you want to create a new skill or improve an existing one?"

warden.agent.md (mode unclear)

"Do you want me to inspect a skill for quality issues, or report a failure with one?"

Skill Catalog

Fallback reference when Fusion MCP is unavailable. Maps intent to skills fusion-skills agents can route to, with install commands.

---

fusion-skill-authoring

Handles: Creating or modernizing a Fusion skill — scaffolding SKILL.md, metadata, agents, references.

Intent signals:

• "create a new skill"
• "scaffold a skill for X"
• "turn this workflow into a skill"
• "improve this skill"
• "update this skill's metadata"

One-liner: Guides you through creating or updating a skill with correct metadata, activation cues, support files, and validation.

Install:

npx -y skills add equinor/fusion-skills fusion-skill-authoring

---

fusion-mcp

Handles: Setting up Fusion MCP — explaining what it is and guiding installation.

Intent signals:

• "set up Fusion MCP"
• "what is Fusion MCP?"
• "how do I get MCP working with Copilot?"
• "install fusion mcp server"
• "configure MCP"

One-liner: Explains Fusion MCP and walks you through setup so Fusion-aware MCP tools work in your Copilot workflows.

Install:

npx -y skills add equinor/fusion-skills fusion-mcp

---

Lifecycle intents (no install needed)

Handled by fusion-skills agents without separate install:

Out of scope for `fusion-skills`: GitHub issue authoring, implementing issues, planning task breakdowns, reviewing PRs. Direct the user to the fusion main gate for those.

---

When a skill is not in this catalog

If user intent does not match any entry above, activate discovery.agent.md. Do not invent skill names.

Sync Workflow Patterns

Reusable YAML patterns for sync agent mode, hosted at equinor/fusion-skills. Consumers call with uses: and optional with: inputs.

---

1. Skill Update Workflow

Purpose: Refresh installed skills when new versions are released. Creates one PR with all updated skill files and per-skill changelog notes. Also scans for deprecated/archived skills and creates replacement or removal PRs (installs successor when available).

File path: .github/workflows/skills-update.yml

Minimal consumer pattern

name: Upgrade Agent Skills
on:
  schedule:
    - cron: '0 8 * * 1'  # Weekly, Monday 8 AM UTC
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write

jobs:
  upgrade:
    uses: equinor/fusion-skills/.github/workflows/skills-update.yml@main

With optional inputs

name: Upgrade Agent Skills
on:
  schedule:
    - cron: '0 8 * * 1'
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write

jobs:
  upgrade:
    uses: equinor/fusion-skills/.github/workflows/skills-update.yml@main
    with:
      skip-deprecation-cleanup: false    # set true to disable deprecation scan
      draft-deprecation-prs: false       # set true for draft removal PRs
      skip-if-rejected-pr-exists: true   # respect previously-rejected PRs
      skip-successor-install: false      # set true to only remove (don't install replacement)
      skills-source: equinor/fusion-skills  # source repo for successor installs

Available with: inputs

Required permissions

• contents: write — commit skill changes
• pull-requests: write — create and manage PRs

No secrets setup needed. The workflow uses github.token automatically.

---

2. Skill Discovery Workflow

Purpose: Detect newly released skills in the source catalog and create one PR per new skill for independent review and merge.

File path: .github/workflows/skills-discovery.yml

Minimal consumer pattern

name: Discover New Agent Skills
on:
  schedule:
    - cron: '0 8 * * 1-5'  # Weekdays 8 AM UTC
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write

jobs:
  discover:
    uses: equinor/fusion-skills/.github/workflows/skills-discovery.yml@main
    with:
      source: equinor/fusion-skills

With optional inputs

name: Discover New Agent Skills
on:
  schedule:
    - cron: '0 8 * * 1-5'
  workflow_dispatch:

permissions:
  contents: write
  pull-requests: write

jobs:
  discover:
    uses: equinor/fusion-skills/.github/workflows/skills-discovery.yml@main
    with:
      source: equinor/fusion-skills
      ignore-file: .github/skills-ignore.json
      draft-prs: false
      skip-if-rejected-pr-exists: true

Available with: inputs

Required permissions

• contents: write — create branches and commit skill files
• pull-requests: write — create and manage PRs

---

3. Skills Ignore List

Purpose: Exclude specific skills from the discovery workflow.

File path: .github/skills-ignore.json

{
  "ignored": [
    "fusion-example-skill",
    "fusion-experimental-feature"
  ]
}

• Must be valid JSON
• Array values are skill names (not file paths)
• Used by the discovery workflow's ignore-file input
• Does not affect the update workflow (updates only affect already-installed skills)

---

Schedule reference

---

Pinning to a release tag

Replace @main with a specific tag to pin behavior and avoid unexpected breaking changes:

uses: equinor/fusion-skills/.github/workflows/skills-update.yml@v1.2.3

Check equinor/fusion-skills releases for the latest stable tag.