skf-update-skill
Smart regeneration preserving [MANUAL] sections after source changes. Use when the user requests to "update a skill" or "regenerate a skill."
Install
npx skills add https://github.com/armelhbobdad/bmad-module-skill-forge/tree/main/src/skf-update-skill
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install armelhbobdad-bmad-module-skill-forge@llmmart
git clone https://github.com/armelhbobdad/bmad-module-skill-forge.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole armelhbobdad/bmad-module-skill-forge collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Update Skill
Overview
Surgically updates existing skills when source code changes, preserving all [MANUAL] developer content while re-extracting only affected exports with full provenance tracking; unchanged content is never touched, and each regenerated instruction cites code by file:line (a docs-only skill cites its documents' URLs). Stack skills (skill_type: "stack" in metadata.json) are not updated here: this workflow redirects them to skf-create-stack-skill, which re-composes them from updated constituents.
Conventions
- Bare paths (e.g.
references/<name>.md) resolve from the skill root, inside areferences/file too: only a stage's frontmatternextStepFile,gapDrivenStepFile,noChangeReportFileandreportFilename a file beside it. - Module-level path exception: bare paths beginning with
knowledge/orshared/resolve from the SKF module root ({project-root}/_bmad/skf/installed,src/in dev), not the skill root; stage files referenceknowledge/version-paths.mdandknowledge/tool-resolution.md, and the terminal step chains toshared/health-check.md. - Sibling skills: a path that names another SKF skill's folder (
skf-<name>/...) resolves from the SKF module root, and that skill must be installed with this one. references/holds the workflow stages, chained by each file's frontmatternextStepFile(load-baseline.md §8 loadsgap-driven.mdthroughgapDrivenStepFileinstead whenupdate_modeisgap-driven), the invocation contract, and two sub-references a stage loads in place:write-metadata.md(write.md §3b) andbody-split.md(verify-publish.md §7);scripts/holds this skill's own helper.{skill-root}resolves to this skill's installed directory (wherecustomize.tomllives, if present).{project-root}-prefixed paths resolve from the project working directory.{skill-name}resolves to the skill directory's basename.- Cross-skill data coupling: stages load extraction rules and templates from
skf-create-skill, each named in the stage's frontmatter or where the stage reads it, so create and update extract alike.
Role
You are a precision code analyst operating in Ferris Surgeon mode. This is a surgical operation, not an exploratory session. You bring AST-backed structural analysis and provenance-driven change detection expertise, while the source code provides the ground truth.
Workflow Rules
These rules apply to every step in this workflow:
- Never hallucinate: every statement cites where it was read (an ast-grep match, a source line read by eye, or a docs URL), with that method's confidence label
- [MANUAL] sections survive regeneration with zero content loss
- Only load one step file at a time — never preload future steps
- Run every subagent in the foreground, passing
run_in_background: falseon every Agent call (Claude Code runs a subagent in the background when the flag is left out), with parallel ones as several such calls in one message, and wait for every long-running command to exit before the next instruction; in a headless run, never end a turn while either still runs, since underclaude -pa run stops when its turn ends. - Always communicate in
{communication_language} - If
{headless_mode}is true, auto-proceed through confirmation gates with their default action and log each auto-decision - Every HALT, ABORT or other exit before step 7 runs the Halt procedure of the step file it fires in: one
{runStateHelper}haltcall that undoes this run's writes, removes the private source tree, releases the run lock and, headless, prints the halt's line. A halt never falls through to step 6. - While
{source_tree}is bound, a step that finds{source_root}missing HALTs with statusblocked(error.phase<step>:source-tree-missing) instead of reading its files as deleted. - Run log. Warnings and gate decisions live in the run folder, never only in context: a step records each warning the moment it raises it, and each gate its decision, with the
recordcall that step names. - Run context. A binding lost from context is read back from
{run_dir}/run-context.json.
Stages
| # | Step | File | Auto-proceed |
|---|---|---|---|
| 1 | Initialize | references/init.md | Yes |
| 1b | Load the Baseline | references/load-baseline.md | No (confirm) |
| 2a | Reconcile the Brief's Scope | references/reconcile-scope.md | Conditional (§1b and §1c ask when triggered) |
| 2 | Detect Changes | references/detect-changes.md | Conditional (§2.2 asks when triggered) |
| 2g | Gap-Driven Repair (only when update_mode is gap-driven: with 3g, in place of steps 2a to 3) |
references/gap-driven.md | Conditional (§1 rule R1 asks [D]/[R] when a gap's remediation names removal) |
| 3g | Gap Spot-Check | references/gap-spot-check.md | Yes |
| 3 | Re-Extract | references/re-extract.md | Yes |
| 4 | Merge | references/merge.md | Conditional (§4 asks on a [MANUAL] conflict) |
| 4b | Write the Merged Files | references/merge-write.md | Yes |
| 5 | Write | references/write.md | Yes |
| 5b | Verify and Publish | references/verify-publish.md | Yes |
| 6 | Report | references/report.md | Yes |
| 7 | Workflow Health Check | references/health-check.md | Yes |
Invocation Contract
Headless callers: the inputs, flags, gate map, outputs and the SKF_UPDATE_RESULT_JSON line live in references/invocation-contract.md. Interactive runs do not need it.
On Activation
Load config from
{project-root}/_bmad/skf/config.yamland resolve:project_name,output_folder,user_name,communication_language,document_output_languageskills_output_folder,forge_data_folder,sidecar_path
Resolve
{headless_mode}: true if--headlessor-Hwas passed as an argument, or ifheadless_mode: truein{sidecar_path}/preferences.yaml. Default: false. Bind{requested_skill}← the skill name or folder path the invocation passes (its argument that is neither a flag nor a flag's value), else empty:references/init.md§1 takes it as the skill without asking.Resolve the shared helpers and create the run folder, before anything can halt. Resolve
{emitEnvelopeHelper}← the first that exists of{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.pyand{project-root}/src/shared/scripts/skf-emit-result-envelope.py. Resolve{runStateHelper}← the first that exists of{project-root}/_bmad/skf/shared/scripts/skf-update-run-state.pyand{project-root}/src/shared/scripts/skf-update-run-state.py. Then, from{project-root}, run:mkdir -p "{project-root}/_bmad-output/.skf-run" && mktemp -d "{project-root}/_bmad-output/.skf-run/skf-update-skill-XXXXXXXX"Bind
{run_dir}← the path it prints and{run_id}← its folder name lessskf-update-skill-.If a helper is missing or the folder cannot be created, HALT: display "SKF cannot start this update: {the missing helper (re-install SKF), or the command's first stderr line}. Nothing was changed." Headless, when the emitter resolved, print the halt's line with no run folder, from
{project-root}:uv run {emitEnvelopeHelper} emit-halt --workflow skf-update-skill <<'SKF_JSON' {"status": "blocked", "phase": "on-activation:run-folder", "path": "{project-root}/_bmad-output/.skf-run", "reason": "<which helper is missing, or that stderr line>", "skill_name": "unknown", "version": "unknown", "previous_version": "unknown", "update_mode": "normal"} SKF_JSONResolve workflow customization. Bind
{resolveCustomizationHelper}←{project-root}/_bmad/skf/shared/scripts/skf-resolve-customization.py, else{project-root}/src/shared/scripts/skf-resolve-customization.py(the first that exists), and run:uv run {resolveCustomizationHelper} --skill {skill-root} --project-root {project-root} --key workflow --factsIt merges the bundled
{skill-root}/customize.tomlwith{project-root}/_bmad/custom/skf-update-skill.toml(team overrides, committed) and.user.toml(personal overrides, gitignored). When it exits non-zero, prints no JSON or is missing, print one line,[activation/warn] customization_resolver_unavailable: <reason>(<reason>: its first stderr line,SKF helper skf-resolve-customization.py not foundwhen the script is missing,no JSONwhen it printed none). If the resolver cannot run, read{skill-root}/customize.tomlalone and use its bundled defaults: the{project-root}/_bmad/custom/overrides do not apply to this run. Record the warning in the run log at once: writecustomization_resolver_unavailable: <reason>to{run_dir}/resolver-warning.txtwith a file write (a resolver error can hold quotes or$( ), so never echo it or type it into an argument), then runuv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning "$(cat "{run_dir}/resolver-warning.txt")"from{project-root}.Apply the resolved values so no surface is a silent no-op: execute each entry in
workflow.activation_steps_prependin order now; treat every entry inworkflow.persistent_factsas standing context for the whole run (the bundled default loads everyproject-context.mdunder{project-root}, none in{project-root}/_bmad-output/.skf-run/; if the resolver ran,--factshas applied each!entry, which drops each earlier entry it names, and expanded each glob, so afile:entry names one file); resolve{onCompleteCommand}←workflow.on_completeif non-empty, else empty string, and stash it in workflow context (references/report.md§5b runs it after a finished run's result files, never in--detect-only,--dry-runor a halt; empty = no-op). Then, before step 5 loadsreferences/init.md, execute each entry inworkflow.activation_steps_appendin order.Load, read the full file, and then execute
references/init.mdto begin the workflow.
Files (bmad-module-skill-forge)
-
references
-
body-split.md 3.8 KB
Loading… -
detect-changes.md 35.1 KB
Loading… -
gap-driven.md 27 KB
Loading… -
gap-spot-check.md 30.3 KB
Loading… -
health-check.md 3.9 KB
Loading… -
init.md 29.6 KB
Loading… -
invocation-contract.md 5.3 KB
Loading… -
load-baseline.md 31.3 KB
Loading… -
merge-write.md 24.3 KB
Loading… -
merge.md 25.9 KB
Loading… -
re-extract.md 16.5 KB
Loading… -
reconcile-scope.md 20.1 KB
Loading… -
report.md 30.6 KB
Loading… -
verify-publish.md 33.8 KB
Loading… -
write-metadata.md 17.8 KB
Loading… -
write.md 32.4 KB
Loading…
-
-
scripts
-
skf-new-file-diff.py 12.4 KB
Loading…
-
-
customize.toml 3 KB
Loading… -
SKILL.md 9.9 KB
--- name: skf-update-skill description: Smart regeneration preserving [MANUAL] sections after source changes. Use when the user requests to "update a skill" or "regenerate a skill." --- # Update Skill ## Overview Surgically updates existing skills when source code changes, preserving all [MANUAL] developer content while re-extracting only affected exports with full provenance tracking; unchanged content is never touched, and each regenerated instruction cites code by file:line (a docs-only skill cites its documents' URLs). Stack skills (`skill_type: "stack"` in metadata.json) are not updated here: this workflow redirects them to `skf-create-stack-skill`, which re-composes them from updated constituents. ## Conventions - Bare paths (e.g. `references/<name>.md`) resolve from the skill root, inside a `references/` file too: only a stage's frontmatter `nextStepFile`, `gapDrivenStepFile`, `noChangeReportFile` and `reportFile` name a file beside it. - **Module-level path exception:** bare paths beginning with `knowledge/` or `shared/` resolve from the SKF module root (`{project-root}/_bmad/skf/` installed, `src/` in dev), not the skill root; stage files reference `knowledge/version-paths.md` and `knowledge/tool-resolution.md`, and the terminal step chains to `shared/health-check.md`. - **Sibling skills:** a path that names another SKF skill's folder (`skf-<name>/...`) resolves from the SKF module root, and that skill must be installed with this one. - `references/` holds the workflow stages, chained by each file's frontmatter `nextStepFile` (load-baseline.md §8 loads `gap-driven.md` through `gapDrivenStepFile` instead when `update_mode` is `gap-driven`), the invocation contract, and two sub-references a stage loads in place: `write-metadata.md` (write.md §3b) and `body-split.md` (verify-publish.md §7); `scripts/` holds this skill's own helper. - `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives, if present). - `{project-root}`-prefixed paths resolve from the project working directory. - `{skill-name}` resolves to the skill directory's basename. - **Cross-skill data coupling:** stages load extraction rules and templates from `skf-create-skill`, each named in the stage's frontmatter or where the stage reads it, so create and update extract alike. ## Role You are a precision code analyst operating in Ferris Surgeon mode. This is a surgical operation, not an exploratory session. You bring AST-backed structural analysis and provenance-driven change detection expertise, while the source code provides the ground truth. ## Workflow Rules These rules apply to every step in this workflow: - Never hallucinate: every statement cites where it was read (an ast-grep match, a source line read by eye, or a docs URL), with that method's confidence label - [MANUAL] sections survive regeneration with zero content loss - Only load one step file at a time — never preload future steps - Run every subagent in the foreground, passing `run_in_background: false` on every Agent call (Claude Code runs a subagent in the background when the flag is left out), with parallel ones as several such calls in one message, and wait for every long-running command to exit before the next instruction; in a headless run, never end a turn while either still runs, since under `claude -p` a run stops when its turn ends. - Always communicate in `{communication_language}` - If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision - Every HALT, ABORT or other exit before step 7 runs the **Halt procedure** of the step file it fires in: one `{runStateHelper}` `halt` call that undoes this run's writes, removes the private source tree, releases the run lock and, headless, prints the halt's line. A halt never falls through to step 6. - While `{source_tree}` is bound, a step that finds `{source_root}` missing HALTs with status `blocked` (`error.phase` `<step>:source-tree-missing`) instead of reading its files as deleted. - **Run log.** Warnings and gate decisions live in the run folder, never only in context: a step records each warning the moment it raises it, and each gate its decision, with the `record` call that step names. - **Run context.** A binding lost from context is read back from `{run_dir}/run-context.json`. ## Stages | # | Step | File | Auto-proceed | |---|------|------|--------------| | 1 | Initialize | references/init.md | Yes | | 1b | Load the Baseline | references/load-baseline.md | No (confirm) | | 2a | Reconcile the Brief's Scope | references/reconcile-scope.md | Conditional (§1b and §1c ask when triggered) | | 2 | Detect Changes | references/detect-changes.md | Conditional (§2.2 asks when triggered) | | 2g | Gap-Driven Repair (only when `update_mode` is gap-driven: with 3g, in place of steps 2a to 3) | references/gap-driven.md | Conditional (§1 rule R1 asks [D]/[R] when a gap's remediation names removal) | | 3g | Gap Spot-Check | references/gap-spot-check.md | Yes | | 3 | Re-Extract | references/re-extract.md | Yes | | 4 | Merge | references/merge.md | Conditional (§4 asks on a [MANUAL] conflict) | | 4b | Write the Merged Files | references/merge-write.md | Yes | | 5 | Write | references/write.md | Yes | | 5b | Verify and Publish | references/verify-publish.md | Yes | | 6 | Report | references/report.md | Yes | | 7 | Workflow Health Check | references/health-check.md | Yes | ## Invocation Contract Headless callers: the inputs, flags, gate map, outputs and the `SKF_UPDATE_RESULT_JSON` line live in `references/invocation-contract.md`. Interactive runs do not need it. ## On Activation 1. Load config from `{project-root}/_bmad/skf/config.yaml` and resolve: - `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language` - `skills_output_folder`, `forge_data_folder`, `sidecar_path` 2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in `{sidecar_path}/preferences.yaml`. Default: false. Bind `{requested_skill}` ← the skill name or folder path the invocation passes (its argument that is neither a flag nor a flag's value), else empty: `references/init.md` §1 takes it as the skill without asking. 3. **Resolve the shared helpers and create the run folder**, before anything can halt. Resolve `{emitEnvelopeHelper}` ← the first that exists of `{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py` and `{project-root}/src/shared/scripts/skf-emit-result-envelope.py`. Resolve `{runStateHelper}` ← the first that exists of `{project-root}/_bmad/skf/shared/scripts/skf-update-run-state.py` and `{project-root}/src/shared/scripts/skf-update-run-state.py`. Then, from `{project-root}`, run: ```bash mkdir -p "{project-root}/_bmad-output/.skf-run" && mktemp -d "{project-root}/_bmad-output/.skf-run/skf-update-skill-XXXXXXXX" ``` Bind `{run_dir}` ← the path it prints and `{run_id}` ← its folder name less `skf-update-skill-`. If a helper is missing or the folder cannot be created, HALT: display "**SKF cannot start this update:** {the missing helper (re-install SKF), or the command's first stderr line}. Nothing was changed." Headless, when the emitter resolved, print the halt's line with no run folder, from `{project-root}`: ```bash uv run {emitEnvelopeHelper} emit-halt --workflow skf-update-skill <<'SKF_JSON' {"status": "blocked", "phase": "on-activation:run-folder", "path": "{project-root}/_bmad-output/.skf-run", "reason": "<which helper is missing, or that stderr line>", "skill_name": "unknown", "version": "unknown", "previous_version": "unknown", "update_mode": "normal"} SKF_JSON ``` 4. **Resolve workflow customization.** Bind `{resolveCustomizationHelper}` ← `{project-root}/_bmad/skf/shared/scripts/skf-resolve-customization.py`, else `{project-root}/src/shared/scripts/skf-resolve-customization.py` (the first that exists), and run: ```bash uv run {resolveCustomizationHelper} --skill {skill-root} --project-root {project-root} --key workflow --facts ``` It merges the bundled `{skill-root}/customize.toml` with `{project-root}/_bmad/custom/skf-update-skill.toml` (team overrides, committed) and `.user.toml` (personal overrides, gitignored). When it exits non-zero, prints no JSON or is missing, print one line, `[activation/warn] customization_resolver_unavailable: <reason>` (`<reason>`: its first stderr line, `SKF helper skf-resolve-customization.py not found` when the script is missing, `no JSON` when it printed none). If the resolver cannot run, read `{skill-root}/customize.toml` alone and use its bundled defaults: the `{project-root}/_bmad/custom/` overrides do not apply to this run. Record the warning in the run log at once: write `customization_resolver_unavailable: <reason>` to `{run_dir}/resolver-warning.txt` with a file write (a resolver error can hold quotes or `$( )`, so never echo it or type it into an argument), then run `uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning "$(cat "{run_dir}/resolver-warning.txt")"` from `{project-root}`. Apply the resolved values so no surface is a silent no-op: execute each entry in `workflow.activation_steps_prepend` in order now; treat every entry in `workflow.persistent_facts` as standing context for the whole run (the bundled default loads every `project-context.md` under `{project-root}`, none in `{project-root}/_bmad-output/.skf-run/`; if the resolver ran, `--facts` has applied each `!` entry, which drops each earlier entry it names, and expanded each glob, so a `file:` entry names one file); resolve `{onCompleteCommand}` ← `workflow.on_complete` if non-empty, else empty string, and stash it in workflow context (`references/report.md` §5b runs it after a finished run's result files, never in `--detect-only`, `--dry-run` or a halt; empty = no-op). Then, before step 5 loads `references/init.md`, execute each entry in `workflow.activation_steps_append` in order. 5. Load, read the full file, and then execute `references/init.md` to begin the workflow.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.