Skill Authoring

---
name: skill-authoring
description: Use when the operator asks to create, update, import, analyze, or preserve a reusable skill or recurring instruction pattern. Do NOT use for one-off ticket work, ordinary code implementation, problem-catalog incidents, or copying external skill text verbatim.
source_inspiration: conceptual-only
license_status: clean-room-original
fusebase_flow_version: 3.1
risk_level: medium
invocation: automatic
expected_outputs:
  - skill classification: framework skill vs project skill vs problem-catalog entry vs no skill
  - clean-room skill brief with role applicability and non-overlap analysis
  - canonical SKILL.md updates when implementation is approved
  - mirror / manifest / source-leak validation notes for framework skills
  - retrofit-hygiene sweep + matcher dry-run evidence for trigger/gate and description changes
related_workflows:
  - knowledge-curation.md
  - eight-phase-flow.md
hook_dependencies:
  - none
---

# Skill Authoring

> **Style:** Mode-B-lite. Clean-room, Fusebase-specific procedure for deciding, writing, wiring, and validating reusable skills.

## Purpose

Create or update skills without skill sprawl, role drift, mirror drift, or license contamination. This skill governs reusable instruction capture: what deserves a skill, where it belongs, which role uses it, and what validation proves it was authored cleanly.

## When to invoke

- Operator asks to create, update, install, import, compare, or analyze a skill.
- Operator provides an external skill, prompt, guide, or workflow and asks to reproduce similar capability in Fusebase Flow.
- A recurring pattern should become durable reusable expertise.
- Existing skill behavior needs tightening after a missed bug, failed handoff, or repeated role drift.
- A framework skill is added or changed and provider mirrors/manifests must stay in sync.

## Do not invoke when

- The request is normal per-ticket implementation covered by `implementation-planning`, `validation-and-qa`, or another domain skill.
- The issue is a one-off failure with a concrete cause; file `docs/problem-catalog/<slug>/problem.md` instead.
- The operator wants to copy external text verbatim. Refuse copying and offer clean-room capability extraction.
- The topic is already covered by an existing skill and only needs normal use, not authoring or update.
- A provider mirror is the only target. Canonical skill edits start in `flow-skills/` (framework) or `docs/skills/` (project-local); mirrors are generated or deliberately promoted.

## Required inputs

| Input | Where it lives | If missing |
|---|---|---|
| Operator request | chat | Stop; skill purpose depends on requested reuse |
| Candidate source material | attachment, repo file, operator summary, or observed repeated pattern | Proceed only from available concepts; do not invent missing domain rules |
| Existing skill catalog | `flow-skills/`, `.agents/skills/`, `.claude/skills/`, `docs/skills/README.md` | Search before adding; avoid duplicate skills |
| CLI edition map, for CLI provider assets | `docs/fusebase-cli-edition.md` | Treat provider assets as domain support, not canonical Flow skills |
| Skill substrate | `templates/skill-template.md` | Stop; use the canonical section order |
| Role boundaries | `FLOW_RULES.md`, `flow-skills/role-discipline/references/<role>.md`, `agents/*/AGENT.md` | Stop if role ownership cannot be assigned |
| Clean-room constraints | `docs/source-map.md`, `docs/clean-room.md` | Treat external material as concept-only |
| Mirror process | `hooks/local/mirror-skills.sh`, `audit/skill-mirror-manifest.txt` | Required for framework skill changes |

## Procedure

### 1. Classify the reusable knowledge

| If the pattern is... | Destination | Owner |
|---|---|---|
| Useful to every Fusebase Flow project and description-matchable by agents | `flow-skills/<slug>/SKILL.md` | Framework change; PO defines, AI Developer implements |
| Fusebase Apps CLI runtime/domain guidance already present in provider assets | `.agents/skills/<slug>/` and `.claude/skills/<slug>/` | Provider asset; reference from Flow artifacts, do not duplicate |
| Specific to one target project after 3+ repeated uses | `docs/skills/<slug>/SKILL.md` | Product Owner / project team |
| A one-off incident, outage, or diagnostic lesson | `docs/problem-catalog/<slug>/problem.md` | Product Owner |
| A one-ticket design or architecture choice | `docs/specs/<slug>/decisions.md` | Product Owner / Architect |
| Already covered by an existing skill | Update that skill or leave unchanged | Depends on owning role |

Default to updating an existing skill when overlap is material. Add a new framework skill only when the trigger, procedure, failure modes, and role boundary are distinct.

### 2. Extract capability clean-room

For external material:

1. Read only to identify capabilities, triggers, constraints, failure modes, and reusable checks.
2. Do not copy paragraphs, example blocks, proprietary labels, vendor-specific paths, or exact output formats.
3. Replace product/tool-specific assumptions with Fusebase Flow concepts: role, phase, artifact path, workflow, skill, policy, hook, mirror.
4. Remove prohibited or irrelevant brand terms before writing repo files.
5. Write a short comparison table: existing Fusebase skill overlap, new capability, recommended role.

The authorized MIT import documented at `docs/source-map.md#karpathy-guidelines` is a narrow exception to this skill's no-copy instructions and clean-room metadata requirements; preserve its license notice. Other imports remain concept-only.

### 3. Assign role applicability

| Role | Allowed authoring responsibility |
|---|---|
| Product Owner | Decide whether a skill is needed; classify framework vs project skill; define trigger, purpose, acceptance criteria, role applicability, and non-overlap |
| Architect | Review skill design when it changes role boundaries, workflows, hooks, provider compatibility, or broad framework semantics |
| AI Developer | Implement approved skill edits; update canonical files; regenerate mirrors; run validation; report evidence |
| Deploy phase | No skill authoring; may surface post-deploy lessons for PO curation |

If role ownership is unclear, stop and ask in chat text with 2-3 options; do not use popup / clickable menus.

### 4. Author the skill

Use `templates/skill-template.md` section order. Keep the body Mode-B-lite:

| Section | Requirement |
|---|---|
| Frontmatter | `name`, trigger-rich `description`, `source_inspiration: conceptual-only`, `license_status: clean-room-original`, version, risk, invocation, outputs, workflows, hooks |
| Purpose | 1-3 sentences; why this exists separately |
| When to invoke | concrete triggers the matcher/operator can recognize |
| Do not invoke when | negative triggers to prevent sprawl |
| Required inputs | table with location and fallback |
| Procedure | numbered or role-scoped steps |
| Worked example | procedure-heavy skills only: one compact example (≤12 lines) after Procedure — input → step outcomes → output |
| Output artifacts | paths and chat/artifact mode |
| Failure cases | detection and response |
| Escalation path | next skill/workflow/operator question |
| Anti-patterns | things the skill must not do |
| Clean-room note | standard Fusebase attestation |

Move long examples or variant-specific detail into `references/` only when needed. Do not create README, quick-reference, changelog, or other auxiliary files inside a skill folder.

### 5. Wire framework skills

For `flow-skills/<slug>/SKILL.md` changes, check whether each surface needs an update:

| Surface | Update when |
|---|---|
| `flow-skills/role-discipline/references/<role>.md` | role don't-list or refusal phrasing changes (shared protocols: `flow-skills/role-discipline/SKILL.md`) |
| `agents/product-owner/AGENT.md` | PO / Architect should load or invoke the skill |
| `agents/ai-developer/AGENT.md` | AI Developer / Deploy phase should load or invoke the skill |
| `workflows/*.md` | a workflow creates, consumes, or validates the skill |
| `templates/*.md` | generated artifacts need fields from the skill |
| `README.md`, `docs/framework.md`, `docs/compatibility.md`, `docs/source-map.md` | skill counts, catalog, compatibility, or attestation counts change |
| `CHANGELOG.md`, `docs/release-notes/<version>.md` | release-visible capability changes |

Then run `hooks/local/mirror-skills.sh` and, if agent files changed, `hooks/local/mirror-agents.sh`.

### 6. Validate

Minimum validation for framework skill changes:

| Check | Expected |
|---|---|
| Mirror integrity | canonical skill hash matches `.agents/skills/` and `.claude/skills/`; manifest regenerated |
| Agent mirror integrity | canonical agent hash matches `.claude/agents/` and `.codex/agents/` if agents changed |
| Source-leak scan | no external/prohibited names, copied phrases, or vendor-specific paths introduced |
| Count scan | no stale skill-count references after adding/removing framework skills |
| CLI provider boundary | provider CLI assets remain outside canonical `flow-skills/` unless separately approved as clean-room Flow framework skills |
| Format check | `git diff --check` clean except known line-ending warnings |
| Scope review | no unrelated refactors or duplicated skill responsibilities |
| Retrofit hygiene | on any trigger/gate change: propagation sweep clean — `grep` for each pre-change trigger phrase / artifact path returns 0 unexplained hits in the skill (see Retrofit-hygiene sweep below) |
| Matcher dry-run | on new skills / description changes: own `description` keyword-claims each of its 3-5 trigger phrases and none of its named siblings' phrases against the full description catalog (see Matcher dry-run below) |
| Worked example | procedure-heavy skill (Procedure with 3+ steps or a decision table) contains exactly one compact `## Worked example` (≤12 lines) |

If validation cannot run, report the exact missing check and treat the change as incomplete until the operator accepts that gap.

#### Retrofit-hygiene sweep (mandatory on any trigger/gate change)

A trigger/gate change = any edit to when the skill fires, what artifact gates it, which inputs it accepts, or which role owns it. Partial retrofits create self-contradicting skills; ALL surfaces update in the SAME edit:

| Surface | Must reflect the new trigger/gate |
|---|---|
| Frontmatter `description` | "Use when / ONLY when" names the new trigger/artifact set; no stale names |
| Header style line + Purpose | gating statement matches the new set |
| When to invoke / Do not invoke when | positive and negative triggers updated symmetrically |
| Required inputs | rows and "If missing" behavior accept the new set |
| Procedure | every step — especially existence/first-step gates — checks the new set |
| Failure cases + Escalation path | detection, response, and referenced artifacts use the new set |
| External restatements | sibling skills, README catalog, `AGENTS.md` overlay, `agents/*/AGENT.md` lines quoting this trigger |

Mechanical check: for each pre-change trigger phrase / artifact path, `grep -n '<old-string>' flow-skills/<slug>/SKILL.md` → 0 hits, or every remaining hit is deliberate and explained in the change evidence.

Anti-example (real): `business-logic-guardian` v3.5 was retrofitted to accept `business-logic-index.md` in "When to invoke", but frontmatter `description`, Required inputs, Procedure step 1, and Escalation still gated on `business-logic.md` only — the skill no-opped on projects holding only the index and contradicted its own body. This sweep exists to make that class impossible.

#### Matcher dry-run (mandatory on new skills and description changes)

| Step | Action | Pass condition |
|---|---|---|
| 1 | List 3-5 operator phrases this skill claims (from `description` + When to invoke) | — |
| 2 | Dump the catalog: `grep -H '^description:' flow-skills/*/SKILL.md`. Per own phrase: (a) confirm THIS skill's `description` contains the phrase's 1-2 distinctive keywords — absent keywords = phrase never fires; (b) scan every other description for those keywords — any that also plausibly claims the phrase = COLLISION | every own phrase keyword-present in own `description`; every collision resolved: add an explicit "<sibling> owns that" Do-NOT clause here or narrow the trigger |
| 3 | List 2-3 phrases owned by the nearest siblings (skills named in this skill's "Do NOT use" line or Do-not-invoke section) | own `description` claims NONE of their keywords (step 2b scan, reversed) |
| 4 | Record the phrase → winning-skill table in change evidence (chat or gate note) | table present |

Any keyword-absent own phrase, unresolved collision, or claimed sibling phrase → fix `description` / Do-not-invoke boundaries BEFORE running `mirror-skills.sh`.

#### Worked-example requirement

Every procedure-heavy skill — Procedure with 3+ steps or a decision table — carries exactly ONE `## Worked example` after Procedure: ≤12 lines, Mode-B-lite, concrete input → key step outcomes → produced artifact. One example, not a tutorial; variant detail goes to `references/` only if genuinely needed. Applies to new skills at authoring time and to any existing skill on its next material update — no mass retro-edit of untouched skills.

## Worked example

Request: "guardian should also accept the new index doc" — a trigger/gate change to an existing framework skill.

1. Classify (§1): update existing `business-logic-guardian`; no new skill.
2. Author (§4): add `business-logic-index.md` to the activation gate.
3. Retrofit sweep (§6): `grep -n 'business-logic\.md' flow-skills/business-logic-guardian/SKILL.md` → update frontmatter `description`, When/Do-not-invoke, Required inputs, Procedure step 1, Escalation in the SAME edit; 0 unexplained stale hits.
4. Matcher dry-run (§6): "don't break the business logic" → guardian wins; "document the business logic" → `app-business-docs` still wins.
5. Wire + mirror (§5): `hooks/local/mirror-skills.sh`; manifest regenerated.

Evidence: sweep greps + dry-run table in the gate note.

## Output artifacts

| Artifact | Path or location | Mode |
|---|---|---|
| Skill analysis / recommendation | chat | Mode A |
| Framework skill | `flow-skills/<slug>/SKILL.md` | Mode-B-lite |
| Project skill | `docs/skills/<slug>/SKILL.md` | Mode-B-lite |
| Problem-catalog alternative | `docs/problem-catalog/<slug>/problem.md` | Mode B |
| Mirror manifest | `audit/skill-mirror-manifest.txt` | generated |
| Agent mirror manifest | `audit/agent-mirror-manifest.txt` | generated when agents change |

## Failure cases

| Failure mode | Detection | Response |
|---|---|---|
| Duplicate skill | Existing skill has same trigger/procedure | Update existing skill or recommend no change |
| External text copied | Source-leak scan or review finds copied prose/examples | Replace with clean-room rewrite before claiming done |
| Wrong location | Project-specific skill added under `flow-skills/`, or framework skill placed only under `docs/skills/` | Move to correct surface and update references |
| Mirror drift | Preflight/hash check finds mirror mismatch | Run mirror script and re-check |
| Role drift | PO writes production code via skill, or AI Developer changes product direction | Stop; apply `role-discipline` refusal and re-scope |
| Overlong skill | SKILL.md grows toward large reference-guide size | Split variant detail into `references/` and keep SKILL.md procedural |
| Stale retrofit | retrofit-hygiene sweep finds a section still describing the pre-change trigger/gate | propagate in the same edit; re-sweep to 0 stale hits before mirroring |
| Trigger collision | matcher dry-run finds a keyword-absent own phrase, an unresolved description collision, or a claimed sibling phrase | rewrite `description` / Do-not-invoke boundary; re-run dry-run |

## Escalation path

- If the operator wants a new framework skill but overlap is unclear, ask for approval in chat text with an options table: update existing skill, create new skill, or file project skill.
- If the skill changes hooks, policies, or workflow semantics, escalate to Architect review before implementation.
- If implementation touches provider mirrors or manifests, hand to AI Developer for canonical edit + mirror regeneration.
- If clean-room status cannot be established, stop and request a concept summary instead of using the source text.

## Domain-expert skill mode

Use when the operator wants a skill that makes the agent an **expert in a specific product area / industry** (e.g. dental clinics, legal intake, fitness) so app work uses best-practice patterns and known market-solution categories instead of reinventing the wheel. The produced skill is **project-local** (lives under the project's own skill area, not Flow canonical `flow-skills/`, and is **not** mirrored or added to the Flow manifest) and is **input-dependent** — it needs the operator's domain + any research they supply.

| Step | Action |
|---|---|
| 1. Confirm need | A real, repeated domain — not a one-off ticket. One domain = one skill. |
| 2. Gather inputs | Operator's vision + research dropped at `docs/<app>/research/`. The agent does NOT invent domain facts. |
| 3. Scope the expertise | Domain vocabulary, standard workflows, common entities/data, regulatory/trust constraints, typical client-vs-internal needs. |
| 4. Market awareness | List the *categories* of established solutions so the agent reuses proven patterns — **never copy competitor names, prose, code, or licensed assets** (clean-room). |
| 5. Author | Follow `templates/skill-template.md`; description leads with the domain triggers; cite where each domain fact came from. |
| 6. Place (do NOT mirror) | Project-local domain skill, not Flow canonical. Do not run `mirror-skills.sh` for it; do not add it to `audit/skill-mirror-manifest.txt`. |

The *authoring method here* is generic (ships with Flow); the *produced domain skill* is project-specific and absent by default.

## Anti-patterns

- Do not copy external skill prose, example blocks, or proprietary labels.
- Do not write directly to `.agents/skills/` or `.claude/skills/` as the source of truth.
- Do not promote CLI provider assets into canonical `flow-skills/` without a separate clean-room proposal and non-overlap analysis.
- Do not add a new skill when a narrow update to an existing skill covers the behavior.
- Do not use a skill for a one-off bug that belongs in the problem catalog.
- Do not make Product Owner sessions implement code or AI Developer sessions lock product decisions.
- Do not ask skill-authoring questions through popup / clickable menus; use chat text per FR-19.
- Do not leave mirrors, manifests, counts, or release docs stale after adding a framework skill.
- Do not change a skill's trigger/gate in one section and leave any other § Retrofit-hygiene sweep surface on the old gate — that section owns the ONLY surface list (never re-enumerate it elsewhere); run the sweep in the same edit or do not ship.

## Clean-room note

Original Fusebase Flow content. Designed after reviewing public AI coding workflow patterns; no third-party code, prompts, skill files, or hook scripts are copied. See `docs/source-map.md`.