skf-brief-skill
starsforks
How to install skf-brief-skill?
armelhbobdad/bmad-module-skill-forge/skf-brief-skill
$npx -y skills add armelhbobdad/bmad-module-skill-forge --skill skf-brief-skillDesign a skill scope through guided discovery. Use when the user requests to "create a skill brief" or "brief a skill".
SKILL.md
| 1 | # Brief Skill |
| 2 | |
| 3 | ## Overview |
| 4 | |
| 5 | 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. |
| 6 | |
| 7 | A good skill brief sets a tight, cohesive boundary: one capability with 3-8 primary functions, an unambiguous public API surface, and a description short enough to fit in a registry row. Briefs that try to cover several unrelated concerns (e.g. authentication *and* data visualization) compile into skills that no agent can route to confidently — a brief covering too much is a worse failure mode than a brief covering too little, and this workflow steers toward the smaller, sharper version when scope is unclear. Scope on cheap signals — manifests, top-level exports, intent — not full AST extraction. |
| 8 | |
| 9 | **Ratify path.** A pre-authored `skill-brief.yaml` (typically from `skf-analyze-source`'s `generate-briefs` step) can be *ratified* — reviewed and rewritten in place — instead of re-derived from scratch. Interactively, pass its path at the first prompt; headlessly, pass `from_brief <path>`. See the `from_brief` Inputs cell in `references/invocation-contract.md` for the full ratify contract. |
| 10 | |
| 11 | ## Conventions |
| 12 | |
| 13 | - Bare paths (e.g. `references/<name>.md`) resolve from the skill root. |
| 14 | - `references/` holds prompt content carved out of SKILL.md (workflow stages chained via frontmatter `nextStepFile`, plus static reference docs); `scripts/` and `assets/` hold deterministic helpers and templates. |
| 15 | - `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives, if present). |
| 16 | - `{project-root}`-prefixed paths resolve from the project working directory. |
| 17 | - `{skill-name}` resolves to the skill directory's basename. |
| 18 | |
| 19 | ## Role |
| 20 | |
| 21 | 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. |
| 22 | |
| 23 | ## Workflow Rules |
| 24 | |
| 25 | These rules apply to every step in this workflow: |
| 26 | |
| 27 | - Only load one step file at a time — never preload future steps |
| 28 | - **Lazy-load references and assets:** `references/*.md` and `assets/*.md` files are loaded inside the section that needs them, not at step entry. If a section is skipped (e.g. `version-resolution.md` when `{extractPublicApiHelper}` already returned a version, `scope-templates.md` for the `docs-only` branch that bypasses §2c), do not load that file. Each unnecessary load costs context (~5-10 KB per reference) and biases the LLM toward consulting material the current path does not need. |
| 29 | - 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. |
| 30 | - If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision |
| 31 | |
| 32 | ## On Activation |
| 33 | |
| 34 | 1. Load config from `{project-root}/_bmad/skf/config.yaml` and resolve: |
| 35 | - `project_name`, `output_folder`, `user_name`, `communication_language`, `forge_data_folder`, `sidecar_path` |
| 36 | |
| 37 | 2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in preferences.yaml. Default: false. |
| 38 | |
| 39 | 3. **Resolve workflow customization.** Run: |
| 40 | |
| 41 | ```bash |
| 42 | python3 {project-root}/_bmad/scripts/resolve_customization.py \ |
| 43 | --skill {skill-root} --key workflow |
| 44 | ``` |
| 45 | |
| 46 | The script merges the three customization layers per `bmad-customize`'s structural merge rules (scalars override, arrays append): |
| 47 | |
| 48 | - `{skill-root}/customize.toml` — bundled defaults |
| 49 | - `_bmad/custom/<skill-name>.toml` under `{project-root}` — team overrides (committed) |
| 50 | - `_bmad/custom/<skill-name>.user.toml` under `{project-root}` — personal overrides (gitignored) |
| 51 | |
| 52 | If the script fails or is missing, fall back to reading `{skill-root}/customize.toml` directly — the bundled defaults are an empty string for each path scalar. |
| 53 | |
| 54 | Apply the path-scalar fallback now so stage files don't have to repeat the conditional logic. For each of the three scalars, if the merged value is empty or absent, use the bundled default: |
| 55 | |
| 56 | - `{descriptionVoiceExamplesPath}` ← `workflow.description_voice_examples_path` if non-empty, else `assets/description-voice-examples.md` |
| 57 | - `{scopeTemplatesPath}` ← `workflow.scope_templates_path` if non-empty, else `assets/scope-templates.md` |
| 58 | - `{briefSchemaPath}` ← `workflow.brief_schem |
People who liked this also viewed
6 picksType
- find-skillsHelps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skSkillsJul 2026
- grill-meA relentless interview to sharpen a plan or design.SkillsJul 2026
- vercel-react-best-practicesVercel's official collection of agent skillsSkillsJul 2026
- improve-codebase-architectureScan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.SkillsJul 2026
- setup-matt-pocock-skillsConfigure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.SkillsJul 2026
- triageMove issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs.SkillsJul 2026
