# Skill Template — Quick Skill Output

## SKILL.md Section Structure

The following sections should be populated in the generated SKILL.md. Best-effort — not all sections will have data for every skill.

### Required Sections

```markdown
---
name: {skill_name}
description: >
  {README-derived description, trigger-optimized for agent discovery.
  Include what the package does and when to use it.
  Mention what NOT to use it for if applicable.}
---

# {skill_name}

## Overview
- **Package:** {package_name}
- **Repository:** {repo_url}
- **Language:** {language}
- **Source Authority:** community
- **Generated:** {date}

## Description
{README-derived description of what the package does}

## Key Exports
{List of public exports with brief descriptions}

## Usage Patterns
{Common usage patterns extracted from README examples}
```

### Optional Sections (include when data available)

```markdown
## Configuration
{Configuration options if found in source}

## Dependencies
{Key dependencies from manifest file}

## Notes
{Any caveats, limitations, or observations about the extraction}
```

## context-snippet.md Format (Vercel-Aligned)

Indexed format targeting ~80-120 tokens per skill:

```markdown
[{skill_name} v{version}]|root: skills/{skill_name}/
|IMPORTANT: {skill_name} v{version} — read SKILL.md before writing {skill_name} code. Do NOT rely on training data.
|quick-start:{SKILL.md#usage-patterns}
|api: {top-5 exports with () for functions}
|key-types:{SKILL.md#key-exports} — {inline summary of most important type values}
|gotchas: {2-3 most critical pitfalls or breaking changes, inline}
```

## metadata.json Format

```json
{
  "name": "{skill_name}",
  "version": "{source-version or 1.0.0}",
  "description": "{brief description of the skill}",
  "skill_type": "single",
  "source_authority": "community",
  "source_repo": "{repo_url}",
  "source_root": "{resolved_source_path}",
  "source_commit": "{commit_sha_if_available}",
  "source_package": "{package_name}",
  "language": "{language}",
  "generated_by": "quick-skill",
  "generation_date": "{date}",
  "confidence_tier": "Quick",
  "spec_version": "1.3",
  "exports": ["{export_1}", "{export_2}"],
  "confidence_distribution": {
    "t1": 0,
    "t1_low": "{exports_count (integer, not string)}",
    "t2": 0,
    "t3": 0
  },
  "tool_versions": {
    "ast_grep": null,
    "qmd": null,
    "skf": "{skf_version}"
  },
  "stats": {
    "exports_documented": "{number}",
    "exports_public_api": "{number}",
    "exports_internal": 0,
    "exports_total": "{number}",
    "public_api_coverage": 1.0,
    "total_coverage": 1.0,
    "scripts_count": 0,
    "assets_count": 0
  },
  "dependencies": [],
  "compatibility": "{semver-range}",
  "provenance": {
    "language_hint": "{language_hint or null}",
    "scope_hint": "{scope_hint or null}"
  }
}
```

---
nextStepFile: 'resolve-target.md'
---

<!-- Config: communicate in {communication_language}. -->

# Batch Mode

When `--batch <file>` is supplied, quick-skill processes a list of targets from a text file in sequence rather than a single target from arguments. Designed for unattended bulk runs — CI pipelines, mass-rebuilds, and batch meta-workflows.

## Input format

One target per line. Empty lines and lines starting with `#` (after optional leading whitespace) are ignored. Each non-empty line has the same shape as the single-target `target` argument, with optional space-separated per-line modifiers:

```
# A batch input file.
lodash
@vercel/og
cognee@0.5.0
https://github.com/foo/bar
https://github.com/foo/bar@2.1.0-beta

# Per-line modifiers — overrides for THIS target only:
lodash language=javascript scope=src/
cognee@0.5.0 language=python scope=cognee/api/
```

Recognised per-line modifiers:

| Modifier | Effect (this target only) |
| --- | --- |
| `language=<lang>` | Sets `language_hint` for this target — same effect as the optional `language_hint` input on a single-target run. |
| `scope=<path>` | Sets `scope_hint` for this target — same effect as the optional `scope_hint` input on a single-target run. |

Per-line modifiers shadow the global `--description` / `--exports` / `--skip-snippet` / `--no-active-pointer` overrides only when those override fields are not set. Global overrides apply to every target unless a future modifier extends per-line override syntax.

## Execution

`--batch` implies `--headless`. The batch loop runs the full quick-skill pipeline (steps 1–7) for each target in file order:

1. Set `target`, `target_version`, `language_hint`, `scope_hint` from the batch line into the workflow context.
2. Execute steps 1–7 per the normal pipeline.
3. After step 7 completes (success or HARD HALT), record the per-target outcome (target, status, exit_code, skill_package, error.code) into the batch result list.
4. If `--fail-fast` is set and the target failed, exit the batch loop immediately. Otherwise continue with the next target.

Per-target output lands in `{skill_package}/` as today, with the per-target result contract at `{skill_package}/quick-skill-result-latest.json` (success or error variant per `references/halt-contract.md`).

## Batch summary contract

After the last target completes (or `--fail-fast` triggers an early exit), write the batch summary at:

```
{batchOutputPath}quick-skill-batch-{YYYYMMDD-HHmmss}.json
{batchOutputPath}quick-skill-batch-latest.json   (copy, not symlink)
```

`{batchOutputPath}` is resolved at SKILL.md On Activation §3 from `workflow.batch_output_path` (bundled default `{skills_output_folder}/_batch/`, trailing slash included).

Schema:

```json
{
  "skill": "skf-quick-skill",
  "mode": "batch",
  "status": "success | partial | failed",
  "timestamp": "<ISO 8601 UTC>",
  "input_file": "<path passed to --batch>",
  "targets_total": 0,
  "succeeded": 0,
  "failed": 0,
  "fail_fast_triggered": false,
  "results": [
    {
      "target": "<line from batch file>",
      "status": "success | error",
      "exit_code": 0,
      "skill_package": "<absolute path or null>",
      "error_code": null
    }
  ]
}
```

`status` resolves as: `"success"` when `failed == 0`; `"partial"` when `failed > 0 && succeeded > 0`; `"failed"` when `succeeded == 0`. `fail_fast_triggered` is `true` only when `--fail-fast` aborted the loop early — `targets_total` then reflects the count actually attempted, not the file's line count.

## Headless events

Batch mode emits per-target boundary events on stderr in addition to the per-step events documented in Workflow Rules:

```
{"batch":<n>,"target":"<target>","status":"start"}
{"batch":<n>,"target":"<target>","status":"done","exit":<code>}
{"batch":<n>,"target":"<target>","status":"fail","exit":<code>,"error_code":"<class>"}
```

`<n>` is the 1-based index of the target in the parsed list. After the loop ends, emit one final batch-summary event:

```
{"batch_summary":true,"targets_total":N,"succeeded":K,"failed":M,"status":"<...>","fail_fast_triggered":<bool>}
```

## Exit code

The batch process exits with code `0` when `failed == 0`, otherwise with the exit code of the first failed target (so automators that already branch on the single-target exit-code map continue to work without batch-specific handling). When `--fail-fast` triggers, the exit code is the failing target's code.

---
nextStepFile: 'write-and-validate.md'
skillTemplateData: '{skillTemplatePath}'
quickMetadataRendererProbeOrder:
  - '{project-root}/_bmad/skf/shared/scripts/skf-render-quick-metadata.py'
  - '{project-root}/src/shared/scripts/skf-render-quick-metadata.py'
---

<!-- Config: communicate in {communication_language}. Generated SKILL.md text in {document_output_language}. -->

# Step 4: Compile

## STEP GOAL:

To assemble the best-effort SKILL.md document, context-snippet.md in Vercel-aligned indexed format, and metadata.json with `source_authority: community` from the extraction inventory. Present compiled output for review before validation.

## Rules

- Focus only on assembling the three output documents — do not write files to disk (that's step 6)
- Follow template structure exactly from {skillTemplateData}
- Mark any sections with insufficient data as best-effort

## Steps

### 1. Load Skill Template

Load {skillTemplateData} to understand:
- SKILL.md required and optional sections
- context-snippet.md Vercel-aligned indexed format
- metadata.json field requirements

### 2. Assemble SKILL.md

Populate the SKILL.md section structure from `{skillTemplateData}` § "SKILL.md Section Structure" (the frontmatter skeleton and the Required/Optional section list live there) using extraction_inventory. The rules below are the deltas the template does not encode:

**Frontmatter rules (agentskills.io compliance):**
- `name`: lowercase alphanumeric + hyphens only, must match the skill output directory name. Prefer gerund form (`processing-pdfs`) for clarity.
- `description`: non-empty, max 1024 chars, optimized for agent discovery. Use third-person voice ("Processes..." not "I can..." / "You can...") so it reads correctly in the agent's skill index.
- No other frontmatter fields — only `name` and `description` for community skills

**Per-section override wiring:**
- **Description:** From `{overrides.description}` if set (subject to the same length/voice checks as extracted descriptions); otherwise from extraction_inventory.description (README-derived)
- **Key Exports:** From `{overrides.exports}` if set (comma-separated names parsed and trimmed; empty items skipped); otherwise from extraction_inventory.exports — list each with name, type, brief description

**Scripts & Assets Note** (add as an optional section if source contains `scripts/`, `bin/`, `assets/`, `templates/`, or `schemas/` directories): "This package may include scripts and assets. Run create-skill for full extraction with provenance tracking."

**If confidence is low** — include a note: "This skill was generated with limited source data. Consider running create-skill for a more thorough compilation."

### 3. Generate Context Snippet

**If `{overrides.skip_snippet}` is true** — skip generation and note in the §5 preview: "context-snippet.md skipped per `--skip-snippet` override." Step-05 §2 will skip the corresponding write; step 5 §5 advisory snippet validation will report a "skipped" entry.

Otherwise, produce context-snippet.md in the Vercel-aligned indexed format from `{skillTemplateData}` § "context-snippet.md Format" (~80-120 tokens).

The snippet anchors point to the QS template's actual headings — `#usage-patterns` (Usage Patterns) and `#key-exports` (Key Exports). The QS template has no `## Quick Start` / `## Key Types` headings (those are Deep-tier sections), so the Deep-tier anchors `#quick-start` / `#key-types` would dangle. If the assembled SKILL.md is missing the referenced heading, omit that line rather than emit a dangling anchor.

**If fewer than 5 exports:** Use all available exports.
**If no exports:** Omit the api line.
**If no gotchas known:** Omit the gotchas line.

### 4. Generate Metadata JSON

Run the shared renderer against the assembled state. The helper applies the constants, echoes input-derived fields, computes export counts and the ISO 8601 UTC timestamp, and emits the canonical envelope per `{skillTemplateData}` § "metadata.json Format".

**Resolve `{quickMetadataRenderer}`** from `{quickMetadataRendererProbeOrder}`; first existing path wins. If no candidate exists, fall back to in-prompt rendering of the canonical envelope per `{skillTemplateData}` § "metadata.json Format".

**Probe `tool_versions.skf` first** (the helper expects it as input — the filesystem walk stays here because the helper does no I/O):

1. Read `{project-root}/_bmad/skf/package.json` → take `version`
2. If absent, read `{project-root}/_bmad/skf/VERSION`
3. If absent, set to `"unknown"`

Build the input payload from the extraction inventory + step 1 resolution + the probed `tool_versions.skf` and pipe it to the renderer:

```bash
echo '{"name":"<name>","version":"<v>","description":"<desc>","language":"<lang>","source_repo":"<url>","source_root":"<path or empty>","source_commit":"<source_ref or empty>","source_package":"<package or name>","exports":[{"name":"...","type":"..."}],"dependencies":["..."],"compatibility":"<semver-range or empty>","language_hint":<hint or null>,"scope_hint":<hint or null>,"skf_version":"<probed>"}' \
  | python3 {quickMetadataRenderer}
```

The renderer emits the rendered metadata.json on stdout. Capture the output as `metadata` for the §5 preview and step 5 §2's deliverable write.

### 5. Present Compiled Output for Review

**If `{headless_mode}` is true** — skip the inline preview (no human reviewer reads it) and emit a one-line summary instead:

"Compiled: SKILL.md ({section_count} sections, {export_count} exports), context-snippet.md (~{snippet_token_count} tokens), metadata.json (version {version}, confidence {confidence}). Auto-approving [C]."

Then proceed directly to §6 — the GATE default action takes over.

**Otherwise (interactive mode):**

"**Compilation complete. Review before validation:**

---

**SKILL.md Preview:**

{Display the full assembled SKILL.md content}

---

**context-snippet.md:**

{Display the snippet}

---

**metadata.json:**

{Display the JSON}

---

**Extraction confidence:** {confidence}
**Exports documented:** {count}

Review the output above, then choose: [C] continue to validation, [E] edit the description, [S] adjust scope and re-extract, or [Q] quit without writing."

### 6. Present MENU OPTIONS

Display: **Select:** [C] Continue to Validation · [E] Edit description · [S] Adjust scope and re-extract · [Q] Quit without writing

#### Menu Handling Logic:

- **IF C** — Load, read entire file, then execute {nextStepFile}.
- **IF E** — Ask the user for a replacement description ("New description (1–1024 chars):"). Update SKILL.md frontmatter `description` and `metadata.json.description` in the in-memory compiled output, then re-render the §5 preview and redisplay this menu. Do not re-run extraction.
- **IF S** — Ask the user for an adjusted `scope_hint` ("New scope (e.g. `src/server/`, `packages/core/`):") and optionally a `language_hint`. Update the extraction context with the new hints, then load `quick-extract.md` to re-extract. The new extraction returns to §1 of this step on completion. Discards the prior compiled output.
- **IF Q** — HARD HALT with **exit code 6 (user-cancelled)** per the exit-code map in `references/halt-contract.md`: "Compilation cancelled. No files written." Before exiting, emit the error result contract per `references/halt-contract.md` (`phase: "compile"`, `error.code: "user-cancelled"`, `skill_package: null`). Do not proceed to validation; do not write any artifacts.
- **IF Any other** — Help the user adjust the compiled output (treated as a free-form revision request), then redisplay the menu.

#### Gate:

- Halt and wait for user input after presenting the compiled output; only [C] (or a headless auto-approve) chains to `{nextStepFile}` for validation.
- **GATE [default: C]** — If `{headless_mode}`: auto-proceed with [C] Continue, log: "headless: auto-approve compiled output"
- [E] re-renders the preview without re-running extraction; [S] discards the compiled output and re-runs step 3 with new hints.

---
nextStepFile: 'quick-extract.md'
---

<!-- Config: communicate in {communication_language}. -->

# Step 2: Ecosystem Check

## STEP GOAL:

To query the agentskills.io ecosystem for an existing official skill matching the resolved target, preventing unnecessary duplication. This is an advisory gate — it never blocks the workflow on failure.

## Rules

- 5-second timeout on ecosystem queries; tool unavailability is a silent skip, not an error
- Do not begin extraction or compilation

## Steps

### 1. Query Ecosystem

Search for an existing official skill matching `{repo_name}` in the agentskills.io ecosystem.

**Query methods (try in order):**
1. Search agentskills.io registry for `{repo_name}`
2. Web search: `"agentskills.io" "{repo_name}" skill`

**Apply 5-second timeout.** If query takes longer, treat as no-match.

### 2. Evaluate Result

**If tool unavailable or timeout:**
- Set `ecosystem_status: skip`
- Proceed silently to step 3 (auto-proceed, no message to user)

**If no match found:**
- Set `ecosystem_status: no-match`
- Auto-proceed silently to step 3. Do not display any message — absence of a match is the expected case.

**If match found:**
- Set `ecosystem_status: match`
- Display match details and present conditional menu:

"**Existing official skill found for {repo_name}.**

**Skill:** {matched_skill_name}
**Source:** agentskills.io
**Authority:** official

An official skill already exists. You can:

**[P] Proceed** — Compile a custom community skill anyway (different scope or customization)
**[I] Install** — Install the existing official skill instead (exits this workflow)
**[A] Abort** — Cancel compilation"

### 3. Handle Match Menu (only when a match was found)

#### Menu Handling Logic:

- IF P: Set `ecosystem_status: match-proceed`, then load, read entire file, then execute {nextStepFile}
- IF I: Display install instructions for the official skill, emit the HARD HALT envelope per `references/halt-contract.md` (`phase: "ecosystem-check"`, `error.code: "ecosystem-redirect"`, `error.message: "User opted to install existing official skill instead of compiling a custom community skill."`, `skill_package: null`), exit with code 8 (ecosystem-redirect). Skill package is unknown at this phase — no on-disk result file is written.
- IF A: Display "Compilation cancelled.", emit the HARD HALT envelope (`phase: "ecosystem-check"`, `error.code: "user-cancelled"`, `error.message: "User aborted at ecosystem-match gate."`, `skill_package: null`), exit with code 6 (user-cancelled). Skill package is unknown at this phase — no on-disk result file is written.
- IF Any other: help user, then redisplay the match menu

#### Gate:

- **GATE [default: P]** — If `{headless_mode}` and match found: auto-proceed with [P] Proceed (compile custom skill anyway), log: "headless: ecosystem match found, auto-proceeding with custom compilation"

### 4. Auto-Proceed (No Match or Skip)

For no-match and skip, load and execute {nextStepFile} to proceed to source extraction.

---
nextStepFile: 'health-check.md'
atomicWriteProbeOrder:
  - '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
  - '{project-root}/src/shared/scripts/skf-atomic-write.py'
---

<!-- Config: communicate in {communication_language}. Generated SKILL.md text in {document_output_language}. -->

# Step 6: Finalize

## STEP GOAL:

To finalize the skill by creating the active-version pointer, displaying the completion summary, and writing the result contract. Deliverables (SKILL.md, context-snippet.md, metadata.json) were already written in step 5 so that validation could run against files on disk; this step only performs the post-write finalization.

## Rules

- Do not rewrite deliverables — they were written and validated in step 5
- Create the active pointer via the shared helper — never `rm` + `ln -s` manually
- Result contract writing is mandatory (pipeline consumers depend on it)

## Steps

### 1. Create Active Pointer (atomic flip, Windows-safe)

**If `{overrides.no_active_pointer}` is true** — skip the helper invocation entirely. Log: "Active pointer: skipped per `--no-active-pointer` override." Do not update `{skill_group}/active`. Proceed to §2 with the active-pointer line omitted from the completion summary and the outputs payload.

`{skill_group}` and `{skill_package}` were computed in step 5 §1 from `{skills_output_folder}`, `{repo_name}`, and `{version}`; `{version}` was resolved from the extraction inventory. Reuse the same values here — do not recompute.

Create or update the `active` pointer at `{skill_group}/active` pointing to `{version}` using the shared atomic-flip helper. The helper acquires an `flock` on `{skill_group}/active.skf-lock`, refuses to replace a non-link at `{skill_group}/active` (protecting against accidental `rm -rf` of a real directory), and uses a rename-over-symlink pattern so the update is atomic from a concurrent reader's perspective. On Windows the helper automatically falls back to a directory junction (`mklink /J`) when `os.symlink` fails with `PRIVILEGE_NOT_HELD` / `ACCESS_DENIED` — junctions require no admin elevation and resolve identically for `skf-skill-inventory`'s consumers:

**Resolve `{atomicWriteHelper}`** from `{atomicWriteProbeOrder}`; first existing path wins. If no candidate exists, skip the flip the same way `--no-active-pointer` does: log "Active pointer: skipped — atomic-write helper unavailable", omit the active-pointer line from the completion summary and outputs, and record `active_pointer: "skipped-helper-missing"` in the result-contract summary (§3) so consumers see why the pointer is absent. The deliverables are already on disk, so a missing helper degrades to "no pointer" rather than a failed run. There is no manual fallback: a hand-rolled `rm` + `ln -s` loses the helper's atomicity and non-link guard, risking a half-flipped pointer or an `rm -rf` into a real directory.

```bash
python3 {atomicWriteHelper} flip-link \
  --link {skill_group}/active \
  --target {version}
```

The helper returns non-zero (helper exit 2) if `{skill_group}/active` already exists as a real directory or file rather than a link — in that case, HARD HALT the workflow with **exit code 7 (finalize-blocked)** per the exit-code map in `references/halt-contract.md`: "Refusing to flip `{skill_group}/active` — existing path is not a symlink or junction. Investigate manually; expected a link pointing at a version directory." Before exiting, emit the error result contract per `references/halt-contract.md` (`phase: "finalize"`, `error.code: "finalize-blocked"`, `skill_package` set, `outputs` listing the deliverables already on disk from step 5). A common cause on Windows is a prior run that executed `ln -s` under git-bash without Developer Mode enabled, which silently wrote a full directory copy; remove that copy and retry.

Confirm: "Active pointer: {skill_group}/active -> {version} ({kind})" where `{kind}` is `symlink` or `junction` as returned by the helper.

### 2. Display Completion Summary

"**Quick Skill complete.**

**Skill:** {repo_name} v{version}
**Language:** {language}
**Source:** {resolved_url}
**Authority:** community
**Confidence:** {extraction confidence}
{If `scope_hint` is non-empty, add:} **Scope:** {scope_hint}

**Files written:**
- `{skill_package}/SKILL.md`
- `{skill_package}/context-snippet.md` (omit this line when `--skip-snippet` was set)
- `{skill_package}/metadata.json`
- `{skill_group}/active` -> `{version}` (omit this line when `--no-active-pointer` was set)

**Exports documented:** {count}
**Validation:** {pass / N issues (advisory)}

---

**Recommended next steps:**

1. **test-skill** (advisory) — Run cognitive completeness verification on the generated skill
2. **export-skill** — Package and distribute the skill with platform-aware context injection

**Note:** This is a best-effort community skill. For deeper analysis with AST-verified exports and provenance tracking, use the full **create-skill** workflow with a skill brief."

### 3. Result Contract

Write the result contract per `shared/references/output-contract-schema.md`: the per-run record at `{skill_package}/quick-skill-result-{YYYYMMDD-HHmmss}.json` (UTC timestamp, resolution to seconds) and a copy at `{skill_package}/quick-skill-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include `SKILL.md`, `context-snippet.md`, and `metadata.json` paths in `outputs` and export count in `summary`.

**Post-completion hook (optional).** If `{onCompleteCommand}` is non-empty (resolved at SKILL.md On Activation §3 from `workflow.on_complete`), invoke it after the result contract is finalized:

```bash
{onCompleteCommand} --skill-package={skill_package}
```

Log success/failure but never fail the workflow on a hook error — the skill is already written. The hook runs last so a git-add, registry registration, or notifier sees a complete package. When `{onCompleteCommand}` is empty (bundled default), skip the invocation entirely.

### 4. Chain to Health Check

Once the active pointer, completion summary, result contract, and any post-completion hook are done, load and execute {nextStepFile}. Do not stop here — health-check is the true terminal step even though the summary reads as final.

<!-- Config: communicate in {communication_language}. -->

# HARD HALT Contract

The exit-code map and error-result envelope every step emits on a HARD HALT. Any step loads this file on its failure path, so the wire format is available even if SKILL.md has been compacted mid-run.

## Exit Codes

Every HARD HALT in this workflow exits with a stable, documented code so headless automators can branch on the failure class without grepping message text:

| Code | Meaning                | Raised by                                                   |
| ---- | ---------------------- | ----------------------------------------------------------- |
| 0    | success                | step 7 (terminal)                                          |
| 3    | resolution-failure     | step 1 (prose input §2, registry chain §3, version-tag miss §3a, language abort §4); step 3 (non-library shape §1.5, zero-exports §4.5) |
| 4    | write-failure          | step 5 §2 (deliverable write failed)                       |
| 5    | overwrite-cancelled    | step 5 §1 (user selected [N])                              |
| 6    | user-cancelled         | step 1 §1 ([X] Cancel and exit, or cancel-line affordance); step 2 §3 ([A] Abort at ecosystem-match gate); step 4 §6 (user selected [Q]) |
| 7    | finalize-blocked       | step 6 §1 (active-pointer flip refused — non-link in place) |
| 8    | ecosystem-redirect     | step 2 §3 ([I] Install at ecosystem-match gate — user opted to install the existing official skill instead of compiling a custom community skill) |

## Result Contract on HARD HALT

In addition to the success-variant result contract written by step 6 §3, every HARD HALT must surface an **error variant** so headless automators don't silently break when `quick-skill-result-latest.json` is missing on failed runs.

**Always (every HARD HALT, regardless of phase)** — emit a single line on **stderr**:

```
SKF_QUICK_SKILL_RESULT_JSON: {"status":"error","exit_code":<N>,"phase":"<slug>","error":{"code":"<class>","message":"<short>"},"outputs":{},"summary":{},"skill_package":"<path-or-null>"}
```

One line, no pretty-print. Matches the prefix-and-envelope convention used by `skf-emit-result-envelope.py`.

**Additionally, when `{skill_package}` is known** (HALT at step 5 §1 onward) — write the same JSON object (without the `SKF_QUICK_SKILL_RESULT_JSON: ` prefix) to disk:

```
{skill_package}/quick-skill-result-{YYYYMMDD-HHmmss}.json
{skill_package}/quick-skill-result-latest.json   (copy, not symlink)
```

so consumers that hardcode the `-latest.json` path see a deterministic file even on failed runs. HALTs at step 1/02/03/04 cannot write to disk because `{skill_package}` is computed only in step 5 §1; for those, the stderr envelope plus exit code is the contract.

**Schema:**

| Field           | Type           | Notes                                                                                                       |
| --------------- | -------------- | ----------------------------------------------------------------------------------------------------------- |
| `status`        | string         | always `"error"` for HARD HALTs                                                                             |
| `exit_code`     | integer        | matches the Exit Codes table above                                                                          |
| `phase`         | string         | step slug where the HALT occurred (e.g. `resolve-target`, `compile`)                                        |
| `error.code`    | string         | one of: `resolution-failure`, `write-failure`, `overwrite-cancelled`, `user-cancelled`, `finalize-blocked`, `ecosystem-redirect` |
| `error.message` | string         | the user-facing message that was displayed                                                                  |
| `error.details` | any            | optional — phase-specific context (e.g. the failed file path)                                               |
| `outputs`       | object         | empty `{}` on early HALTs; partial when files were already written                                          |
| `summary`       | object         | empty `{}` on early HALTs                                                                                   |
| `skill_package` | string \| null | absolute path when known, `null` when HALT preceded step 5 §1                                              |

---
# `shared/health-check.md` resolves relative to the SKF module root
# (`{project-root}/_bmad/skf/` when installed, `{project-root}/src/` during
# development), not relative to this step file.
nextStepFile: 'shared/health-check.md'
---

<!-- Config: communicate in {communication_language}. -->

# Step 7: Workflow Health Check

## STEP GOAL:

Chain to the shared workflow self-improvement health check at `{nextStepFile}`. This is the terminal step of quick-skill — after the shared health check completes, the workflow is fully done.

## Rules

- No user-facing reports, file writes, or result contracts in this step — those belong in step 6
- Delegate directly to `{nextStepFile}` with no additional commentary or intervening action

## Steps

Load `{nextStepFile}`, read it fully, then proceed to execute it.

---
nextStepFile: 'compile.md'
publicApiExtractorProbeOrder:
  - '{project-root}/_bmad/skf/shared/scripts/skf-extract-public-api.py'
  - '{project-root}/src/shared/scripts/skf-extract-public-api.py'
---

<!-- Config: communicate in {communication_language}. -->

# Step 3: Quick Extract

## STEP GOAL:

To read the resolved GitHub repository source and extract the public API surface using surface-level source reading (no AST). Produces an extraction inventory of exports, descriptions, and manifest data for compilation.

## Rules

- Best-effort extraction — completeness is not required; surface-level reading only, no AST
- Do not begin compilation or write output files
- If no exports found, use README content as fallback

## Steps

**Ref-aware source reading:** When `source_ref` is set from tag resolution (see step 1), append `?ref={source_ref}` to all GitHub API content and tree requests (e.g., `gh api repos/{owner}/{repo}/contents/{path}?ref={source_ref}`) to read from the tagged version. When using web browsing, use the tagged URL format (e.g., `github.com/{owner}/{repo}/blob/{source_ref}/{path}`). This ensures extraction reads from the same source version resolved during tag resolution.

**Parallel-fetch directive:** §1 (README), §2 (manifest), and §3 (entry-point exports) read independent files from the same `?ref={source_ref}` and are safe to issue as one batched tool-call message rather than three sequential round trips. For multi-module Maven (`<modules>`) and multi-project Gradle (`include(...)`) builds, also fetch all submodule `pom.xml` / `build.gradle[.kts]` files in parallel rather than serially per module — N module fetches collapse to O(1) wall-clock time.

### 1. Read README

Read `README.md` from the repository root via web browsing.

Extract:
- **Description:** What the package does (first paragraph or tagline)
- **Features:** Key features or capabilities listed
- **Usage patterns:** Code examples showing common usage
- **Installation:** Package manager install command (confirms package name)

If README is unavailable, note and continue.

### 1.5. Repo-Shape Sniff

After the README has loaded, classify the repo shape from the available signals before committing further effort to extraction. Quick-skill is designed to wrap a library; non-library repos sail through silently today and produce low-quality skills the user only notices via the description field after compilation.

**Classify as one of:**

- **library** (default) — README has installation / usage / API content; manifest at root with publishable metadata. Proceed normally.
- **awesome-list** — README H1 contains "awesome" (case-insensitive) or `awesome-` is in the repo name; README body is dominated by curated bullet links of the form `- [name](url) — desc`; no manifest at root.
- **docs-site / website** — README is short (under ~50 non-empty lines) and primarily points elsewhere ("See https://… for docs"); root has no manifest, or only a docs-framework manifest (e.g. `docusaurus.config.js`, `astro.config.mjs`, `mkdocs.yml`).
- **examples-only / tutorial** — README explicitly labels the repo as examples or a tutorial ("Code examples for…", "Tutorial: …", "Learn X by building Y"); typically no published package; many small standalone files instead of a single API surface.

**If a non-library shape is detected** — soft-warn and gate before continuing:

"**Heads up — `{repo_name}` looks like a `{shape}` repo, not a library.**

Quick-skill is designed to wrap a library's public API. The compiled SKILL.md will likely have a thin Description and an empty Key Exports list. You can continue anyway, or abort and pick a target library.

Select: [C] Continue anyway · [A] Abort"

- **IF C** — log "user accepted `{shape}` shape" and proceed to §2. Set `extraction_inventory.repo_shape` to the detected shape so the result contract carries the signal for automators.
- **IF A** — HARD HALT with **exit code 3 (resolution-failure)** per the exit-code map in `references/halt-contract.md`: "Aborted. `{shape}` repos are best wrapped manually with `/skf-create-skill` from a brief, not auto-extracted." Before exiting, emit the error result contract per `references/halt-contract.md` (`phase: "quick-extract"`, `error.code: "resolution-failure"`, `error.details: {repo_shape: "{shape}"}`, `skill_package: null`).

**GATE [default: C]** — In headless mode, log "headless: detected `{shape}` repo, continuing anyway" and proceed; the result contract's `summary.repo_shape` carries the signal so automators can flag low-quality outputs without re-parsing logs.

### 2. Fetch Source Files

Fetch the manifest file and the top-level entry-point file(s) for the detected language. The helper invoked in §3 does pure parsing — no I/O — so this step does the fetch work using `gh api` (preferred when source_ref is set) or web browsing.

| Language | Manifest | Entry-point files (quick mode) |
| --- | --- | --- |
| JavaScript / TypeScript | `package.json` | `index.{js,ts}`, `src/index.{ts,js}`, or the file pointed to by the `main` field |
| Python | `pyproject.toml` or `setup.py` | `__init__.py`, `src/{package}/__init__.py` |
| Rust | `Cargo.toml` | `src/lib.rs` |
| Go | `go.mod` | top-level `*.go` files (3–5 best-effort) |
| Java (Maven) | `pom.xml` | top-level `*.java` files under `src/main/java/<groupId-as-path>/` (3–5 best-effort) |
| Kotlin (Gradle) | `build.gradle.kts` or `build.gradle` | top-level `*.kt` files under `src/main/kotlin/` (3–5 best-effort); also fetch `settings.gradle[.kts]` for `include(...)` entries when present |

**If `scope_hint` provided:** focus the entry-point fetch on the specified directories instead of repo root.

For multi-module Maven (`<modules>`) and multi-project Gradle (`include(...)`) builds, fetch the parent manifest first, then loop §2+§3 per module. Batch the sub-module fetches per the parallel-fetch directive at the top of this step.

### 3. Parse Manifest and Scan Exports

Run the shared extractor against the contents fetched in §2. The helper does manifest parse + export scan in one invocation and emits a structured envelope ready to feed §4's inventory.

**Resolve `{publicApiExtractor}`** from `{publicApiExtractorProbeOrder}`; first existing path wins. If no candidate exists, fall back to in-prompt per-language regex parsing of the manifest and entry-point files.

Build the input payload from §2's fetched files and pipe it to the helper:

```bash
echo '{"language":"<lang>","manifest":{"path":"<rel>","content":"<...>"},"entries":[{"path":"<rel>","content":"<...>"},...],"mode":"quick"}' \
  | python3 {publicApiExtractor} --mode quick
```

Where `<lang>` is one of `js`, `ts`, `javascript`, `typescript`, `python`, `rust`, `go`, `java`, `kotlin`. The helper accepts arbitrarily many `entries` items and aggregates exports across them.

The helper emits JSON on stdout with:

- `package_name`, `version`, `description` — parsed from the manifest
- `exports[]` — `{name, type, source_file}` per discovered top-level public symbol
- `dependencies[]` — declared direct dependencies
- `modules[]` — for Maven `<modules>` and Gradle `include(...)`, the names of sub-modules to iterate (loop §2+§3 per entry)
- `extra` — language-specific extras (e.g. `group_id` for Maven)
- `warnings[]` — manifest parse failures or scanner errors (advisory only; the envelope is still valid)

Capture the helper's output into the extraction context. The shape of the envelope is the same for every language; §4 builds the inventory from it without per-language branching.

**Multi-module loop:** when `modules[]` is non-empty, fetch each sub-module's manifest + entry-point files (§2) and re-invoke the helper per module (§3), aggregating `exports[]` across all module envelopes. The aggregated `exports[]`, `dependencies[]`, and a single resolved `package_name` (from the parent manifest) feed §4.

### 4. Build Extraction Inventory

Assemble the extraction inventory from collected data:

```
extraction_inventory:
  description: {from README or manifest}
  package_name: {from manifest}
  version: {from manifest}
  language: {detected}
  exports: [{name, type, brief_description}]
  usage_patterns: [{pattern from README examples}]
  dependencies: [{key deps from manifest}]
  confidence: {high/medium/low based on data quality}
```

**If no exports found:**
- Set confidence to `low`
- Use README description and features as fallback content
- Note: "No exports detected — SKILL.md will be based on README content only"

### 4.5. Zero-Exports Soft Gate (rescue mode)

Run this gate **only when** `extraction_inventory.exports.length == 0` and `extraction_inventory.description` is empty (no usable README content either). When either is non-empty, the README-fallback in §4 produces a usable skill and this section is skipped.

When both are empty, the compiled SKILL.md would be effectively empty — no API surface to document and no description to fall back on. Offer the user a chance to retry with hints before producing a degenerate output:

"**Extraction yielded zero exports and no README description.**

The compiled SKILL.md would be effectively empty — no API surface to document and no description to fall back on.

Common causes:
- Wrong scope (extraction read the repo root, but the public API lives in a subdir)
- Wrong language (manifest probe picked the test/build language, not the lib language)
- Repo lays out exports unconventionally (e.g., not in `src/index.*` or `lib.rs`)

Select: [R] Retry with new hints · [P] Proceed anyway (low-confidence skill) · [A] Abort"

- **IF R** — prompt for new `scope_hint` ("New scope hint (e.g. `src/server/`):") and optional new `language_hint` ("New language hint (or empty to keep `{language}`):"). Update the extraction context with the new hints, then **re-execute step 3 from §1** with the new values. Discards the prior empty inventory.
- **IF P** — log "user accepted zero-exports outcome" and proceed to §5. The compiled skill will be README-content-only with confidence `low`. Record `zero_exports_rescue: "user-accepted"` in the inventory so the result contract summary surfaces it.
- **IF A** — HARD HALT with **exit code 3 (resolution-failure)**: "Aborted. Run `/skf-create-skill` from a brief if you want a guided extraction with provenance tracking." Before exiting, emit the error result contract per `references/halt-contract.md` (`phase: "quick-extract"`, `error.code: "resolution-failure"`, `error.details: {exports_found: 0, description_empty: true, language: "{language}", scope: "{scope_hint or 'entire repo'}"}`, `skill_package: null`).

**GATE [default: P]** — In headless mode, log "headless: zero exports + empty description, proceeding with low-confidence skill" and proceed; record `zero_exports_rescue: "auto-proceeded"` in the result contract summary so batch automators can re-queue these targets with stricter hints downstream. [P] preserves the pre-rescue behaviour for unattended pipelines.

### 5. Report Extraction Summary

"**Extraction complete:**

- **Package:** {package_name} v{version}
- **Language:** {language}
- **Exports found:** {count}
- **Confidence:** {confidence}
- **Source files read:** {count}

**Proceeding to compilation...**"

### 6. Auto-Proceed to Compilation

Once extraction_inventory is assembled (even if minimal or low-confidence), load and execute {nextStepFile} to compile.

<!-- Config: communicate in {communication_language}. -->

# Registry Resolution Patterns

## Package-to-Repo Resolution

When the user provides a package name instead of a GitHub URL, use this fallback chain to resolve the source repository.

### Detection: URL vs Package Name

- **GitHub URL:** Starts with `https://github.com/` or `github.com/` — extract org/repo directly
- **Package name:** Everything else — enter resolution chain below

### Resolution Fallback Chain

Try each registry in order. Stop at first success.

**Per-call timeout:** apply a 10s timeout to each registry HTTP call (15s for the web-search fallback) so a single hung registry cannot stall the workflow under hostile network conditions. Treat a timeout as a soft failure and fall through to the next entry in the chain.

#### 1. npm Registry (JavaScript/TypeScript)

```
URL: https://registry.npmjs.org/{package_name}
Field: repository.url
Fallback field: homepage
```

Extract `repository.url`, strip `git+` prefix and `.git` suffix if present.

#### 2. PyPI Registry (Python)

```
URL: https://pypi.org/pypi/{package_name}/json
Field: info.project_urls.Source OR info.project_urls.Repository OR info.home_page
```

Check `project_urls` keys in order: Source, Repository, Homepage. Filter for GitHub URLs.

#### 3. crates.io Registry (Rust)

```
URL: https://crates.io/api/v1/crates/{package_name}
Field: crate.repository
```

Direct `repository` field usually points to GitHub.

#### 4. Web Search Fallback

If all registry lookups fail:

```
Search: "{package_name} github repository"
```

Look for GitHub URL in top results. Verify it matches the package name.

#### 5. Resolution Failure

If all methods fail:

```
"Could not resolve '{package_name}' to a GitHub repository.

Please provide the GitHub URL directly, or check:
- Is the package name spelled correctly?
- Is it a private package?
- Is the source hosted on a non-GitHub platform?"
```

**Hard halt** — cannot proceed without a resolved source.

Language detection is authoritative in `resolve-target.md` §4 (Detect Language) — this file covers only the package-to-repo registry chain.

---
nextStepFile: 'ecosystem-check.md'
registryResolutionData: '{registryResolutionPath}'
packageResolverProbeOrder:
  - '{project-root}/_bmad/skf/shared/scripts/skf-resolve-package.py'
  - '{project-root}/src/shared/scripts/skf-resolve-package.py'
detectLanguageProbeOrder:
  - '{project-root}/_bmad/skf/shared/scripts/skf-detect-language.py'
  - '{project-root}/src/shared/scripts/skf-detect-language.py'
---

<!-- Config: communicate in {communication_language}. -->

# Step 1: Resolve Target

## STEP GOAL:

To accept a GitHub URL or package name from the user, resolve it to a GitHub repository, detect the primary language, and prepare state for source extraction.

## Rules

- Focus only on resolving the target to a GitHub repository — do not begin extraction or compilation
- If resolution fails, hard halt with actionable guidance

## Steps

### 1. Accept User Input

**Batch mode:** if `--batch` is active (see SKILL.md "Batch Mode"), the current target was already resolved by On Activation step 5 from the next batch line and placed into the workflow context as `target`, with optional `language_hint` and `scope_hint` per-line modifiers. Skip the prompt below — emit `{"batch":<n>,"target":"<target>","status":"start"}` to stderr and proceed directly to §1b with the batch-supplied values.

**Single-target mode** (default):

"**Quick Skill — fastest path to a skill.**

Provide a **GitHub URL** or **package name** and I'll resolve it to source and compile a best-effort SKILL.md.

**Target:** (GitHub URL or package name)

Examples: `cocoindex`, `@tanstack/query`, `https://github.com/tursodatabase/limbo`, `cognee@0.5.0`

**Optional:**
- **Language hint:** (if the repo is multi-language)
- **Scope hint:** (specific directories to focus on)

Or type `cancel` / `exit` / `:q` / `[X]` to leave without writing anything."

Wait for user input. **Cancel branch** — if the user types `cancel`, `exit`, `:q`, `[X]`, or selects `[X] Cancel and exit`, display `"Cancelled — no files were written."` and HARD HALT with **exit code 6 (user-cancelled)** per the exit-code map in `references/halt-contract.md`. Before exiting, emit the error result contract per `references/halt-contract.md` (`phase: "resolve-target"`, `error.code: "user-cancelled"`, `skill_package: null`). Cancellation here is non-destructive — no files have been written yet.

**GATE [default: use args]** — If `{headless_mode}` and a target (URL or package name) was provided as argument: use it as the target input and auto-proceed, log: "headless: using provided target". If no target provided in headless mode, HALT with: "headless mode requires a target argument."

### 1b. Parse Version Targeting

**Version targeting:** If the user input contains `@` followed by a semver-like string (e.g., `cognee@0.5.0`, `https://github.com/org/repo@2.1.0-beta`), parse it as:
- **Package/URL:** everything before the last `@`
- **Target version:** everything after the last `@`

Store the target version as `target_version` in the extraction context. When present, this version overrides auto-detection (same behavior as `target_version` in the skill-brief schema).

If no `@version` suffix is present, proceed as today — version will be auto-detected.

### 2. Classify Input Type

**If input starts with `https://github.com/` or `github.com/`:**
- Extract org/repo from URL
- Set `resolved_url` to the GitHub URL
- Set `repo_name` to the repo name (last path segment)
- Skip to step 3a (Verify Target Version Tag), then step 4 (Detect Language)

**If input is a package-name-like token** (no whitespace, matches `[@a-zA-Z0-9._/-]+(@<semver>)?`, e.g. `lodash`, `@scope/name`, `requests==2.31`, `cognee@0.5.0`):
- Proceed to step 3 (Registry Resolution)

**Otherwise — input looks like free-form prose, not a target:**

The user typed something like "I want a skill that helps with onboarding" or "build me a brainstorming workflow" — quick-skill cannot resolve that to a GitHub repository. Instead of falling through to a registry-failure HARD HALT, redirect with a sibling-skill suggestion:

"**This input looks like a description, not a package or URL.** Quick Skill needs a package name (e.g. `lodash`, `@vercel/og`, `requests`) or a GitHub URL (e.g. `https://github.com/lodash/lodash`).

If you are describing a skill you want to **create from scratch** rather than compile from existing source:

- Run `/skf-create-skill` with a skill brief — full pipeline with provenance tracking and AST-verified exports
- Or use `bmad-agent-builder` for an interactive skill design session

Otherwise, paste the package name or GitHub URL of the library you want to wrap, and quick-skill will resolve it."

**GATE [default: HALT]** — In headless mode, emit the same redirect message and HALT with **exit code 3 (resolution-failure)** per the exit-code map in `references/halt-contract.md`. Before exiting, emit the error result contract per `references/halt-contract.md` (`phase: "resolve-target"`, `error.code: "resolution-failure"`, `skill_package: null`). Do not attempt registry lookups against prose input; that wastes ~3-4 round trips and produces a less actionable error message than the redirect above.

### 3. Registry Resolution

Run the shared resolver against the deterministic registries (npm → PyPI → crates.io). The resolver does the HTTP+JSON+GitHub-URL-extraction work; the LLM only handles the web-search fallback below when needed.

**Resolve `{packageResolver}`** from `{packageResolverProbeOrder}`; first existing path wins. If no candidate exists, fall back to the LLM walk of {registryResolutionData} for the full chain.

```bash
python3 {packageResolver} {package_name} --timeout 10
```

The resolver emits JSON with `status` (`"ok"` or `"fallthrough"`), `resolved_url`, `repo_owner`, `repo_name`, `registry_used`, `registries_tried`, and a per-registry `registry_outcomes` map. Exit 0 means ok; exit 1 means fallthrough.

- **On `status: "ok"`** — capture `resolved_url`, `repo_name`, and `registry_used` from the JSON. Proceed to §3a.
- **On `status: "fallthrough"`** — the deterministic chain returned no GitHub URL (every registry replied with 404 / no-github-link / timeout). Fall back to the web-search step from {registryResolutionData} §4: search `"{package_name} github repository"` with a 15s timeout and look for a GitHub URL in the top results. If found, set `resolved_url` and proceed. If web search also returns nothing, HARD HALT below.

**If all methods fail — HARD HALT (exit code 3, resolution-failure):**

"**Resolution failed.** Could not resolve `{package_name}` to a GitHub repository.

Check:
- Is the package name spelled correctly?
- Is it a private package?
- Is the source hosted on a non-GitHub platform?

**Provide the GitHub URL directly to continue.**"

In interactive mode, wait for corrected input and loop back to step 2. In headless mode, emit the error result contract per `references/halt-contract.md` (`phase: "resolve-target"`, `error.code: "resolution-failure"`, `skill_package: null`) and exit 3.

### 3a. Verify Target Version Tag (when applicable)

Skip this section if `target_version` is null (auto-detect path — version comes from manifest read in step 3).

When the user explicitly supplied `@version` in §1b, verify the tag exists in the resolved repo before extraction. Otherwise step 3 silently reads from the default branch while metadata records the requested version — a quiet provenance bug where the SKILL.md claims version 0.5.0 but the exports actually came from main.

Probe both with-and-without v-prefix (the v-prefix is conventional but not universal across ecosystems):

```bash
gh api repos/{owner}/{repo}/git/ref/tags/{target_version} --silent \
  || gh api repos/{owner}/{repo}/git/ref/tags/v{target_version} --silent
```

**If a matching tag is found** — set `source_ref` to the matching ref (with v-prefix when that variant matched). Step-03's ref-aware source reading uses this value to fetch from the tagged commit. Proceed to §4.

**If no tag matches** — HARD HALT with **exit code 3 (resolution-failure)**:

"**Tag `{target_version}` not found in `{owner}/{repo}`.**

The version was parsed from your `@version` suffix but does not exist as a tag in the resolved repository. Quick-skill cannot extract from a version with no commit pointer — the result would be sourced from the default branch but labelled `{target_version}` in metadata.

Recent tags in this repo:
{list top 5 from `gh api repos/{owner}/{repo}/tags --paginate=false`, or "(none — repo has no tags; omit @version to auto-detect from default branch)"}

Re-run with one of these tags, or omit the `@version` suffix to auto-detect from the default branch."

Before exiting, emit the error result contract per `references/halt-contract.md` (`phase: "resolve-target"`, `error.code: "resolution-failure"`, `error.details: {requested_version: "{target_version}", available_tags: [...top 5]}`, `skill_package: null`). In headless mode, exit immediately; do not loop.

### 4. Detect Language

**Resolve `{detectLanguageHelper}`** from `{detectLanguageProbeOrder}`; first existing path wins. If no candidate exists (e.g. Python/`uv` unavailable), fall back to the manifest-priority walk documented in the helper's `--help` — `package.json` → JavaScript/TypeScript (TypeScript when a `tsconfig.json` is also present), `Cargo.toml` → Rust, `pyproject.toml`/`setup.py`/`setup.cfg` → Python, `go.mod` → Go, `pom.xml` → Java, `build.gradle.kts` → Kotlin, `build.gradle` → Kotlin when `src/main/kotlin/` exists else Java, `*.csproj`/`*.sln` → C#, `Gemfile` → Ruby, then extension frequency — applied by hand.

Determine primary language:

1. **User-provided language hint** (overrides detection) — set `language` to the hint and skip straight to §5. The disambiguation gate below does not run.

2. **Delegate the rule walk to `{detectLanguageHelper}`** — it is the single source of truth for the manifest → language rule table (including the `package.json` JS-vs-TS disambiguation); do not restate or re-derive it here. Fetch the repo file listing once (`gh api repos/{owner}/{repo}/git/trees/{source_ref or default branch}?recursive=1`, reading the `path` values), then hand the flat list to the script:

   ```bash
   echo '{"tree": [<flat list of repo-relative file paths>]}' | uv run {detectLanguageHelper}
   ```

   The script returns `{language, confidence, detection_source, detected_languages}` after walking the deterministic rule table (manifest presence first, then extension-frequency fallback). `detected_languages` is the ordered, deduplicated set of every manifest-level match in priority order, with `detected_languages[0]` equal to the winning `language`.

3. **Auto-pick** — set `language` to the returned `language`. If `detected_languages` is empty (the script recognized no manifest and no source extensions — `language` is `"unknown"`), treat it as a zero-match resolution and HALT with the step 1 §3 resolution-failure guidance so the user can supply a language hint or a different target.

4. **Multi-language gate** (`len(detected_languages) > 1`) — the script found manifests for more than one language. Surface the choice rather than silently keeping the first match. Multi-language repos (Python + JS bindings, or monorepos with mixed manifests) otherwise produce a skill for whichever manifest sorts first in priority order, with no signal that the user might have wanted the other one.

   "**`{repo_name}` has manifests for multiple languages:** {detected_languages}.

   Primary guess: **{language}** (`detected_languages[0]`, manifest-priority order). If you wanted a different language, abort and re-run with `--language-hint <lang>` or with the optional language hint at step 1 §1.

   Select: [C] Continue with `{language}` · [A] Abort"

   - **IF C** — log "user accepted multi-manifest pick: `{language}`" and keep `language`.
   - **IF A** — HARD HALT with **exit code 3 (resolution-failure)**: "Aborted to disambiguate language. Re-run with a `language_hint`." Before exiting, emit the error result contract per `references/halt-contract.md` (`phase: "resolve-target"`, `error.code: "resolution-failure"`, `error.details: {detected_languages: [...], auto_pick: "{language}"}`, `skill_package: null`).
   - **GATE [default: C]** — Headless mode auto-proceeds with the manifest-priority pick; record `detected_languages` and `language_resolution: "auto-picked-first"` in the extraction context so the result contract surfaces the ambiguity downstream.

### 5. Confirm Resolution

"**Target resolved:**

- **Repository:** {resolved_url}
- **Name:** {repo_name}
- **Language:** {language}
- **Scope:** {scope_hint or 'entire repo'}

**Proceeding to ecosystem check...**"

### 6. Proceed to Next Step

Once the target is resolved to a GitHub repository with confirmed URL, name, and detected language, load and execute {nextStepFile} for the ecosystem check.

---
nextStepFile: 'finalize.md'
frontmatterValidatorProbeOrder:
  - '{project-root}/_bmad/skf/shared/scripts/skf-validate-frontmatter.py'
  - '{project-root}/src/shared/scripts/skf-validate-frontmatter.py'
outputValidatorProbeOrder:
  - '{project-root}/_bmad/skf/shared/scripts/skf-validate-output.py'
  - '{project-root}/src/shared/scripts/skf-validate-output.py'
---

<!-- Config: communicate in {communication_language}. Generated SKILL.md text in {document_output_language}. -->

# Step 5: Write & Validate

## STEP GOAL:

To write the compiled SKILL.md, context-snippet.md, and metadata.json to the versioned skill package, then validate them on disk against the agentskills.io specification at community tier. Writing happens here (before step 6 finalization) because `skill-check` is a file-based CLI — it reads artifacts from disk — so the files must exist before validation runs. Report any gaps or issues. Validation is advisory — issues are reported but do not block the workflow.

## Rules

- Write exactly what was compiled — do not modify content during writing or after validation
- Community-tier validation (lighter than official requirements)

## Steps

### 1. Create Output Directory

Resolve `{version}` from the extraction inventory's detected version, defaulting to `1.0.0` if not detected. Create the skill output directories:

```
{skill_group}                          # {skills_output_folder}/{repo_name}/
{skill_package}                        # {skills_output_folder}/{repo_name}/{version}/{repo_name}/
```

If `{skill_package}` already exists, confirm with user before overwriting:

"**Directory `{skill_package}` already exists.** Overwrite will replace the prior compiled output; validation results, result contracts, and any manual tweaks from the previous run will not be preserved. Overwrite existing files? [Y/N]"

- **If user selects Y:** Proceed to section 2.
- **If user selects N:** HARD HALT with **exit code 5 (overwrite-cancelled)** per the exit-code map in `references/halt-contract.md`: "Overwrite cancelled. Existing skill preserved. Run [QS] with a different skill name or remove the existing directory manually." Before exiting, emit the error result contract per `references/halt-contract.md` (`phase: "write-and-validate"`, `error.code: "overwrite-cancelled"`, `skill_package` set to the existing path that was preserved). Write the `-latest.json` envelope to disk here — `{skill_package}` is known, so consumers that hardcode that path see a deterministic file even on this cancelled run.

**GATE [default: Y]** — If `{headless_mode}` is true, auto-proceed with Y and log: "headless: overwriting existing `{skill_package}`".

### 2. Write Deliverables

Write the three compiled artifacts to the skill package so that validation in sections 3–7 has files on disk to read:

**File 1:** `{skill_package}/SKILL.md` — the compiled skill document
**File 2:** `{skill_package}/context-snippet.md` — the compressed context snippet. **Skip this write** if `{overrides.skip_snippet}` was set; the artifact is omitted from `outputs`.
**File 3:** `{skill_package}/metadata.json` — the machine-readable metadata

Confirm after each write: "Written: SKILL.md" / "Written: context-snippet.md" / "Written: metadata.json". When `--skip-snippet` is active, log "Skipped: context-snippet.md (--skip-snippet)" instead of the snippet write confirmation.

**If any write fails — HARD HALT (exit code 4, write-failure):** Before exiting, emit the error result contract per `references/halt-contract.md` (`phase: "write-and-validate"`, `error.code: "write-failure"`, `error.details: {failed_path: <path>, error: <details>}`, `skill_package` set, `outputs` listing any files that did write successfully before the failure).

"**Write failed:** Could not write to `{file_path}`.

Error: {error details}

Check:
- Does the output directory exist and is it writable?
- Is there sufficient disk space?
- Are there permission issues?"

### 3. Check Tool Availability

Run: `npx skill-check -h`

- If succeeds (returns usage information): Continue to automated validation (section 4)
- If fails (command not found or error): Skip to manual fallback in section 4

### 4. Validate SKILL.md via skill-check (if available)

**If `npx skill-check` is available**, run automated validation + security scan in one invocation against the skill package written in section 2 (security scan is enabled by default when `--no-security-scan` is omitted, so the same call covers §6 and avoids paying the npx startup cost twice):

```bash
npx skill-check check {skill_package} --fix --format json
```

This validates frontmatter, description, body limits, links, and formatting; runs the security scan; and auto-fixes deterministic issues (field ordering, slug format, required fields, trailing newlines).

**Parse JSON output** to extract:
- `scores[].score` — overall score (0-100); match the entry by `relativePath`/`skillId`
- `diagnostics[]` — remaining issues after auto-fix
- `fixed[]` — issues automatically corrected
- `security[]` (when present) — security findings, recorded as advisory warnings (security issues do not block output)

Record quality score, remaining diagnostics, and security findings as validation issues.

**If skill-check is not available**, run the shared frontmatter validator. Resolve `{frontmatterValidator}` from `{frontmatterValidatorProbeOrder}`; first existing path wins. If no candidate exists, log a high-severity issue ("frontmatter validator unavailable — both `npx skill-check` and `skf-validate-frontmatter.py` missing") and skip frontmatter validation.

```bash
uv run {frontmatterValidator} {skill_package}/SKILL.md --skill-dir-name {repo_name}
```

The validator emits JSON with `status` (`pass`/`fail`), `issues[]` (each with `severity`, `code`, `message`), and `frontmatter` (the parsed name/description). It checks frontmatter delimiters, name format (Unicode letters + digits + hyphens, no consecutive/trailing hyphens), name-directory match, description presence and length, and unknown fields against the agentskills.io spec. Record each `issues[]` entry as a validation issue with its reported severity. Missing frontmatter or missing required fields are high-severity — skills without valid frontmatter will fail `npx skills add` and `npx skill-check check`.

### 5. Validate Body, Snippet, and Metadata via skf-validate-output.py

Run the shared output validator against the on-disk skill package — it performs the body-structure, snippet-format, and metadata-shape checks. Pass `--skip-frontmatter` since §4 has already covered frontmatter.

**Resolve `{outputValidator}`:** probe `{outputValidatorProbeOrder}` (installed first, dev fallback); first existing path wins. If neither candidate exists, log a high-severity issue ("output validator unavailable — `skf-validate-output.py` missing") and skip body/snippet/metadata validation.

```bash
python3 {outputValidator} {skill_package} --generated-by quick-skill --skip-frontmatter
```

The validator emits JSON with `result` (PASS/FAIL), `validation.skill_md.body[]`, `validation.context_snippet.issues[]`, `validation.metadata.issues[]`, and a severity-bucketed `summary`. Record each issue as a validation issue at its reported severity.

The validator covers:

- **Body structure** — Overview, Description, Key Exports, Usage sections present (medium when missing)
- **Context snippet** — `[{name} v{version}]|root: ...` first line, `|IMPORTANT:` second line, ~80–120-token length
- **Metadata** — required string fields (`name`, `version`, `source_authority`, `language`, `generation_date`), `source_repo`, `generated_by`, `confidence_tier`, and `stats` numerics (`exports_documented`, `exports_public_api`, `exports_total`, `public_api_coverage`, `total_coverage`)

### 6. Security Scan (covered by §4)

Security findings are already collected from the §4 invocation (no separate `npx` round trip needed — `skill-check check ... --fix --format json` runs the security scan by default). If skill-check was unavailable in §3, log "security scan skipped — skill-check unavailable" in validation results.

### 7. Report Validation Results

"**Validation complete:**

**SKILL.md:** {pass/issues found} (quality score: {score}/100 if skill-check was available)
{list any issues}
{list any auto-fixed issues}

**context-snippet.md:** {pass/issues found}
{list any issues}

**metadata.json:** {pass/issues found}
{list any issues}

**Security:** {pass/warn/skipped}
{list any security findings}

**Overall:** {pass / N issues found}

{If issues found:}
These issues are advisory for community-tier skills. You can proceed to finalize or go back to adjust.

**Proceeding to finalize...**"

Set `validation_result` with pass/fail status, quality score, and issues list.

### 8. Auto-Proceed to Finalize

Once deliverables are written to `{skill_package}` and validation is reported (advisory), load and execute {nextStepFile} to finalize.