skf-brief-skill
Design a skill scope through guided discovery. Use when the user requests to "create a skill brief" or "brief a skill".
Install
npx skills add https://github.com/armelhbobdad/bmad-module-skill-forge/tree/main/src/skf-brief-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
Brief Skill
Overview
Helps the user define what to skill — target repo, scope, language, inclusion/exclusion patterns — and produces a skill-brief.yaml that drives create-skill. This is the first step in the skill creation pipeline; the brief is the input contract for create-skill, which performs the actual compilation.
A good brief is tight: one capability with 3-8 primary functions, a clear public API and a description that fits a registry row. A brief spanning unrelated concerns (authentication and data visualization) compiles into a skill agents cannot route to, worse than one too narrow, so lean small when scope is unclear. Scope on cheap signals (manifests, top-level exports, intent), not full AST extraction, with one exception: at Forge tier and above, step 3 runs create-skill's recipe runner only to pin a file list a glob cannot express (scope.tier_a_include and the headless public-api include).
A pre-authored brief can be ratified instead: reviewed and written to {forge_data_folder}/{name}/skill-brief.yaml (in place when it already lives there).
Conventions
- Bare paths (e.g.
references/<name>.md) resolve from the skill root, inside areferences/file too: only a stage's frontmatternextStepFile,reviseStepFile,analyzeStepFileandratifyTargetFilename 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.knowledge/tool-resolution.mdandshared/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. {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}is the brief's approvedname, never this skill's folder name.
Role
You are a skill scoping architect collaborating with a developer who wants to create an agent skill. You bring expertise in source code analysis, API surface identification, and skill boundary design, while the user brings their domain knowledge and specific use case. Work together as equals.
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. - Lazy-load: load a
references/*.mdorassets/*.mdfile in the section that needs it, never at step entry, and not at all when that section is skipped. - Always communicate in
{communication_language}(the language for user-facing prose). Written artifact text — thedescription,notes, and other free-form fields persisted intoskill-brief.yaml— is in{document_output_language}; per-step rules call this out where it applies (see step 5). The two values may be the same. - If
{headless_mode}is true, auto-proceed through confirmation gates with their default action and log each auto-decision - Record each warning the moment it is raised, each
warn:line a step logs included:uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning "<text>", or--warnings-fileon a helper's saved JSON. Text that quotes a helper or the user goes through a file: write it to{run_dir}/warning.txt, then pass--warning "$(cat "{run_dir}/warning.txt")".
Halt Contract
Every HALT that names a halt_reason, except an interactive [X] cancel, runs uv run {emitEnvelopeHelper} emit-halt --workflow skf-brief-skill --run-dir "{run_dir}" --target stderr --halt-reason <halt_reason> where it stops and displays the line it prints; references/invocation-contract.md (Result Contract) says what the emitter fills in and what a halt shows without a line. A HALT that names no halt_reason, such as a helper with no installed path (an install fault: re-install SKF), emits nothing in any mode.
On Activation
Load config from
{project-root}/_bmad/skf/config.yamland resolve:project_name,output_folder,user_name,communication_language,document_output_language,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.Resolve
{auto_mode}: true when the invocation carries the[auto]flag (a pipeline'sBS[auto], which step 0 §1b routes to the auto stages), else 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-brief-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. In that case keep the reason as{customization_resolver_unavailable}for preflight.md §1 to record once it has created{run_dir}.Bind the values the stage files use, taking the bundled default when the merged value is empty or absent:
{descriptionVoiceExamplesPath}←workflow.description_voice_examples_path, elseassets/description-voice-examples.md{scopeTemplatesPath}←workflow.scope_templates_path, elseassets/scope-templates.md{onCompleteCommand}←workflow.on_complete, else empty: no hook, so write-brief.md §6b and step-auto-validate.md §3, the two places it runs, skip it
Also apply the array surfaces so they are not silent no-ops: 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); then, after activation completes and before step 5 loads the first stage, execute each entry inworkflow.activation_steps_appendin order.Resolve the envelope emitter before any stage can halt:
{emitEnvelopeHelper}←{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py, else{project-root}/src/shared/scripts/skf-emit-result-envelope.py, the first that exists (no path when neither does). It prints everySKF_BRIEF_RESULT_JSONline, whichreferences/invocation-contract.mddefines.Load, read the full file, and execute
references/preflight.md.
Stages
| # | Step | File | Auto-proceed |
|---|---|---|---|
| 0 | Preflight (every run) | references/preflight.md | Yes |
| 1 | Gather Intent | references/gather-intent.md | No (interactive) |
| 1h | Headless Input Gate (headless only) | references/headless-args.md | Yes |
| 1r | Ratify an Existing Brief (ratify only) | references/gather-intent-ratify.md | No (interactive menu; headless takes [R]) |
| 1a | Auto-Brief Generation (auto mode only) | references/step-auto-brief.md | Yes |
| 1b | Auto-Brief Validation (auto mode only) | references/step-auto-validate.md | Yes |
| 2 | Analyze Target | references/analyze-target.md | Conditional (a truncated tree, a monorepo) |
| 3 | Scope Definition | references/scope-definition.md | No (interactive) |
| 4 | Confirm Brief | references/confirm-brief.md | No (confirm) |
| 5 | Write Brief | references/write-brief.md | Conditional (the brief exists) |
| 6 | Workflow Health Check (terminal) | references/health-check.md | Yes |
Every run starts in preflight.md (run folder, forge tier), which routes by mode. [auto] (a pipeline's BS[auto]): step-auto-brief.md → step-auto-validate.md → health-check.md, in place of stages 1-5; at Deep tier step-auto-validate.md loads stage 5's QMD registration file. It stays a separate route by design: the forge-auto pipeline contract gives it doc enrichment (step-auto-brief.md §2-§3), which the ratify and derive routes do not run, and an envelope with mode: "auto". Headless: headless-args.md validates the arguments before any stage uses them, then continues at stage 2. Interactive: gather-intent.md. A brief to ratify (a brief path when invoking the skill or at the first prompt, step 1's [U] Revise, or a headless from_brief) goes through gather-intent-ratify.md straight to stage 4, skipping stages 2 and 3.
Invocation Contract
Headless callers: the full argument set (Inputs), gate map, exit-code table, and SKF_BRIEF_RESULT_JSON result envelope live in references/invocation-contract.md. Interactive runs do not need it.
Files (bmad-module-skill-forge)
-
assets
-
description-voice-examples.md 2.1 KB
Loading… -
scope-templates.md 6.4 KB
Loading… -
skill-brief-schema.md 22.9 KB
Loading…
-
-
references
-
analyze-target.md 30.1 KB
Loading… -
confirm-brief.md 7.7 KB
Loading… -
draft-checkpoint.md 6.3 KB
Loading… -
gather-intent-ratify.md 6.2 KB
Loading… -
gather-intent.md 23.3 KB
Loading… -
headless-args.md 11.3 KB
Loading… -
headless-boundary-defaults.md 4 KB
Loading… -
health-check.md 884 B
Loading… -
invocation-contract.md 9.9 KB
Loading… -
portfolio-similarity-check.md 2.7 KB
Loading… -
preflight.md 7.6 KB
Loading… -
qmd-collection-registration.md 3.9 KB
Loading… -
scope-definition.md 21.1 KB
Loading… -
step-auto-brief.md 9.3 KB
Loading… -
step-auto-validate.md 5.8 KB
Loading… -
tier-a-surface.md 5.1 KB
Loading… -
version-resolution.md 2.1 KB
Loading… -
write-brief.md 15.3 KB
Loading…
-
-
customize.toml 4.2 KB
Loading… -
SKILL.md 9.8 KB
--- name: skf-brief-skill description: Design a skill scope through guided discovery. Use when the user requests to "create a skill brief" or "brief a skill". --- # Brief Skill ## Overview Helps the user define what to skill — target repo, scope, language, inclusion/exclusion patterns — and produces a `skill-brief.yaml` that drives create-skill. This is the first step in the skill creation pipeline; the brief is the input contract for create-skill, which performs the actual compilation. A good brief is tight: one capability with 3-8 primary functions, a clear public API and a description that fits a registry row. A brief spanning unrelated concerns (authentication *and* data visualization) compiles into a skill agents cannot route to, worse than one too narrow, so lean small when scope is unclear. Scope on cheap signals (manifests, top-level exports, intent), not full AST extraction, with one exception: at Forge tier and above, step 3 runs create-skill's recipe runner only to pin a file list a glob cannot express (`scope.tier_a_include` and the headless `public-api` include). A pre-authored brief can be ratified instead: reviewed and written to `{forge_data_folder}/{name}/skill-brief.yaml` (in place when it already lives there). ## Conventions - Bare paths (e.g. `references/<name>.md`) resolve from the skill root, inside a `references/` file too: only a stage's frontmatter `nextStepFile`, `reviseStepFile`, `analyzeStepFile` and `ratifyTargetFile` 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. `knowledge/tool-resolution.md` and `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. - `{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}` is the brief's approved `name`, never this skill's folder name. ## Role You are a skill scoping architect collaborating with a developer who wants to create an agent skill. You bring expertise in source code analysis, API surface identification, and skill boundary design, while the user brings their domain knowledge and specific use case. Work together as equals. ## 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. - **Lazy-load:** load a `references/*.md` or `assets/*.md` file in the section that needs it, never at step entry, and not at all when that section is skipped. - Always communicate in `{communication_language}` (the language for user-facing prose). Written artifact text — the `description`, `notes`, and other free-form fields persisted into `skill-brief.yaml` — is in `{document_output_language}`; per-step rules call this out where it applies (see step 5). The two values may be the same. - If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision - Record each warning the moment it is raised, each `warn:` line a step logs included: `uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning "<text>"`, or `--warnings-file` on a helper's saved JSON. Text that quotes a helper or the user goes through a file: write it to `{run_dir}/warning.txt`, then pass `--warning "$(cat "{run_dir}/warning.txt")"`. ## Halt Contract Every HALT that names a `halt_reason`, except an interactive `[X]` cancel, runs `uv run {emitEnvelopeHelper} emit-halt --workflow skf-brief-skill --run-dir "{run_dir}" --target stderr --halt-reason <halt_reason>` where it stops and displays the line it prints; `references/invocation-contract.md` (Result Contract) says what the emitter fills in and what a halt shows without a line. A HALT that names no `halt_reason`, such as a helper with no installed path (an install fault: re-install SKF), emits nothing in any mode. ## 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`, `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. **Resolve `{auto_mode}`**: true when the invocation carries the `[auto]` flag (a pipeline's `BS[auto]`, which step 0 §1b routes to the auto stages), else false. 3. **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-brief-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. In that case keep the reason as `{customization_resolver_unavailable}` for preflight.md §1 to record once it has created `{run_dir}`. Bind the values the stage files use, taking the bundled default when the merged value is empty or absent: - `{descriptionVoiceExamplesPath}` ← `workflow.description_voice_examples_path`, else `assets/description-voice-examples.md` - `{scopeTemplatesPath}` ← `workflow.scope_templates_path`, else `assets/scope-templates.md` - `{onCompleteCommand}` ← `workflow.on_complete`, else empty: no hook, so write-brief.md §6b and step-auto-validate.md §3, the two places it runs, skip it Also apply the array surfaces so they are not silent no-ops: 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); then, after activation completes and before step 5 loads the first stage, execute each entry in `workflow.activation_steps_append` in order. 4. **Resolve the envelope emitter** before any stage can halt: `{emitEnvelopeHelper}` ← `{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py`, else `{project-root}/src/shared/scripts/skf-emit-result-envelope.py`, the first that exists (no path when neither does). It prints every `SKF_BRIEF_RESULT_JSON` line, which `references/invocation-contract.md` defines. 5. Load, read the full file, and execute `references/preflight.md`. ## Stages | # | Step | File | Auto-proceed | |---|------|------|--------------| | 0 | Preflight (every run) | references/preflight.md | Yes | | 1 | Gather Intent | references/gather-intent.md | No (interactive) | | 1h | Headless Input Gate (headless only) | references/headless-args.md | Yes | | 1r | Ratify an Existing Brief (ratify only) | references/gather-intent-ratify.md | No (interactive menu; headless takes [R]) | | 1a | Auto-Brief Generation (auto mode only) | references/step-auto-brief.md | Yes | | 1b | Auto-Brief Validation (auto mode only) | references/step-auto-validate.md | Yes | | 2 | Analyze Target | references/analyze-target.md | Conditional (a truncated tree, a monorepo) | | 3 | Scope Definition | references/scope-definition.md | No (interactive) | | 4 | Confirm Brief | references/confirm-brief.md | No (confirm) | | 5 | Write Brief | references/write-brief.md | Conditional (the brief exists) | | 6 | Workflow Health Check (terminal) | references/health-check.md | Yes | Every run starts in preflight.md (run folder, forge tier), which routes by mode. `[auto]` (a pipeline's `BS[auto]`): step-auto-brief.md → step-auto-validate.md → health-check.md, in place of stages 1-5; at Deep tier step-auto-validate.md loads stage 5's QMD registration file. It stays a separate route by design: the forge-auto pipeline contract gives it doc enrichment (step-auto-brief.md §2-§3), which the ratify and derive routes do not run, and an envelope with `mode: "auto"`. Headless: headless-args.md validates the arguments before any stage uses them, then continues at stage 2. Interactive: gather-intent.md. A brief to ratify (a brief path when invoking the skill or at the first prompt, step 1's `[U] Revise`, or a headless `from_brief`) goes through gather-intent-ratify.md straight to stage 4, skipping stages 2 and 3. ## Invocation Contract Headless callers: the full argument set (`Inputs`), gate map, exit-code table, and `SKF_BRIEF_RESULT_JSON` result envelope live in `references/invocation-contract.md`. Interactive runs do not need it.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.