Claude Skill

skf-update-skill

Smart regeneration preserving [MANUAL] sections after source changes. Use when the user requests to "update a skill" or "regenerate a skill."

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download armelhbobdad-bmad-module-skill-forge-src_skf-update-skill-484edd0.zip · 134 KB

Install

skills CLI npx skills add https://github.com/armelhbobdad/bmad-module-skill-forge/tree/main/src/skf-update-skill
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install armelhbobdad-bmad-module-skill-forge@llmmart
Git 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 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:

    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}:

    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:

    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.

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.

No comments yet.

Reviews (0)

No reviews yet.