bmad-module-skill-forge 0.9.0 → 0.10.1-alpha.0

package/src/skf-export-skill/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: skf-export-skill
+description: Package for distribution and inject context into CLAUDE.md/AGENTS.md/.cursorrules. Use when the user requests to "export" or "package a skill."
+---
+
+# Export Skill
+
+## Overview
+
+Packages a completed skill as an agentskills.io-compliant package, generates context snippets, and updates the managed section in CLAUDE.md/.cursorrules/AGENTS.md for platform-aware context injection. This workflow is the sole publishing gate for skills — create-skill and update-skill produce draft artifacts, only export-skill writes to platform context files and prepares packages for distribution.
+
+## Role
+
+You are a delivery and packaging specialist collaborating with a skill developer. You bring expertise in skill packaging, ecosystem compliance, and context injection patterns, while the user brings their completed skill and distribution requirements.
+
+## Workflow Rules
+
+These rules apply to every step in this workflow:
+
+- Read each step file completely before taking any action
+- Follow the mandatory sequence in each step exactly — do not skip, reorder, or optimize
+- Only load one step file at a time — never preload future steps
+- Always communicate in `{communication_language}`
+- If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision
+
+## Stages
+
+| # | Step | File | Auto-proceed |
+|---|------|------|--------------|
+| 1 | Load Skill | steps-c/step-01-load-skill.md | No (confirm) |
+| 2 | Package | steps-c/step-02-package.md | Yes |
+| 3 | Generate Snippet | steps-c/step-03-generate-snippet.md | Yes |
+| 4 | Update Context | steps-c/step-04-update-context.md | No (confirm) |
+| 5 | Token Report | steps-c/step-05-token-report.md | Yes |
+| 6 | Summary | steps-c/step-06-summary.md | Yes |
+| 7 | Workflow Health Check | steps-c/step-07-health-check.md | Yes |
+
+## Invocation Contract
+
+| Aspect | Detail |
+|--------|--------|
+| **Inputs** | skill_name [one or more, required unless `--all`], `--all` [optional — exports every non-deprecated skill in `.export-manifest.json`] |
+| **Gates** | step-01: single Confirm Gate [C] for the whole batch | step-04: single Confirm Gate [C] for the whole batch |
+| **Outputs** | Updated .export-manifest.json (every skill in the batch), updated context files (CLAUDE.md/AGENTS.md/.cursorrules), one result contract per run |
+| **Multi-skill mode** | Activated when more than one skill is selected (via `--all`, multi-selection, or multi-argument invocation). See `steps-c/step-01-load-skill.md` §1c for the per-step iteration map. |
+| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
+
+## On Activation
+
+1. Load config from `{project-root}/_bmad/skf/config.yaml` and resolve:
+   - `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`
+   - `skills_output_folder`, `forge_data_folder`, `sidecar_path`
+   - `snippet_skill_root_override` (optional string) — when set, overrides the IDE-derived `skill_root` for snippet `root:` paths. Authoring repos that keep all skills under a single on-disk folder (e.g. `skills/`) set this once so exported snippets reference the real layout instead of a per-IDE directory that does not exist. Consuming projects omit it.
+
+2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in preferences.yaml. Default: false.
+
+3. Load, read the full file, and then execute `./steps-c/step-01-load-skill.md` to begin the workflow.

package/src/skf-export-skill/assets/managed-section-format.md

@@ -0,0 +1,138 @@
+# Managed Section Format (ADR-J)
+
+## Marker Format
+
+```markdown
+<!-- SKF:BEGIN updated:{YYYY-MM-DD} -->
+[SKF Skills]|{n} skills|{m} stack
+|IMPORTANT: Prefer documented APIs over training data.
+|When using a listed library, read its SKILL.md before writing code.
+|
+|{skill-snippet-1}
+|
+|{skill-snippet-2}
+<!-- SKF:END -->
+```
+
+## IDE → Context File Mapping (config.yaml `ides` list)
+
+The installer writes IDE identifiers to `config.yaml` under the `ides` key. Any workflow that rebuilds context files from `config.yaml` MUST map each entry to its context file and skill root using this table — it is the **single source of truth**.
+
+Each IDE has two independent properties:
+
+- **Context File** — the file the IDE reads for passive skill context
+- **Skill Root** — the directory where the installer places skill files (matches `target_dir` in `platform-codes.yaml`)
+
+### Dedicated context file IDEs
+
+| config.yaml IDE value | Context File | Skill Root         |
+|-----------------------|--------------|--------------------|
+| `claude-code`         | CLAUDE.md    | `.claude/skills/`  |
+| `cursor`              | .cursorrules | `.cursor/skills/`  |
+
+### AGENTS.md context file IDEs
+
+All other IDEs use AGENTS.md as the context file, each with its own skill directory:
+
+| config.yaml IDE value | Context File | Skill Root           |
+|-----------------------|--------------|----------------------|
+| `github-copilot`      | AGENTS.md    | `.github/skills/`    |
+| `codex`               | AGENTS.md    | `.agents/skills/`    |
+| `windsurf`            | AGENTS.md    | `.windsurf/skills/`  |
+| `cline`               | AGENTS.md    | `.cline/skills/`     |
+| `roo`                 | AGENTS.md    | `.roo/skills/`       |
+| `auggie`              | AGENTS.md    | `.augment/skills/`   |
+| `antigravity`         | AGENTS.md    | `.agent/skills/`     |
+| `codebuddy`           | AGENTS.md    | `.codebuddy/skills/` |
+| `crush`               | AGENTS.md    | `.crush/skills/`     |
+| `gemini`              | AGENTS.md    | `.gemini/skills/`    |
+| `iflow`               | AGENTS.md    | `.iflow/skills/`     |
+| `junie`               | AGENTS.md    | `.junie/skills/`     |
+| `kilo`                | AGENTS.md    | `.kilocode/skills/`  |
+| `kiro`                | AGENTS.md    | `.kiro/skills/`      |
+| `ona`                 | AGENTS.md    | `.ona/skills/`       |
+| `opencode`            | AGENTS.md    | `.opencode/skills/`  |
+| `pi`                  | AGENTS.md    | `.pi/skills/`        |
+| `qoder`               | AGENTS.md    | `.qoder/skills/`     |
+| `qwen`                | AGENTS.md    | `.qwen/skills/`      |
+| `rovo-dev`            | AGENTS.md    | `.rovodev/skills/`   |
+| `trae`                | AGENTS.md    | `.trae/skills/`      |
+| `other`               | AGENTS.md    | `.agents/skills/`    |
+| _(any unknown value)_ | AGENTS.md    | `.agents/skills/`    |
+
+### Resolution rules
+
+**Deduplication:** When multiple IDE entries map to the same context file, deduplicate so each context file is processed exactly once. Use the **first configured IDE's** skill root for that context file's snippet root paths. Report the deduplication to the user: "Multiple IDEs target AGENTS.md — using {first IDE}'s skill root (`{skill_root}`). Each IDE's skills are installed to its own directory."
+
+**Missing `ides` key:** If the `ides` key is absent from `config.yaml`, treat it as an empty list. If the resulting set is empty (no recognized entries), fall back to AGENTS.md with `.agents/skills/` as the skill root.
+
+**Unknown IDE values:** Warn: "Unknown IDE '{value}' in config.yaml — defaulting to AGENTS.md with `.agents/skills/`"
+
+**`snippet_skill_root_override` (optional):** Authoring repos where all skills live under one shared on-disk directory (e.g. `skills/`) that does not match any per-IDE skill root may set `snippet_skill_root_override: skills/` in `config.yaml`. When set:
+
+- `export-skill/step-03` §2.7 uses the override as `{skill_root}` for snippet generation instead of the IDE-mapped value
+- `export-skill/step-04` §4d (and its equivalents in `drop-skill/step-02` and `rename-skill/step-02`) skip the prefix rewrite for any snippet whose current prefix already equals the override — the managed section will reference the on-disk location instead of a per-IDE directory that does not exist
+
+Consuming projects (the common case) omit the field and keep the default IDE-mapping behavior. The override is a narrow escape hatch for repos that author skills into `{skills_output_folder}` and never duplicate them into `.claude/skills/`-style directories.
+
+### Consumers
+
+This mapping is the single source of truth. Workflows that need it: `export-skill/step-01` (resolves `target_context_files` from config.yaml IDE list), `export-skill/step-04` (applies four-case logic and rewrites root paths when writing managed sections), `drop-skill/step-02` and `rename-skill/step-02` (rebuild context files after a management operation).
+
+## Four-Case Logic
+
+### Case 1: Create (No File Exists)
+
+Target file does not exist. Create new file with managed section only.
+
+```markdown
+<!-- SKF:BEGIN updated:{date} -->
+{managed section content}
+<!-- SKF:END -->
+```
+
+### Case 2: Append (File Exists, No Section)
+
+Target file exists but contains no `<!-- SKF:BEGIN` marker. Append managed section at end of file.
+
+1. Read existing file content
+2. Append two blank lines
+3. Append managed section with markers
+4. Write file
+
+### Case 3: Regenerate (Existing Section)
+
+Target file contains `<!-- SKF:BEGIN` and `<!-- SKF:END -->` markers. Replace content between markers.
+
+1. Read existing file content
+2. Find `<!-- SKF:BEGIN` line (preserve everything before it)
+3. Find `<!-- SKF:END -->` line (preserve everything after it)
+4. Replace everything between markers (inclusive) with new managed section
+5. Write file
+
+### Case 4: Malformed Markers (Halt)
+
+Target file contains `<!-- SKF:BEGIN` but no matching `<!-- SKF:END -->` marker. This indicates a corrupted managed section.
+
+1. Halt workflow with error: "Malformed managed section — `<!-- SKF:BEGIN` found but no `<!-- SKF:END -->`. Fix the markers manually before re-running export."
+2. Do not modify the file
+
+## Regeneration: Full Index Rebuild
+
+When regenerating (Case 3) or creating/appending (Cases 1-2), rebuild the skill index from the **exported skill set** only:
+
+1. Read `{skills_output_folder}/.export-manifest.json` (v2 schema — see `knowledge/version-paths.md`) to determine which skills have been explicitly exported and their `active_version` (if no manifest exists, only the current export target qualifies)
+2. For each skill in the exported set, resolve the snippet at `{skills_output_folder}/{skill-name}/{active_version}/{skill-name}/context-snippet.md` (i.e., `{skill_package}/context-snippet.md`). Do NOT use glob patterns across version directories — always resolve via manifest `active_version` or `active` symlink
+3. Count total skills and stack skills (from filtered set only)
+4. Assemble filtered snippets into managed section
+5. Sort alphabetically by skill name
+6. Update the header line with correct counts
+
+**Rationale:** create-skill and update-skill also write `context-snippet.md` as a build artifact, but only export-skill is the publishing gate (ADR-K). The `.export-manifest.json` file tracks which skills have passed through export-skill, preventing draft skills from leaking into the agent's passive context.
+
+## Safety Rules
+
+- NEVER modify content outside the `<!-- SKF:BEGIN/END -->` markers
+- ALWAYS preserve existing file content above and below markers
+- ALWAYS verify file was written correctly after write
+- If write fails, report error — do not attempt partial writes

package/src/{workflows/export-skill/data → skf-export-skill/assets}/snippet-format.md

@@ -1,21 +1,17 @@
 # Context Snippet Format (Vercel-Aligned Indexed Format)
 
-## Platform Root Path Mapping
+## Skill Root Path
 
-The snippet `root:` path must reflect the platform-specific skills directory:
+The snippet `root:` path must reflect the IDE's actual skill directory — its `skill_root` from the IDE → Context File Mapping table in `managed-section-format.md`. Each IDE has its own skill directory (e.g., `.claude/skills/`, `.windsurf/skills/`, `.github/skills/`).
 
-| Platform | Root Path Prefix |
-|----------|-----------------|
-| `claude` | `.claude/skills/` |
-| `cursor` | `.cursor/skills/` |
-| `copilot` | `.agents/skills/` |
+The root path in context-snippet.md on disk uses the **`skill_root` of the first entry in `target_context_files`** (resolved in step-01 from config.yaml IDE mapping). When assembling managed sections for other context files, step-04 rewrites root paths to match the target context file's skill root.
 
-The root path in context-snippet.md on disk uses the **first platform in `target_platforms`** (the first entry from config.yaml IDE mapping, or the explicit `--platform` flag value if provided). When assembling managed sections for other platforms, step-04 rewrites root paths to match the target platform.
+**Authoring-repo override:** If `snippet_skill_root_override` is set in `config.yaml`, it replaces the IDE-mapped value for snippet generation and freezes matching prefixes against step-04 rewrites. See the "Resolution rules" section in `managed-section-format.md` for the full semantics.
 
 ## Format Rules
 
 - Indexed pipe-delimited format per skill — retrieval instruction + file map + inline gotchas
-- ~80-120 tokens per skill target (up from ~50-80, justified by Vercel research)
+- ~80-120 tokens per skill target (up from ~50-80, justified by Vercel research). Deep tier may exceed 120 tokens when gotchas are load-bearing (substantive breaking-change notices, deprecated-API lists); the hard ceiling is 300 tokens.
 - T1-now content only (AST-current, no annotations)
 - Line 2 (IMPORTANT) is the RETRIEVAL INSTRUCTION — always present, tells agent to read SKILL.md
 - Section anchors (`#quick-start`, `#key-types`) must match actual SKILL.md heading slugs
@@ -25,7 +21,7 @@ The root path in context-snippet.md on disk uses the **first platform in `target
 ## Single Skill Snippet Template
 
 ```markdown
-[{skill-name} v{version}]|root: {platform_root}{skill-name}/
+[{skill-name} v{version}]|root: {skill_root}{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#quick-start}
 |api: {top exports with () for functions, comma-separated}
@@ -43,7 +39,7 @@ The root path in context-snippet.md on disk uses the **first platform in `target
 ## Stack Skill Snippet Template
 
 ```markdown
-[{project}-stack v{version}]|root: {platform_root}{project}-stack/
+[{project}-stack v{version}]|root: {skill_root}{project}-stack/
 |IMPORTANT: {project}-stack — read SKILL.md before writing integration code. Do NOT rely on training data.
 |stack: {dep-1}@{v1}, {dep-2}@{v2}, {dep-3}@{v3}
 |integrations: {pattern-1}, {pattern-2}
@@ -60,4 +56,4 @@ The root path in context-snippet.md on disk uses the **first platform in `target
 - If fewer exports than the limit, list all available
 - If no exports data available, omit the api line
 - Section anchors must be verified against actual SKILL.md headings during generation. For split-body skills (where `references/` exists and `## Full` headings are stubs), if a heading is missing from SKILL.md, rewrite the anchor to point to the reference file path (preferred). Omit the anchor line only if the heading cannot be found in either SKILL.md or `references/*.md`
-- Skill path is relative to project root and uses the platform-specific root prefix (see Platform Root Path Mapping above)
+- Skill path is relative to project root and uses the IDE's `skill_root` prefix (see **Skill Root Path** above, and the IDE → Context File Mapping table in `managed-section-format.md`)

package/src/skf-export-skill/steps-c/step-01-load-skill.md

@@ -0,0 +1,247 @@
+---
+nextStepFile: './step-02-package.md'
+---
+
+# Step 1: Load Skill
+
+## STEP GOAL:
+
+To load the target skill's artifacts, validate they meet agentskills.io spec compliance, parse export flags, and confirm with the user before proceeding to packaging.
+
+## Rules
+
+- Focus only on loading, validating, and confirming the skill — this is read-only
+- Do not write any output files yet (packaging starts in Step 02)
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Parse Export Arguments
+
+"**Starting skill export...**"
+
+Determine the skill(s) to export and any flags:
+
+**Skill Path Discovery (version-aware — see `knowledge/version-paths.md`):**
+- If user provided one or more skill names or paths as arguments, use that list directly
+- If `--all` was passed, build the list from every skill in `{skills_output_folder}/.export-manifest.json.exports` whose `active_version` entry is not `status: "deprecated"` (deprecated skills are excluded from all exports — see step-04 §4b)
+- If no explicit skill and no `--all`, discover available skills using the export manifest:
+  1. Read `{skills_output_folder}/.export-manifest.json` — list skill names from `exports`
+  2. For each skill group directory in `{skills_output_folder}/`, check for `{skill_group}/active/{skill-name}/SKILL.md`
+  3. If neither manifest nor `active` symlink yields results, fall back to flat path: `{skills_output_folder}/{skill-name}/SKILL.md`
+- If multiple skills are found, present the list and accept either a single selection or a comma-/space-separated multi-selection (e.g. `1, 2, 3` or `all`)
+- If no skills found, halt: "No skills found in {skills_output_folder}/. Run create-skill first."
+
+Store the resolved selection as `skill_batch` — a list of one or more skill names. `len(skill_batch) > 1` activates multi-skill mode (see §1c below).
+
+**Flag Parsing:**
+- `--all` flag: Check if provided. When true and no explicit skill list was given, `skill_batch` is the full non-deprecated manifest set (see above).
+- `--context-file` flag: Check if explicitly provided (CLAUDE.md, .cursorrules, or AGENTS.md). Replaces the old `--platform` flag.
+- `--dry-run` flag: Check if provided. Default: `false`
+
+**Context File Resolution:**
+
+If `--context-file` is explicitly provided, use that single context file as the sole target. Determine the skill root from the first configured IDE that maps to that context file (or `.agents/skills/` for AGENTS.md if no matching IDE is configured). If other IDEs are configured in config.yaml, emit a note: "**Note:** Exporting to {context-file} only. config.yaml also lists: {other-ides}. Run without `--context-file` to export to all configured IDEs."
+
+If `--context-file` is NOT provided, read the `ides` list from config.yaml and map each IDE to its context file and skill root using the "IDE → Context File Mapping" table in `skf-export-skill/assets/managed-section-format.md`. Every IDE the installer offers has an explicit mapping — no silent skips.
+
+For each IDE in `config.yaml.ides`:
+
+1. Look up its `context_file` and `skill_root` from the canonical mapping table
+2. If the IDE is not in the table, default to AGENTS.md / `.agents/skills/` and warn: "Unknown IDE '{value}' in config.yaml — defaulting to AGENTS.md with `.agents/skills/`"
+
+**Deduplication:** Group by `context_file`. When multiple IDE entries map to the same context file (e.g. both `codex` and `cline` map to AGENTS.md), deduplicate so each context file appears in `target_context_files` only once. Use the **first configured IDE's** `skill_root` for that context file. Report the deduplication: "Multiple IDEs target AGENTS.md — using {first-ide}'s skill root (`{skill_root}`). Each IDE's skills are installed to its own directory."
+
+**Missing-key handling:** If the `ides` key is absent from config.yaml (older installation or manually edited file), treat it as an empty list.
+
+- If mapping produces one or more context files (after dedup), store as `target_context_files` list — each entry has `{context_file, skill_root}`
+- If mapping produces zero entries (empty ides list and no recognized entries), fall back to `[{context_file: "AGENTS.md", skill_root: ".agents/skills/"}]` with note: "No IDEs configured in config.yaml — defaulting to AGENTS.md with `.agents/skills/`."
+
+"**Skill(s):** {skill-batch-list} ({N} total)
+**Context file(s):** {context-file-list} (skill root: {skill-root-list})
+**Dry Run:** {yes/no}"
+
+### 1b. Detect Snippet Root Prefix Mismatch
+
+**Skip entirely if `snippet_skill_root_override` is already set in `config.yaml`** — the authoring-repo escape hatch is already configured and any on-disk prefix that matches it is ground truth (see `assets/managed-section-format.md` override rules).
+
+Otherwise, probe existing snippets to catch the authoring-repo case (skills live under a single shared directory like `skills/` that does not match any per-IDE `skill_root`) before step-04 silently rewrites their root paths:
+
+1. Collect candidate snippet paths:
+   - Read `{skills_output_folder}/.export-manifest.json` if it exists. For each skill in `exports` with a resolvable `active_version`, add `{skills_output_folder}/{skill-name}/{active_version}/{skill-name}/context-snippet.md`
+   - Also include the current skill's snippet if present (resolved via manifest / `active` symlink / flat path per `knowledge/version-paths.md`)
+2. For each snippet that exists on disk, read the first line and parse the `root:` value. Strip the trailing `{skill-name}/` to extract the prefix (e.g. `skills/`, `.claude/skills/`)
+3. Collect unique prefixes into `observed_prefixes`
+4. Compare against `target_context_files[0].skill_root` (the first entry's IDE-mapped skill root — used as reference since step-03 §2.7 picks this same entry for snippet generation when no override is set)
+
+**If `observed_prefixes` contains any value that does not match the reference `skill_root`:**
+
+Emit a single warning (once, not per snippet) and present resolution options before proceeding:
+
+"**Snippet root prefix mismatch detected.**
+Existing snippets use: `{observed_prefixes}`
+IDE-mapped skill_root:  `{target_context_files[0].skill_root}`
+
+This usually means you are in an authoring repo where skills live under a single shared directory. Options:
+- **(a) Set override** — add `snippet_skill_root_override: {observed_prefix}` to `config.yaml`. Snippets keep their on-disk prefix; the managed section references the real location.
+- **(b) Proceed with IDE mapping** — step-04 will rewrite every snippet's root path to the IDE's skill_root. Use this only if the IDE's skill directory actually contains the skill files.
+- **(c) Cancel** — abort export and investigate.
+
+If multiple distinct prefixes were observed, the snippets disagree with each other — investigate before choosing (a)."
+
+In `{headless_mode}`, default to (b) and log the observed prefix(es) so the mismatch is visible in run logs. In interactive mode, wait for user choice before continuing to section 2.
+
+**If all observed prefixes match the reference `skill_root` (or no existing snippets were found):** Proceed silently.
+
+### 1c. Multi-skill Mode (when `len(skill_batch) > 1`)
+
+When multiple skills are being exported in a single run (via `--all`, multi-selection at the discovery menu, or an explicit multi-argument invocation), the workflow does NOT loop the full step-01→step-07 sequence once per skill. Instead, it partitions work across steps to avoid repeated gates and redundant batch work:
+
+| Step | Behavior in multi-skill mode |
+|------|------------------------------|
+| step-01 §2–5 | **Iterate per skill** — load, validate, read metadata, and check the test report for every skill in `skill_batch`. Collect per-skill results. |
+| step-01 §6 | **Single gate** — present one consolidated summary table (one row per skill) and a single [C] gate for the whole batch. |
+| step-02 | **Iterate per skill** — validate each skill's package structure and collect per-skill readiness. |
+| step-03 | **Iterate per skill** — regenerate each skill's `context-snippet.md` independently (each skill has its own prior-gotchas carry-forward state). |
+| step-04 | **Batch once** — §3b orphan detection, §4 skill-index rebuild, §5 managed-section assembly, and §6–9 diff + write all execute once for the entire batch. The exported skill set in §4b already enumerates every skill in the manifest — it does not need per-skill iteration. §9b adds/updates a manifest entry per skill in `skill_batch` (not just the last one), then writes the manifest once. |
+| step-05 | **Iterate per skill** — compute token counts per skill, then present one aggregate report. |
+| step-06 | **One batch summary + one result contract** — the files-written table lists every skill; the result contract JSON covers the whole run, and `outputs` enumerates every context-snippet + target context file touched. |
+| step-07 | **Runs once** — health check is per-workflow-run, not per-skill. |
+
+**Halt semantics in batch mode:** if any single skill fails validation in §2 (required-file or metadata-field failure), halt the entire batch before §5 — do not partially export. Report which skill failed and why.
+
+**Single-skill mode (`len(skill_batch) == 1`)** preserves the legacy behavior: every section below operates on the one skill without iteration.
+
+### 2. Load and Validate Skill Artifacts
+
+Resolve the skill's versioned path before loading artifacts:
+
+1. Read `{skills_output_folder}/.export-manifest.json` and look up `{skill-name}` in `exports` to get `active_version`
+2. If found: resolve to `{skill_package}` = `{skills_output_folder}/{skill-name}/{active_version}/{skill-name}/`
+3. If not in manifest: check for `active` symlink at `{skills_output_folder}/{skill-name}/active` — resolve to `{skill_group}/active/{skill-name}/`
+4. If neither: fall back to flat path `{skills_output_folder}/{skill-name}/`. If SKILL.md exists at the flat path, auto-migrate per `knowledge/version-paths.md` migration rules
+5. Store the resolved path as `{resolved_skill_package}` for all subsequent artifact loading
+
+Load all files from `{resolved_skill_package}`:
+
+**Required Files (hard halt if missing):**
+- `SKILL.md` — The main skill document
+- `metadata.json` — Machine-readable skill metadata
+
+**Optional Files (note presence):**
+- `references/` — Progressive disclosure directory
+- `context-snippet.md` — Existing snippet (will be regenerated)
+
+**Validation Checks:**
+1. `SKILL.md` exists and is non-empty
+2. `metadata.json` exists and is valid JSON
+3. `metadata.json` contains required fields: `name`, `version`, `skill_type`, `source_authority`, `exports`, `generation_date`, `confidence_tier`
+4. `metadata.json.exports` is a non-empty array (warn if empty — graceful handling)
+
+**If any required validation fails:**
+"**Export cannot proceed.** Missing or invalid: {list failures}
+Run create-skill to generate a complete skill first."
+
+### 3. Read Skill Metadata
+
+Extract from `metadata.json`:
+- `name` — Skill display name
+- `skill_type` — `single` or `stack`
+- `source_authority` — `official`, `internal`, or `community`
+- `exports` — Array of exported functions/types
+- `generation_date` — When the skill was last generated
+- `confidence_tier` — Quick/Forge/Forge+/Deep
+
+**For stack skills, also extract:**
+- `components` — Array of dependencies with versions
+- `integrations` — Array of co-import patterns
+
+### 4. Check Forge Configuration
+
+Load `{sidecar_path}/preferences.yaml` (if exists):
+- Check `passive_context` setting
+- If `passive_context: false` — note that steps 03-04 (snippet + context update) will be skipped
+
+### 4b. Check Test Report (Quality Gate)
+
+Search for a test report at `{forge_data_folder}/{skill_name}/{active_version}/test-report-{skill_name}.md` (i.e., `{forge_version}/test-report-{skill_name}.md`). If not found at the versioned path, fall back to `{forge_data_folder}/{skill_name}/test-report-{skill_name}.md`:
+
+**If test report found:**
+- Read frontmatter `testResult` and `score`
+- If `testResult: fail`: warn: "**Warning:** This skill failed its last test (score: {score}%). Consider running `@Ferris TS` and addressing gaps before export."
+- If `testResult: pass`: note: "Last test: **PASS** ({score}%)"
+
+**If no test report found:**
+- Warn: "**Note:** No test report found for this skill. Consider running `@Ferris TS` before export to verify completeness."
+
+Continue to step 5 regardless — this is advisory, not blocking.
+
+### 5. Present Skill Summary
+
+**Single-skill mode:**
+
+"**Skill loaded and validated.**
+
+| Field | Value |
+|-------|-------|
+| **Name** | {name} |
+| **Type** | {skill_type} |
+| **Authority** | {source_authority} |
+| **Confidence** | {confidence_tier} |
+| **Exports** | {count} functions/types |
+| **Generated** | {generation_date} |
+| **References** | {count files or 'none'} |
+
+**Export Configuration:**
+| Setting | Value |
+|---------|-------|
+| **Context File(s)** | {context-file-list} (skill root: {skill-root-list}) |
+| **Explicit --context-file** | {yes (user-specified) / no (from config.yaml)} |
+| **Dry Run** | {yes/no} |
+| **Passive Context** | {enabled/disabled} |
+
+**Top Exports:**
+{list top 5 exports from metadata}
+
+**Is this the correct skill to export?**"
+
+**Multi-skill mode** (`len(skill_batch) > 1`):
+
+"**{N} skills loaded and validated.**
+
+| # | Name | Type | Authority | Tier | Exports | Test |
+|---|------|------|-----------|------|---------|------|
+| 1 | {name-1} | {type} | {authority} | {tier} | {count} | {pass/fail/none} |
+| 2 | {name-2} | ... | ... | ... | ... | ... |
+| N | {name-N} | ... | ... | ... | ... | ... |
+
+**Export Configuration (applies to all):**
+| Setting | Value |
+|---------|-------|
+| **Context File(s)** | {context-file-list} (skill root: {skill-root-list}) |
+| **Explicit --context-file** | {yes / no (from config.yaml)} |
+| **Dry Run** | {yes/no} |
+| **Passive Context** | {enabled/disabled} |
+
+**Are these the correct skills to export?**"
+
+### 6. Present MENU OPTIONS
+
+Display: "**Select:** [C] Continue to packaging" (multi-skill mode: the single [C] gate covers the whole batch)
+
+#### Menu Handling Logic:
+
+- IF C: Proceed with loaded skill data, then load, read entire file, then execute {nextStepFile}
+- IF Any other: help user respond, then [Redisplay Menu Options](#6-present-menu-options)
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- **GATE [default: C]** — If `{headless_mode}`: auto-proceed with [C] Continue, log: "headless: auto-continue past skill confirmation"
+- ONLY proceed to next step when user selects 'C'
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN the user confirms the correct skill is loaded by selecting 'C' will you load and read fully `{nextStepFile}` to execute packaging.
+

package/src/{workflows/export-skill → skf-export-skill}/steps-c/step-02-package.md

@@ -1,7 +1,4 @@
 ---
-name: 'step-02-package'
-description: 'Build agentskills.io-compliant package structure from skill artifacts'
-
 nextStepFile: './step-03-generate-snippet.md'
 ---
 
@@ -11,40 +8,11 @@ nextStepFile: './step-03-generate-snippet.md'
 
 To assemble and validate an agentskills.io-compliant package structure from the loaded skill artifacts, ensuring all required components are present and properly formatted for distribution.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
-
-### Role Reinforcement:
-
-- ✅ You are a delivery and packaging specialist in Ferris Delivery mode
-- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
-- ✅ Precise validation — ensure package meets ecosystem standards
-
-### Step-Specific Rules:
-
-- 🎯 Focus only on package structure assembly and validation
-- 🚫 FORBIDDEN to modify SKILL.md content — package what exists
-- 💬 This is a deterministic packaging step — auto-proceed when complete
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Follow the MANDATORY SEQUENCE exactly
-- 💾 Hold validated package structure in context for subsequent steps
-- 📖 Validate all required agentskills.io fields
-- 🚫 Warn on non-critical issues but do not halt
+## Rules
 
-## CONTEXT BOUNDARIES:
-
-- Available: Skill metadata, SKILL.md, metadata.json from step-01
-- Focus: Package structure validation and assembly
-- Limits: Do not modify source files — validate and assemble only
-- Dependencies: Step-01 must have loaded and validated the skill
+- Focus only on package structure assembly and validation — do not modify SKILL.md content
+- Auto-proceed when complete
+- **Multi-skill mode:** when step-01 loaded more than one skill (`len(skill_batch) > 1`), iterate sections 1–4 below per skill using each skill's `{resolved_skill_package}`. Collect per-skill status; report the aggregate in §4 as one row per skill. Halt the batch if any skill is NOT READY. See step-01 §1c.
 
 ## MANDATORY SEQUENCE
 
@@ -52,7 +20,7 @@ To assemble and validate an agentskills.io-compliant package structure from the
 
 ### 1. Validate Package Structure
 
-Verify the skill package at `{resolved_skill_package}` (resolved in step-01 via manifest or `active` symlink — see [knowledge/version-paths.md](../../../knowledge/version-paths.md)) contains the expected agentskills.io package layout:
+Verify the skill package at `{resolved_skill_package}` (resolved in step-01 via manifest or `active` symlink — see `knowledge/version-paths.md`) contains the expected agentskills.io package layout:
 
 ```
 {skill_package} = {skills_output_folder}/{skill-name}/{version}/{skill-name}/
@@ -134,24 +102,3 @@ Display: "**Proceeding to snippet generation...**"
 
 ONLY WHEN package validation is complete will you load and read fully `{nextStepFile}` to execute snippet generation.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- All required package components validated
-- All required metadata.json fields checked
-- Warnings noted for missing recommended fields
-- Package status clearly reported
-- Auto-proceed to step-03
-
-### ❌ SYSTEM FAILURE:
-
-- Not checking all required files
-- Not validating metadata.json fields
-- Halting on non-critical warnings (should warn and continue)
-- Modifying any source files
-- Not auto-proceeding after validation
-
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.