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.

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 " 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.