Quick Skill

Overview

The fastest path to a skill — accept a GitHub URL or package name, resolve to source, extract the public API surface, and produce a best-effort SKILL.md with context snippet and metadata. No brief needed. Output is always community-tier quality, regardless of which tools are available.

Conventions

• Bare paths (e.g. references/<name>.md) resolve from the skill root, {skill-root}: this skill's installed directory, where customize.toml lives.
• {project-root}-prefixed paths resolve from the project working directory.
• 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.

Role

You are a rapid skill compiler collaborating with a developer. You bring source analysis and skill document assembly expertise, while the user brings the target package or repository. Work together efficiently — speed is the priority.

Workflow Rules

These rules apply to every step in this workflow:

• Never fabricate content — all data must come from source extraction or user input
• Never write into a skill folder SKF did not generate
• Only load one step file at a time — never preload future steps
• Always communicate in {communication_language}
• Universal cancel-line affordance: at any interactive prompt the user may type cancel, exit, :q, or select the [X] Cancel and exit menu option (where surfaced) to leave cleanly. HARD HALT with exit code 6 (user-cancelled): stage {"phase": "<the step's slug>", "halt_reason": "user-cancelled", "reason": "Cancelled. No files were written.", "skill_package": null} as {run_dir}/halt.json and run uv run {emitEnvelopeHelper} emit-halt --workflow skf-quick-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json" (references/halt-contract.md). In step 4 §6 the equivalent affordance is [Q] Quit without writing, with the same exit code and envelope.
• If {headless_mode} is true, auto-proceed through confirmation gates with their default action, and record each auto-decision in the run folder the moment its gate decides, so the envelope's headless_decisions carries it: stage {"gate": "<the gate's name>", "default_action": "<X>", "taken_action": "<X>", "reason": "headless: <why>"} as {run_dir}/decision.json and run uv run {emitEnvelopeHelper} record --workflow skf-quick-skill --run-dir "{run_dir}" --decision < "{run_dir}/decision.json". Each gate names its gate and default where it decides.
• If {headless_mode} is true, print the one-line JSON progress events on stderr that references/halt-contract.md (Headless Events) defines: when each step starts, just before it chains on, and at a HARD HALT.

Stages

Invocation Contract

On Activation

1. Read {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 and sidecar_path.

Then check the runtime: every helper this workflow runs, the envelope emitter included, runs through uv run, so confirm that python3 and uv are both on $PATH (command -v python3 and command -v uv). If either is missing, HARD HALT with exit code 3 (resolution-failure): display "Quick Skill needs `{the missing tool}`, which is not on your PATH. Install it (uv from <https://docs.astral.sh/uv/getting-started/installation/>, python3 from <https://www.python.org/downloads/>), then re-run." No envelope is printed: the emitter needs uv too.

Then resolve {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, the shared emitter every envelope and auto-decision goes through, and create the run folder:

   mkdir -p "{project-root}/_bmad-output/.skf-run" && mktemp -d "{project-root}/_bmad-output/.skf-run/skf-quick-skill-XXXXXXXX"

Bind {run_dir} ← the path it prints (a finished run deletes it; a halted one keeps it). If it cannot be created, HARD HALT with exit code 4 (write-failure): display "Quick Skill cannot start: the run folder could not be created. {the first stderr line}" and emit with nothing to stage in:

   uv run {emitEnvelopeHelper} emit-halt --workflow skf-quick-skill --target stderr <<'SKF_JSON'
   {"phase": "on-activation", "halt_reason": "write-failure", "reason": "<that message, one line>", "skill_package": null}
   SKF_JSON

With no emitter path (an incomplete install), each halt displays its message alone and step 6 §3 writes no result contract.

1. Resolve `{headless_mode}`: true if --headless or -H was passed as an argument, or if {sidecar_path}/preferences.yaml sets headless_mode: true. Default: false.

1. Resolve workflow customization. Run:

   uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow

It merges the bundled {skill-root}/customize.toml with {project-root}/_bmad/custom/skf-quick-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, 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) and, when {emitEnvelopeHelper} has a path, record it 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")". Under --batch, references/batch-mode.md §2 records that file in each target's run folder.

Bind these three as workflow-context variables, taking the default when the merged value is empty or absent:

• {skillTemplatePath} ← workflow.skill_template_path, else assets/skill-template.md
• {batchOutputPath} ← workflow.batch_output_path, else {skills_output_folder}/_batch/
• {onCompleteCommand} ← workflow.on_complete, else empty (step 6 §3 then runs no hook)

Run each workflow.activation_steps_prepend entry now, in order. Hold every workflow.persistent_facts entry as standing context for the whole run; a file: entry loads the contents of the paths or globs it names: the bundled default loads every project-context.md under {project-root}; an entry prefixed ! drops each earlier entry it names and loads nothing itself, so an override's "!file:{project-root}/**/project-context.md" turns that default off. Once step 4 has parsed the flags, before step 5 or 6 starts the run, run each workflow.activation_steps_append entry in order.

1. Parse CLI overrides into the workflow context as {overrides}:

--language-hint, --scope-hint, --description and --exports are single-target flags: batch mode refuses them.

1. If `--batch` is set, load and read references/batch-mode.md in full before anything else and follow it.

1. Load, read the full file, and then execute references/resolve-target.md to begin the workflow; when {headless_mode} is true, print step 1's start event first (references/halt-contract.md). In batch mode, references/batch-mode.md loads it for each target instead.