skf-analyze-source
Discover what to skill in a large repo and produce recommended skill briefs. Use when the user requests to "analyze source for skills" or "discover skill opportunities."
Install
npx skills add https://github.com/armelhbobdad/bmad-module-skill-forge/tree/main/src/skf-analyze-source
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
Analyze Source
Overview
Analyzes a large repo or multi-service project to identify discrete skillable units, map exports and integration points, and produce recommended skill-brief.yaml files as the primary entry point for brownfield onboarding. The analysis must be thorough enough to produce actionable briefs, but scoped enough to avoid overwhelming the user with false positives.
Conventions
- Bare paths (e.g.
references/<name>.md) resolve from the skill root, inside areferences/file too: only a stage's frontmatternextStepFile,continueFileandnextStepOptionsname 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; e.g.shared/health-check.md, which the terminal step chains to. - 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. {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.
Role
You are a source code analyst and decomposition architect collaborating with a developer onboarding an existing project, pairing your codebase-analysis and skill-scoping expertise with their domain knowledge.
Workflow Rules
These rules apply to every step in this workflow:
- 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}; the text persisted intoskill-brief.yaml(each recommendation'sdescriptionandscope.notes) is written in{document_output_language} - If
{headless_mode}is true, auto-proceed through confirmation gates with their default action, and record each one in the run sink as the gate says
Stages
| # | Step | File | Auto-proceed | Condition |
|---|---|---|---|---|
| 1 | Initialize | references/init.md | Yes | Always |
| 1a | Auto-Scope | references/step-auto-scope.md | Conditional (the coexistence gate) | [auto] mode only: bypasses steps 2–6; owns pin resolution, coexistence detection, and the docs-only short-circuit |
| 1b | Continue (session resume) | references/continue.md | Yes | An unfinished step-by-step report (mode not 'auto') of the same target and inputs, run again without [auto] (init section 1) |
| 2 | Scan Project | references/scan-project.md | No (confirm) | Interactive mode only |
| 3 | Identify Units | references/identify-units.md | No (confirm) | Interactive mode only |
| 4 | Map & Detect | references/map-and-detect.md | No (confirm) | Interactive mode only |
| 5 | Recommend | references/recommend.md | No (confirm) | Interactive mode only |
| 6 | Generate Briefs | references/generate-briefs.md | No (confirm) | Interactive mode only |
| 7 | Workflow Health Check | references/health-check.md | Yes | Always |
Auto mode path: With [auto] present, init routes directly to step 1a, which loads a branch file only when its branch fires: references/step-auto-scope-coexistence.md (a skill already matches), references/step-auto-scope-split.md (a monorepo splits into N briefs) and references/step-auto-scope-corpora.md (a whole-language reference), and routes docs-only targets to references/auto-docs-only.md.
[D] Discover Additional Source (steps 4 and 5) loads references/discover-additional-source.md. Step 2 and [D] make each project path's scan root by references/scan-root.md (steps 3, 4 and 6 make one again when a resumed session no longer finds it), and step 4 and [D] map each unit's exports by references/map-unit-exports.md.
Invocation Contract
Headless callers: the inputs, flags, gates, outputs and exit codes live in references/invocation-contract.md. Interactive runs do not need it.
On Activation
Resolve the envelope helper.
{emitEnvelopeHelper}← the first existing path of{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.pyand{project-root}/src/shared/scripts/skf-emit-result-envelope.py. If neither path exists, HARD HALT (exit code 3,halt_reason: "resolution-failure", phaseon-activation:helpers) and display only: "skf-emit-result-envelope.pyis missing. Nothing was changed. Re-install SKF." In headless mode every other HARD HALT prints its envelope on stderr through the emitter: with the first command below once step 5 has created{run_dir}, before that with the second, the payload on one line.references/headless-contract.md(Halt Envelope) gives the payload rules, and each step file restates them in its opening.uv run {emitEnvelopeHelper} emit-halt --workflow skf-analyze-source --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json" uv run {emitEnvelopeHelper} emit-halt --workflow skf-analyze-source --target stderr <<'SKF_ANALYZE_HALT' {"phase": "on-activation:config", "reason": "<the halt message>", "halt_reason": "input-missing", "mode": "interactive"} SKF_ANALYZE_HALTLoad config from
{project-root}/_bmad/skf/config.yamland resolve:project_name,output_folder,user_name,communication_language,document_output_language,forge_data_folder,skills_output_folder,sidecar_path- If the config cannot be loaded, HARD HALT (exit code 2,
halt_reason: "input-missing", phaseon-activation:config): "SKF cannot load{project-root}/_bmad/skf/config.yaml: the workflow has no forge context to run against. Run setup first." When--headlessor-Hwas passed, print its envelope with the second command above.
Resolve
{headless_mode}: true if--headlessor-Hwas passed as an argument, or ifheadless_mode: truein{sidecar_path}/preferences.yaml. Default: false.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 --factsIt merges the bundled
{skill-root}/customize.tomlwith{project-root}/_bmad/custom/skf-analyze-source.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. In that case keep the reason as{customization_resolver_unavailable}(unset when the resolver ran) for step 5 to record in the run sink.Then bind, so stage files use the variable with no conditional at the usage site:
{analysisReportTemplatePath}←workflow.analysis_report_template_path(the bundledtemplates/analysis-report-template.mdwhen an override leaves it empty){onCompleteCommand}←workflow.on_complete(empty: no hook)
Run
workflow.activation_steps_prependnow, and treatworkflow.persistent_factsas standing context for the 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).Create the run folder. It holds what the run stages for its helpers (the tree listing, each brief's context, the unit records, the halt and result payloads) and the sink of its auto-decisions:
mkdir -p "{project-root}/_bmad-output/.skf-run" && mktemp -d "{project-root}/_bmad-output/.skf-run/skf-analyze-source-XXXXXXXX"Bind
{run_dir}← the path it prints. The step that ends the run deletes it once the envelope is out; a HARD HALT keeps it. If it cannot be created, HARD HALT (exit code 4,halt_reason: "write-failed", phaseon-activation:run-folder, path{project-root}/_bmad-output/.skf-run): "SKF cannot create its run folder under{project-root}/_bmad-output/.skf-run/: . Nothing was changed." Its envelope goes through the second command of step 1, its payload with"customization_resolver_unavailable": "<reason>"added when step 4 kept one. Once the folder exists and{customization_resolver_unavailable}is set, record the reason in the run sink: writecustomization_resolver_unavailable: {customization_resolver_unavailable}to{run_dir}/resolver-warning.txtwith a file write, neverecho(the reason can hold quotes or$( )), then runuv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning "$(cat "{run_dir}/resolver-warning.txt")".Run
workflow.activation_steps_append, then load, read the full file, and executereferences/init.mdto begin the workflow.
Files (bmad-module-skill-forge)
-
assets
-
skill-brief-schema.md 7.4 KB
Loading…
-
-
references
-
auto-docs-only.md 8.7 KB
Loading… -
continue.md 3.3 KB
Loading… -
discover-additional-source.md 12.7 KB
Loading… -
generate-briefs.md 18.9 KB
Loading… -
headless-contract.md 11.5 KB
Loading… -
health-check.md 946 B
Loading… -
identify-units.md 16.7 KB
Loading… -
init.md 15.1 KB
Loading… -
invocation-contract.md 2.5 KB
Loading… -
map-and-detect.md 15.9 KB
Loading… -
map-unit-exports.md 7.4 KB
Loading… -
recommend.md 9.4 KB
Loading… -
scan-project.md 8.3 KB
Loading… -
scan-root.md 3.3 KB
Loading… -
step-auto-scope-coexistence.md 3.6 KB
Loading… -
step-auto-scope-corpora.md 4.3 KB
Loading… -
step-auto-scope-split.md 8.3 KB
Loading… -
step-auto-scope.md 32.4 KB
Loading… -
step-shape-detect.md 2.5 KB
Loading… -
unit-detection-heuristics.md 12.1 KB
Loading…
-
-
templates
-
analysis-report-template.md 595 B
Loading…
-
-
customize.toml 3.2 KB
Loading… -
SKILL.md 9.7 KB
--- name: skf-analyze-source description: Discover what to skill in a large repo and produce recommended skill briefs. Use when the user requests to "analyze source for skills" or "discover skill opportunities." --- # Analyze Source ## Overview Analyzes a large repo or multi-service project to identify discrete skillable units, map exports and integration points, and produce recommended skill-brief.yaml files as the primary entry point for brownfield onboarding. The analysis must be thorough enough to produce actionable briefs, but scoped enough to avoid overwhelming the user with false positives. ## Conventions - Bare paths (e.g. `references/<name>.md`) resolve from the skill root, inside a `references/` file too: only a stage's frontmatter `nextStepFile`, `continueFile` and `nextStepOptions` 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; e.g. `shared/health-check.md`, which the terminal step chains to. - **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. - `{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. ## Role You are a source code analyst and decomposition architect collaborating with a developer onboarding an existing project, pairing your codebase-analysis and skill-scoping expertise with their domain knowledge. ## Workflow Rules These rules apply to every step in this workflow: - 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}`; the text persisted into `skill-brief.yaml` (each recommendation's `description` and `scope.notes`) is written in `{document_output_language}` - If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action, and record each one in the run sink as the gate says ## Stages | # | Step | File | Auto-proceed | Condition | |---|------|------|--------------|-----------| | 1 | Initialize | references/init.md | Yes | Always | | 1a | Auto-Scope | references/step-auto-scope.md | Conditional (the coexistence gate) | `[auto]` mode only: bypasses steps 2–6; owns pin resolution, coexistence detection, and the docs-only short-circuit | | 1b | Continue (session resume) | references/continue.md | Yes | An unfinished step-by-step report (`mode` not `'auto'`) of the same target and inputs, run again without `[auto]` (init section 1) | | 2 | Scan Project | references/scan-project.md | No (confirm) | Interactive mode only | | 3 | Identify Units | references/identify-units.md | No (confirm) | Interactive mode only | | 4 | Map & Detect | references/map-and-detect.md | No (confirm) | Interactive mode only | | 5 | Recommend | references/recommend.md | No (confirm) | Interactive mode only | | 6 | Generate Briefs | references/generate-briefs.md | No (confirm) | Interactive mode only | | 7 | Workflow Health Check | references/health-check.md | Yes | Always | **Auto mode path:** With `[auto]` present, init routes directly to step 1a, which loads a branch file only when its branch fires: `references/step-auto-scope-coexistence.md` (a skill already matches), `references/step-auto-scope-split.md` (a monorepo splits into N briefs) and `references/step-auto-scope-corpora.md` (a whole-language reference), and routes docs-only targets to `references/auto-docs-only.md`. **[D] Discover Additional Source** (steps 4 and 5) loads `references/discover-additional-source.md`. Step 2 and [D] make each project path's scan root by `references/scan-root.md` (steps 3, 4 and 6 make one again when a resumed session no longer finds it), and step 4 and [D] map each unit's exports by `references/map-unit-exports.md`. ## Invocation Contract Headless callers: the inputs, flags, gates, outputs and exit codes live in `references/invocation-contract.md`. Interactive runs do not need it. ## On Activation 1. **Resolve the envelope helper.** `{emitEnvelopeHelper}` ← the first existing path of `{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py` and `{project-root}/src/shared/scripts/skf-emit-result-envelope.py`. If neither path exists, HARD HALT (exit code 3, `halt_reason: "resolution-failure"`, phase `on-activation:helpers`) and display only: "`skf-emit-result-envelope.py` is missing. Nothing was changed. Re-install SKF." In headless mode every other HARD HALT prints its envelope on stderr through the emitter: with the first command below once step 5 has created `{run_dir}`, before that with the second, the payload on one line. `references/headless-contract.md` (Halt Envelope) gives the payload rules, and each step file restates them in its opening. ```bash uv run {emitEnvelopeHelper} emit-halt --workflow skf-analyze-source --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json" uv run {emitEnvelopeHelper} emit-halt --workflow skf-analyze-source --target stderr <<'SKF_ANALYZE_HALT' {"phase": "on-activation:config", "reason": "<the halt message>", "halt_reason": "input-missing", "mode": "interactive"} SKF_ANALYZE_HALT ``` 2. Load config from `{project-root}/_bmad/skf/config.yaml` and resolve: - `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`, `forge_data_folder`, `skills_output_folder`, `sidecar_path` - If the config cannot be loaded, HARD HALT (exit code 2, `halt_reason: "input-missing"`, phase `on-activation:config`): "SKF cannot load `{project-root}/_bmad/skf/config.yaml`: the workflow has no forge context to run against. Run setup first." When `--headless` or `-H` was passed, print its envelope with the second command above. 3. **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. 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-analyze-source.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. In that case keep the reason as `{customization_resolver_unavailable}` (unset when the resolver ran) for step 5 to record in the run sink. Then bind, so stage files use the variable with no conditional at the usage site: - `{analysisReportTemplatePath}` ← `workflow.analysis_report_template_path` (the bundled `templates/analysis-report-template.md` when an override leaves it empty) - `{onCompleteCommand}` ← `workflow.on_complete` (empty: no hook) Run `workflow.activation_steps_prepend` now, and treat `workflow.persistent_facts` as standing context for the 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). 5. **Create the run folder.** It holds what the run stages for its helpers (the tree listing, each brief's context, the unit records, the halt and result payloads) and the sink of its auto-decisions: ```bash mkdir -p "{project-root}/_bmad-output/.skf-run" && mktemp -d "{project-root}/_bmad-output/.skf-run/skf-analyze-source-XXXXXXXX" ``` Bind `{run_dir}` ← the path it prints. The step that ends the run deletes it once the envelope is out; a HARD HALT keeps it. If it cannot be created, HARD HALT (exit code 4, `halt_reason: "write-failed"`, phase `on-activation:run-folder`, path `{project-root}/_bmad-output/.skf-run`): "SKF cannot create its run folder under `{project-root}/_bmad-output/.skf-run/`: {the first stderr line}. Nothing was changed." Its envelope goes through the second command of step 1, its payload with `"customization_resolver_unavailable": "<reason>"` added when step 4 kept one. Once the folder exists and `{customization_resolver_unavailable}` is set, record the reason in the run sink: write `customization_resolver_unavailable: {customization_resolver_unavailable}` to `{run_dir}/resolver-warning.txt` with a file write, never `echo` (the reason can hold quotes or `$( )`), then run `uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning "$(cat "{run_dir}/resolver-warning.txt")"`. 6. Run `workflow.activation_steps_append`, then load, read the full file, and execute `references/init.md` to begin the workflow.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.