skf-create-skill
Skill7 starsChanged 8 days agoApache-2.0View on GitHub
Compile a skill from a brief. Supports --batch for multiple briefs. Use when the user requests to "create a skill" or "compile a skill.
In this repository38 other files it gives its agents.
- _skf-learn/agents.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- bmad-advanced-elicitationSkill
- bmad-brainstormingSkill
- bmad-cis-agent-brainstorming-coachSkill
- bmad-cis-agent-creative-problem-solverSkill
- bmad-cis-agent-design-thinking-coachSkill
- bmad-cis-agent-innovation-strategistSkill
- bmad-cis-agent-presentation-masterSkill
- bmad-cis-agent-storytellerSkill
- bmad-cis-design-thinkingSkill
- bmad-cis-innovation-strategySkill
- bmad-cis-problem-solvingSkill
- bmad-cis-storytellingSkill
- bmad-distillatorSkill
- bmad-editorial-review-proseSkill
- bmad-editorial-review-structureSkill
- bmad-helpSkill
- bmad-index-docsSkill
- bmad-party-modeSkill
- bmad-review-adversarial-generalSkill
- bmad-review-edge-case-hunterSkill
- bmad-shard-docSkill
- skf-analyze-sourceSkill
- skf-audit-skillSkill
- skf-brief-skillSkill
- skf-campaignSkill
- skf-create-stack-skillSkill
- skf-drop-skillSkill
- skf-export-skillSkill
- skf-forgerSkill
- skf-quick-skillSkill
- skf-refine-architectureSkill
- skf-rename-skillSkill
- skf-setupSkill
- skf-test-skillSkill
- skf-update-skillSkill
- skf-verify-stackSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 2 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 30
Never include content in SKILL.md without a provenance citation: [AST:] or [SRC:] for code (T1 and T1-low), [QMD:] for T2 context or [EXT:] …
- Distinctive: line 31
Never write into a skill folder SKF did not generate — generate-artifacts §1 runs the inventory's write check before creating any directory.
- Distinctive: line 32
Only load one step file at a time — never preload future steps
- Very specific: line 36
Always communicate in {communication_language}
- Very specific: line 37
If {headless_mode} is true, auto-proceed through confirmation gates with their default action
- Very specific: line 91
If --batch was given, load, read the full file, and then execute references/batch-mode.md: it validates every brief first, runs steps 1 to …
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Create Skill
Overview
Compiles a verified agent skill from a skill-brief.yaml and the source code or documentation it names, producing an agentskills.io-compliant SKILL.md with provenance map, evidence report, and progressive disclosure references. The workflow is mostly autonomous: it stops for the user in step 1 when no brief is named and several exist, in step 3 when several tags match the brief's version, for each authoritative AI documentation file the brief's scope leaves out (step 3 §2a), after source extraction (to confirm findings), at step 3c when a source brief extracted no export and none of its doc_urls could be fetched, and, for a component library, at step 3d's demo-exclusion and registry prompts. When the user has opted in to Tessl Review, step 6 also records Tessl's review of the skill as advice; it never stops the run. Steps adapt behavior based on forge tier (Quick/Forge/Forge+/Deep). Zero hallucination tolerance: every statement in the output carries a provenance citation, and content that cannot be cited is left out. A single run is not resumable: if it is interrupted mid-compile, re-run from the brief (only --batch checkpoints progress across briefs).
Conventions
- Bare paths (e.g.
references/<name>.md) resolve from the skill root. - 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. - 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 prompt content carved out of SKILL.md (workflow stages chained via frontmatternextStepFile, plus static reference docs) andreferences/sub/the conditional sub-steps; anextStepFileis relative to its own stage file (so a sub-step that returns to a main stage names it in the parent folder).scripts/andassets/hold deterministic helpers and templates.{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 operating in Ferris Architect mode: a skill compilation engine performing structural extraction and assembly.
Workflow Rules
These rules apply to every step in this workflow:
- Never include content in SKILL.md without a provenance citation:
[AST:]or[SRC:]for code (T1 and T1-low),[QMD:]for T2 context or[EXT:]for T3 documentation, in the formsassets/skill-sections.mdgives - Never write into a skill folder SKF did not generate — generate-artifacts §1 runs the inventory's write check before creating any directory; without the helper it writes only into a skill folder that does not exist yet
- 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. - Once step 3 §2b has bound
{source_tree}(the private tree a remote source is read from), every HALT after it first runsuv run {sourceTreeHelper} close --tree "{source_tree}"from{project-root}and goes on whatever it prints. Step 7 removes the tree on a run that finishes, and a later run removes one a stopped run left behind, seven days on - Every HARD HALT in steps 1 to 7 emits the result envelope before it stops, in every mode. Each HALT names its exit code,
halt_reasonand phase where it fires, and its emit command. Stage{"phase": "<phase>", "halt_reason": "<halt_reason>", "reason": "<the halt message, one line>", "summary": {"halt_reason": "<halt_reason>", "evidence_report": null}}as{run_dir}/halt.json(add"path"when the halt names a file or folder; once step 7 has promoted the package, add"skill_package"and"outputs"and setsummary.evidence_reportto{forge_version}/evidence-report.md), then runuv run {emitEnvelopeHelper} emit-halt --workflow skf-create-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json", adding--result-dir "{forge_version}"once step 7 has created{forge_version}, so the emitter also writes the halt'screate-skill-result-*.jsonand its-latest.jsoncopy there. Display the line it prints, then stop with the exit code; under--batchthe halt ends only its brief: go toreferences/batch-mode.md§3, which records it and takes the next brief. If{emitEnvelopeHelper}resolved no path, display the halt message alone. The schema,shared/scripts/schemas/skf-create-skill-result-envelope.v1.json, lists everyhalt_reasonwith its exit code - Always communicate in
{communication_language} - If
{headless_mode}is true, auto-proceed through confirmation gates with their default action - Every decision the run takes without asking (each gate a headless run resolves by its default, step 1's tier override and its pick of the only brief) is recorded the moment it is taken: stage
{"step": "<step>", "gate": "<gate>", "decision": "<action>", "rationale": "<why>", "timestamp": "<ISO-8601>"}, plus"value"or"fallback"where the gate names one, as{run_dir}/decision.jsonand runuv run {emitEnvelopeHelper} record --workflow skf-create-skill --run-dir "{run_dir}" --decision < "{run_dir}/decision.json". The run sink it appends to,{run_dir}/headless-decisions.jsonl, is the brief's one decision trail: it survives context compaction, step 5 §7 renders the evidence report's## Auto-Decisionstable from it, and the result envelope and contract carry it
Stages
| # | Step | File | Auto-proceed |
| 1 | Load Brief | references/load-brief.md | Conditional |
| 2b | CCC Discover | references/sub/ccc-discover.md | Yes |
| 3 | Extract | references/extract.md | No (confirm) |
| 3b | Fetch Temporal | references/sub/fetch-temporal.md | Yes |
| 3c | Fetch Docs | references/sub/fetch-docs.md | Conditional |
| 3d | Component Extraction | references/component-extraction.md | Conditional |
| 4 | Enrich | references/enrich.md | Yes |
| 5 | Compile | references/compile.md | Yes |
| 5a | Doc Sources | references/step-doc-sources.md | Yes |
| 5b | Auto-Shard | references/step-auto-shard.md | Yes |
| 5c | Doc-Rot | references/step-doc-rot.md | Yes |
| 6 | Validate | references/validate.md | Yes |
| 7 | Generate Artifacts | references/generate-artifacts.md | Yes |
| 8 | Report | references/report.md | Yes |
| 9 | Workflow Health Check | references/health-check.md | Yes |
Sub-steps under references/sub/ are conditional branches (CCC discovery, temporal and doc enrichment), lettered by the place they take in the run and kept out of the main-line step count. Step 3d (Component Extraction) is a branch inside step 3 for a component-library brief: extract §2c loads it in place of §4 to §4c and resumes at its §5, before Gate 2.
Invocation Contract
| Aspect | Detail | |||||
| Inputs | brief_path (a skill-brief.yaml path or a skill name) [optional: without it, step 1 offers the briefs in {forge_data_folder}, and a headless run halts unless there is one], --batch [optional: the briefs or folders of briefs after it, {forge_data_folder} when none is given, each validated before the first compiles] | |||||
| Gates | step 1: Brief Selection (no brief named and several in {forge_data_folder}; headless: HARD HALT brief-missing, exit 2; one brief: picked and recorded as gate brief-selection) | step 3: Tag Choice Gate (several tags match the brief's version; headless: the first in priority order) | step 3 §2a: Authoritative-File Gate [P]/[S]/[U] (an authoritative AI documentation file outside the brief's scope; headless: deferred-headless, one auto-decision per path) | step 3: Review Gate [C]/[R] (with the zero-export warning when a source brief without doc_urls extracted no export; [R] with it or the head-cap warning) | step 3c: Zero-Export Gate [C]/[R] (a source brief with no export whose every doc_urls fetch failed) | step 3d: Demo-Exclusion Gate [Y], then Registry Gate [Y] (candidate found) or [S] (none found), component-library scope only, each skipped once the brief holds scope.demo_patterns or scope.registry_path, which step 3d writes when a user confirms or gives the patterns or the registry path |
| Outputs | SKILL.md, context-snippet.md, metadata.json, provenance-map.json, evidence-report.md, extraction-rules.yaml, references/; per brief, the result contract (create-skill-result-{YYYYMMDD-HHmmss}.json and its -latest.json copy in {forge_version}) and one SKF_CREATE_SKILL_RESULT_JSON line on stdout, on stderr at a HARD HALT; and under --batch the batch summary (create-skill-batch-{YYYYMMDD-HHmmss}.json and its -latest.json copy in {skills_output_folder}/_batch/) | |||||
| Headless | All gates auto-resolve with default action when {headless_mode} is true; each auto-decision reaches the envelope's and the result contract's headless_decisions. A caller reads the run's own SKF_CREATE_SKILL_RESULT_JSON line. A run that printed no envelope line has no result to read, whatever the process exit code: it was cut off, or could not write its result, and create-skill-result-latest.json may then describe an earlier run, so it is never read in its place. Under --batch, a caller reads the batch's batch_summary event and the summary file its summary_path names, never create-skill-batch-latest.json in its place: that copy holds the last batch summary written, which may be another batch's. A printed batch_summary event stays the batch's result even if a halt line follows it. A batch that printed no batch_summary event has no batch result, whatever the process exit code: a halt line of its own (phase batch-mode) says why it stopped, and with no halt line it was cut off or could not print its halt line. A target it printed a done or fail event for ended as that event says, and a brief the plan listed as not compiled ended failed with its message; a target with a start event and no end event has no result, and any other target with no event did not run in this session. | |||||
| Exit codes | 0 for a finished brief; at a HARD HALT 2 (the brief is missing, malformed or invalid), 3 (no forge config, source, helper or documentation), 4 (a write failed), 5 (a refused or broken package), 6 (the user chose to refine the scope). A --batch run exits with the highest code among its briefs, 0 when every brief finished |
On Activation
- Load config from
{project-root}/_bmad/skf/config.yamland resolve:output_folder,user_name,communication_language,document_output_language,sidecar_path,skills_output_folder,forge_data_folder
- 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 workflowIt merges the bundled
{skill-root}/customize.tomlwith{project-root}/_bmad/custom/skf-create-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}(unset when the resolver ran) for step 1 §0 to record in each brief's run folder.Apply the resolved values so the surface is not 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 (entries prefixedfile:are paths or globs whose contents load as facts), except a!entry and the entry it names (!file:{project-root}/**/project-context.mddrops the bundled project-context default); and stash{onCompleteCommand}←workflow.on_complete(empty string = no-op) for step 8 to invoke once each brief's result contract is written. After activation completes, execute each entry inworkflow.activation_steps_appendin order.- Resolve
{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, the shared emitter every result envelope, result contract and recorded decision goes through. - If
--batchwas given, load, read the full file, and then executereferences/batch-mode.md: it validates every brief first, runs steps 1 to 8 for each one and the health check once. Otherwise load, read the full file, and then executereferences/load-brief.mdto begin the workflow.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

