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

Procedure

1. Classify the reusable knowledge

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

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:

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:

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:

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:

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)

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

Failure cases

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.

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.