bmad-module-skill-forge 0.8.4 → 0.10.0

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

@@ -59,23 +59,59 @@ To load the target skill's artifacts, validate they meet agentskills.io spec com
 
 Determine the skill to export and any flags:
 
-**Skill Path Discovery:**
+**Skill Path Discovery (version-aware — see [knowledge/version-paths.md](../../../knowledge/version-paths.md)):**
 - If user provided a skill name or path as argument, use that
-- If not provided, search `{skills_output_folder}/*/SKILL.md` for available skills
+- If not provided, 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 found, present list and ask user to select
 - If no skills found, halt: "No skills found in {skills_output_folder}/. Run create-skill first."
 
 **Flag Parsing:**
-- `--platform` flag: Check if provided (claude/cursor/copilot). Default: `claude`
+- `--platform` flag: Check if explicitly provided (claude/cursor/copilot)
 - `--dry-run` flag: Check if provided. Default: `false`
 
+**Platform Resolution:**
+
+If `--platform` is explicitly provided, use that single platform as the sole target. If other IDEs are configured in config.yaml, emit a note: "**Note:** Exporting to {platform} only. config.yaml also lists: {other-ides}. Run without `--platform` to export to all configured IDEs."
+
+If `--platform` is NOT provided, read the `ides` list from config.yaml and map each IDE to a target platform. Every IDE the installer offers has an explicit mapping — no silent skips.
+
+| config.yaml IDE value | Platform | Rationale |
+|----------------------|----------|-----------|
+| `claude-code` | `claude` | native — reads `CLAUDE.md` and `.claude/skills/` |
+| `cursor` | `cursor` | native — reads `.cursorrules` and `.cursor/skills/` |
+| `github-copilot` | `copilot` | native — reads `AGENTS.md` and `.agents/skills/` |
+| `codex` | `copilot` | OpenAI Codex reads `AGENTS.md` (same convention as copilot) |
+| `cline` | `copilot` | uses `AGENTS.md` as a fallback context file |
+| `roo` | `copilot` | uses `AGENTS.md` as a fallback context file |
+| `windsurf` | `copilot` | uses `AGENTS.md` as a fallback context file |
+| `other` | `copilot` | generic AGENTS.md fallback |
+| Any other value | `copilot` | warn: "Unknown IDE '{value}' in config.yaml — defaulting to copilot (AGENTS.md)" |
+
+When the same platform is produced by multiple IDE entries (e.g. both `codex` and `cline` map to `copilot`), deduplicate so each platform appears in `target_platforms` only once. Report the deduplication: "Multiple IDEs target the same platform — exporting to {platform} once."
+
+**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 platforms (after dedup), store as `target_platforms` list
+- If mapping produces zero platforms (empty ides list and no recognized entries), fall back to `["copilot"]` with note: "No IDEs configured in config.yaml — defaulting to copilot (AGENTS.md / .agents/skills/)."
+
 "**Skill:** {skill-name}
-**Platform:** {platform} ({target-file})
+**Platform(s):** {platform-list} ({target-file-list})
 **Dry Run:** {yes/no}"
 
 ### 2. Load and Validate Skill Artifacts
 
-Load all files from the skill directory `{skills_output_folder}/{skill-name}/`:
+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
@@ -117,7 +153,7 @@ Load `{sidecar_path}/preferences.yaml` (if exists):
 
 ### 4b. Check Test Report (Quality Gate)
 
-Search for a test report at `{forge_data_folder}/{skill_name}/test-report-{skill_name}.md`:
+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`
@@ -146,7 +182,8 @@ Continue to step 5 regardless — this is advisory, not blocking.
 **Export Configuration:**
 | Setting | Value |
 |---------|-------|
-| **Platform** | {platform} → {target-file} |
+| **Platform(s)** | {platform-list} → {target-file-list} |
+| **Explicit --platform** | {yes (user-specified) / no (from config.yaml)} |
 | **Dry Run** | {yes/no} |
 | **Passive Context** | {enabled/disabled} |
 
@@ -183,6 +220,7 @@ ONLY WHEN the user confirms the correct skill is loaded by selecting 'C' will yo
 - All required files loaded and validated
 - metadata.json parsed with required fields
 - Export flags parsed (platform, dry-run)
+- config.yaml ides list consumed for multi-platform resolution when --platform not provided
 - Forge config checked for passive_context
 - Clear summary presented to user
 - User confirms correct skill
@@ -193,6 +231,7 @@ ONLY WHEN the user confirms the correct skill is loaded by selecting 'C' will yo
 - Not validating metadata.json fields
 - Not checking preferences.yaml for passive_context opt-out
 - Proceeding without user confirmation
+- Ignoring config.yaml ides list when no --platform flag is provided
 - Modifying any skill files (read-only step)
 
 **Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/workflows/export-skill/steps-c/step-02-package.md

@@ -52,10 +52,10 @@ To assemble and validate an agentskills.io-compliant package structure from the
 
 ### 1. Validate Package Structure
 
-Verify the skill directory 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](../../../knowledge/version-paths.md)) contains the expected agentskills.io package layout:
 
 ```
-{skills_output_folder}/{skill-name}/
+{skill_package} = {skills_output_folder}/{skill-name}/{version}/{skill-name}/
 ├── SKILL.md              ← Required: Active skill document
 ├── metadata.json         ← Required: Machine-readable metadata
 ├── context-snippet.md    ← Will be generated/updated in step-03

package/src/workflows/export-skill/steps-c/step-03-generate-snippet.md

@@ -66,6 +66,30 @@ Auto-proceed immediately to {nextStepFile}.
 
 Load {snippetFormatData} and read the format template for the skill type.
 
+### 2.5. Check Existing Snippet
+
+Before generating new snippet content, check for a prior snippet:
+
+1. Read `{resolved_skill_package}/context-snippet.md` if it exists (resolved in step-01 — see [knowledge/version-paths.md](../../../knowledge/version-paths.md))
+2. If it exists, extract the `|gotchas:` line (if any). Trim leading whitespace and the `|gotchas:` prefix, then capture the remaining content as `prior_gotchas_content`.
+3. **Detect the carry-forward marker:** If `prior_gotchas_content` starts with the token `[CARRIED]` (whitespace-insensitive), set `prior_gotchas_already_carried = true` and strip the marker before storing the remainder. Otherwise set `prior_gotchas_already_carried = false`.
+4. **Distinguish empty from absent:** If the `|gotchas:` line exists but has no non-whitespace content after the prefix, treat it as **absent** — set `prior_gotchas = null`. Only a non-empty value counts as a prior gotchas line worth carrying forward.
+5. If no prior snippet exists at all, set `prior_gotchas = null` and `prior_gotchas_already_carried = false`.
+
+These values will be used as a fallback in section 3 if new gotchas cannot be derived. The `[CARRIED]` marker provides a **hard one-cycle expiry**: gotchas that were already carried once will be dropped on the next carry-forward attempt rather than preserved indefinitely.
+
+### 2.7. Resolve Platform Root Path
+
+Using the first platform in `target_platforms` (resolved in step-01), resolve the root path prefix:
+
+| Platform | `{platform_root}` |
+|----------|-------------------|
+| `claude` | `.claude/skills/` |
+| `cursor` | `.cursor/skills/` |
+| `copilot` | `.agents/skills/` |
+
+Store `{platform_root}` for use in snippet generation. The context-snippet.md written to disk uses this platform's root path.
+
 ### 3. Generate Snippet Content
 
 **For single skills (`skill_type: "single"`):**
@@ -74,11 +98,15 @@ Load {snippetFormatData} and read the format template for the skill type.
 2. Select top exports (up to 10 for Deep tier, 5 otherwise). Append `()` to function names.
 3. Read SKILL.md to extract: heading slugs for `#quick-start` and `#key-types`, inline summary of key types (~10 words)
 4. **Anchor verification (split-body awareness):** For each section anchor (`#quick-start`, `#key-types`), verify the heading exists in SKILL.md. If a `references/` directory exists and `## Full` headings in SKILL.md are absent or stubs (indicating split-body, not a stack skill's structural references), rewrite the anchor to point to the reference file path (e.g., `references/{file}.md#key-types`). If the heading cannot be resolved in either location, omit that anchor line from the snippet.
-5. Derive gotchas from: T2-future annotations in evidence report (breaking changes), async requirements, version-specific behavior. If no gotchas, omit the gotchas line.
+5. Derive gotchas from: T2-future annotations in evidence report (breaking changes), async requirements, version-specific behavior.
+   - **If new gotchas are derived:** Use them (they supersede any prior gotchas). Write as `|gotchas: {pitfall-1}, {pitfall-2}` with no marker.
+   - **If NO new gotchas are derived BUT `prior_gotchas` exists AND `prior_gotchas_already_carried == false`:** First carry-forward cycle — preserve the prior gotchas line, prefixing the value with `[CARRIED]` so the next export can detect that expiry has been reached. Write as `|gotchas: [CARRIED] {prior gotchas content}`. Emit warning: "**Gotchas preserved from prior export (one-cycle carry-forward).** These gotchas will be DROPPED on the next export unless new gotchas are derived or you manually refresh them. Review now if they are still applicable."
+   - **If NO new gotchas are derived AND `prior_gotchas` exists AND `prior_gotchas_already_carried == true`:** Expiry reached — drop the gotchas line entirely. Emit warning: "**Stale gotchas dropped** — the prior gotchas were already carried forward once and cannot be derived from the current evidence report. The snippet now has no gotchas line. If the prior gotchas are still relevant, re-add them to the evidence report's T2-future section and re-run export."
+   - **If NO new gotchas derived AND no `prior_gotchas`:** Omit the gotchas line.
 
 Generate:
 ```
-[{skill-name} v{version}]|root: skills/{skill-name}/
+[{skill-name} v{version}]|root: {platform_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: {export-1}(), {export-2}(), {export-3}, {export-4}(), {export-5}
@@ -88,19 +116,21 @@ Generate:
 
 **If fewer exports than limit:** List all available.
 **If no exports:** Omit the api line.
-**If no gotchas derivable:** Omit the gotchas line.
+**If no gotchas derivable AND no prior gotchas to carry forward:** Omit the gotchas line.
 
 **For stack skills (`skill_type: "stack"`):**
 
 Generate:
 ```
-[{project}-stack v{version}]|root: skills/{project}-stack/
+[{project}-stack v{version}]|root: {platform_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}
 |gotchas: {pitfall-1}, {pitfall-2}
 ```
 
+**Stack skill gotchas carry-forward:** Same one-cycle expiry logic as single skills. If no new gotchas derived and `prior_gotchas_already_carried == false`, preserve with the `[CARRIED]` prefix. If already carried once (`prior_gotchas_already_carried == true`), drop the line and warn loudly. See the single-skill steps for the complete protocol.
+
 ### 4. Verify Token Count
 
 Estimate token count of generated snippet (approximate: words * 1.3).
@@ -114,7 +144,7 @@ Estimate token count of generated snippet (approximate: words * 1.3).
 **If dry-run mode:**
 
 "**[DRY RUN] context-snippet.md would be written to:**
-`{skills_output_folder}/{skill-name}/context-snippet.md`
+`{resolved_skill_package}/context-snippet.md`
 
 **Content:**
 ```
@@ -127,10 +157,10 @@ Hold content in context for step-04.
 
 **If NOT dry-run:**
 
-Write the generated content to `{skills_output_folder}/{skill-name}/context-snippet.md`.
+Write the generated content to `{resolved_skill_package}/context-snippet.md`.
 
 "**context-snippet.md written.**
-**Path:** `{skills_output_folder}/{skill-name}/context-snippet.md`
+**Path:** `{resolved_skill_package}/context-snippet.md`
 **Estimated tokens:** {count}"
 
 ### 6. Proceed to Context Update
@@ -162,10 +192,12 @@ ONLY WHEN snippet generation is complete (or skipped due to passive_context opt-
 - Token count estimated and within target
 - File written (or previewed in dry-run)
 - Passive context opt-out correctly handled (skip when disabled)
+- Prior gotchas checked and carried forward when new derivation yields nothing (with warning)
 - Auto-proceed to step-04
 
 ### ❌ SYSTEM FAILURE:
 
+- Silently dropping prior gotchas without checking for carry-forward
 - Deviating from Vercel-aligned indexed format
 - Including T2 annotations or temporal context
 - Not checking passive_context setting

package/src/workflows/export-skill/steps-c/step-04-update-context.md

@@ -69,27 +69,155 @@ Auto-proceed immediately to {nextStepFile}.
 
 Load {managedSectionData} and read the complete format template and three-case logic.
 
-### 3. Determine Target File
+### 3. Determine Target File(s)
 
-Based on the `--platform` flag parsed in step-01:
+Using the `target_platforms` list resolved in step-01, determine all target files:
 
 | Platform | Target File |
 |----------|-------------|
-| `claude` (default) | CLAUDE.md |
+| `claude` | CLAUDE.md |
 | `cursor` | .cursorrules |
 | `copilot` | AGENTS.md |
 
-Resolve target file path at project root: `{project-root}/{target-file}`
+For each platform in `target_platforms`, resolve target file path: `{project-root}/{target-file}`
+
+**If multiple platforms:** Sections 4-9a execute as a loop — one full pass per target platform. Each iteration uses the same skill index but rewrites root paths per platform (section 4d) and writes to the platform-specific target file. Section 9b executes once after all iterations complete.
+
+**Processing order:** Process platforms in the order listed in `target_platforms`.
+
+#### 3b. Detect Orphaned Platform Files (Stale Managed Sections)
+
+A platform file becomes orphaned when its IDE is removed from `config.yaml` after a prior export. The file still contains an SKF managed section pointing to stale skill versions, but no future export will rewrite it.
+
+Build `orphaned_platform_files` — the set of platform context files that exist on disk with an `<!-- SKF:BEGIN -->` marker but whose platform is NOT in the current `target_platforms` list:
+
+1. For each platform in the full set `{claude, cursor, copilot}`:
+   - If the platform is in `target_platforms`, skip (it will be rewritten in the main loop)
+   - Otherwise, check whether its target file exists (`CLAUDE.md`, `.cursorrules`, or `AGENTS.md`)
+   - If the file exists, read it and check for the `<!-- SKF:BEGIN -->` marker
+   - If the marker is present, add the file path to `orphaned_platform_files` along with the platform name
+
+2. If `orphaned_platform_files` is non-empty, emit a warning:
+
+   "**Orphaned platform files detected.** The following files contain SKF managed sections but their platforms are no longer in `config.yaml` `ides`:
+   {list: platform → file path}
+
+   The managed sections in these files are stale. Options:
+   - **(a) clear** — remove the SKF managed section from each orphaned file (surgical marker replacement, leaves user content intact)
+   - **(b) keep** — leave them untouched (they will remain stale until you re-add the IDE or delete the file)
+   - **(c) rewrite** — also rewrite the orphaned files with the current skill index (use this if the IDE was removed by mistake)"
+
+3. Wait for user choice. In non-interactive mode (dry-run or unattended), default to **(b) keep** and print the warning only.
+
+4. If the user chose **(a) clear**: for each orphaned file, replace everything between `<!-- SKF:BEGIN` and `<!-- SKF:END -->` (inclusive) with an empty string, preserving surrounding content byte-exactly. Record the cleared files in `orphans_cleared`.
+
+5. If the user chose **(c) rewrite**: add each orphaned platform to a separate `rewrite_platforms` list (kept distinct from `target_platforms` so the user's intent to only export to configured IDEs is preserved in the manifest's `platforms` field). Sections 4–9a will loop over `target_platforms + rewrite_platforms` for this run only. Record the rewritten files in `orphans_rewritten`.
+
+6. If the user chose **(b) keep**: record nothing and proceed.
+
+This cleanup only runs during interactive export. Drop-skill and rename-skill operate on the manifest's declared platforms and are not responsible for orphan detection.
 
 ### 4. Rebuild Complete Skill Index
 
-Scan `{skills_output_folder}/*/context-snippet.md` to find ALL exported skills (not just the current one).
+#### 4a. Read Export Manifest (v2 — version-aware)
+
+Read `{skills_output_folder}/.export-manifest.json` — see [knowledge/version-paths.md](../../../knowledge/version-paths.md) for the full v2 schema:
+
+**If the file exists:** Parse JSON. Check for `schema_version` field:
+
+**v2 manifest** (`schema_version: "2"`):
+```json
+{
+  "schema_version": "2",
+  "exports": {
+    "skill-name": {
+      "active_version": "0.6.0",
+      "versions": {
+        "0.1.0": {
+          "platforms": ["claude"],
+          "last_exported": "2026-01-15",
+          "status": "deprecated"
+        },
+        "0.5.0": {
+          "platforms": ["claude"],
+          "last_exported": "2026-03-15",
+          "status": "archived"
+        },
+        "0.6.0": {
+          "platforms": ["claude", "copilot"],
+          "last_exported": "2026-04-04",
+          "status": "active"
+        }
+      }
+    }
+  }
+}
+```
+
+**Status values:**
+- `"active"` — currently exported; snippet appears in managed sections
+- `"archived"` — previously exported, not active; files retained for rollback
+- `"deprecated"` — dropped via drop-skill workflow; excluded from all exports (files may or may not exist on disk)
+- `"draft"` — created but never exported
+
+**v1 manifest** (no `schema_version` field — migrate in-place to v2):
+1. For each entry in `exports`, read its `platforms` and `last_exported`
+2. Resolve the skill's current version from `{resolved_skill_package}/metadata.json`
+3. Wrap in v2 structure: set `active_version` to the resolved version, create a single entry in `versions` with `status: "active"`, the original `platforms`, and `last_exported`
+4. Set `schema_version: "2"` at root
+5. Hold the migrated structure in context (it will be written in section 9b)
+
+**If the file does not exist** (first export or migration): Treat as empty — only the current export target will appear in the rebuilt index.
 
-**If no context-snippet.md files are found:** Generate managed section with zero skills — header only, no skill entries.
+#### 4b. Build Exported Skill Set (version-aware)
 
-For each found context-snippet.md:
-1. Read snippet content
-2. Add to skill index
+Determine the set of skills to include in the rebuilt index:
+
+1. Start with all skill names listed in the manifest's `exports` object (if manifest exists)
+2. For each skill, record its `active_version` from the manifest (v2 schema)
+3. **Integrity guard — `active_version` must resolve to a versions entry:** Check that `versions[active_version]` exists as a key. If `active_version` is set but there is no matching entry under `versions`, the manifest is inconsistent (possible corruption or a botched v1→v2 migration). Skip this skill and log a loud warning: "**Manifest integrity warning:** `{skill-name}.active_version = v{active_version}` has no matching entry under `versions`. Skipping. Re-run `[EX] Export Skill` on `{skill-name}` to repair the manifest entry."
+4. **Exclude deprecated skills:** If the `active_version` entry in `versions.{active_version}` has `status: "deprecated"`, skip this skill entirely — it has been dropped via drop-skill workflow and must not appear in the managed section. Log: "Skipping {skill-name} — active version v{active_version} is deprecated"
+5. Add the current export target skill name (ensures it is always included even before manifest is written) — use the version from `{resolved_skill_package}/metadata.json` as its `active_version`
+6. This is the **exported skill set** — each entry has a skill name and its resolved `active_version`
+
+#### 4c. Resolve and Filter Snippets (manifest-driven — replaces glob scan)
+
+Instead of globbing `{skills_output_folder}/*/context-snippet.md`, resolve snippets from the exported skill set built in 4b:
+
+**For each skill in the exported skill set:**
+1. Resolve `{skill_package}` using the skill's `active_version`: `{skills_output_folder}/{skill-name}/{active_version}/{skill-name}/`
+2. Read `{skill_package}/context-snippet.md`
+3. **If snippet exists:** Add to skill index
+4. **If snippet does not exist at the versioned path:** Check for `active` symlink at `{skills_output_folder}/{skill-name}/active/{skill-name}/context-snippet.md`. If still not found, skip with warning: "Snippet missing for {skill-name} v{active_version} — skipping from managed section"
+
+**Skills NOT in the exported skill set are never scanned** — they have not been through export-skill and must not appear in the managed section (ADR-K).
+
+**If no snippets pass the filter:** Generate managed section with zero skills — header only, no skill entries.
+
+#### 4d. Rewrite Root Paths for Target Platform
+
+The context-snippet.md files on disk contain root paths for the platform they were originally exported to. When assembling the managed section for the current target platform, rewrite root paths if they differ:
+
+**Platform root path mapping:**
+
+| Platform | Root Path Prefix |
+|----------|-----------------|
+| `claude` | `.claude/skills/` |
+| `cursor` | `.cursor/skills/` |
+| `copilot` | `.agents/skills/` |
+| _(legacy)_ | `skills/` |
+
+The legacy `skills/` prefix may appear in snippets exported before platform-aware root paths were introduced, or in draft snippets generated by create-skill/quick-skill.
+
+For each snippet being included in the managed section:
+
+1. Read the `root:` value from the snippet's first line
+2. Detect the current root prefix by matching against the known prefixes above (check platform-specific prefixes first, then fall back to legacy `skills/`)
+3. If the detected prefix does not match the current target platform's prefix, rewrite it
+4. Example: if snippet has `root: .claude/skills/my-lib/` but target is `cursor`, rewrite to `root: .cursor/skills/my-lib/`
+5. Example: if snippet has legacy `root: skills/my-lib/` and target is `copilot`, rewrite to `root: .agents/skills/my-lib/`
+
+This ensures each platform's managed section points to the correct platform-specific skill directory, including during migration from pre-platform-aware exports.
 
 **Sort skills alphabetically by name.**
 
@@ -139,7 +267,7 @@ Assemble the complete managed section:
 
 ### 7. Present Change Preview
 
-"**Context update prepared.**
+"**Context update prepared.{if multi-platform: ' (platform {i}/{total}: {platform})'}**
 
 **Target:** `{project-root}/{target-file}`
 **Case:** {1: Create / 2: Append / 3: Regenerate}
@@ -170,9 +298,16 @@ Auto-proceed to {nextStepFile}.
 
 Display: "**Select:** [C] Continue — write changes to {target-file}"
 
+**Multi-platform behavior:** When processing multiple platforms, present all platforms' previews together before asking for a single confirmation. After confirmation, write all target files sequentially, verifying each one.
+
+"**Targets:** {list all platform → target-file pairs}
+**Ready to write changes to all targets?**"
+
+Display: "**Select:** [C] Continue — write changes to all targets"
+
 #### Menu Handling Logic:
 
-- IF C: Write the changes to target file, verify write succeeded, then load, read entire file, then execute {nextStepFile}
+- IF C: Write the changes to all target files (or single target), verify each write succeeded, then load, read entire file, then execute {nextStepFile}
 - IF Any other: help user respond, then [Redisplay Menu Options](#8-present-menu-options)
 
 #### EXECUTION RULES:
@@ -194,6 +329,38 @@ After user confirms with 'C':
 **If verification fails:**
 "**WARNING: Write verification failed.** {describe issue}. File may need manual review."
 
+### 9b. Update Export Manifest (Non-Dry-Run Only)
+
+**This section executes ONCE after all platform iterations complete** (outside the per-platform loop defined in section 3). Only platforms whose writes succeeded in section 9 are recorded.
+
+1. Read `{skills_output_folder}/.export-manifest.json` (or start with `{"schema_version": "2", "exports": {}}` if it does not exist)
+2. Ensure `schema_version` is `"2"` (if v1 was migrated in section 4a, the migrated structure is already in context)
+3. Add or update the current skill's entry in v2 format:
+   ```json
+   "{skill-name}": {
+     "active_version": "{version}",
+     "versions": {
+       "{version}": {
+         "platforms": ["{successfully-written platforms}"],
+         "last_exported": "{current-date}",
+         "status": "active"
+       }
+     }
+   }
+   ```
+   - `{version}` is the version from `{resolved_skill_package}/metadata.json`
+   - Set `platforms` to only the platforms that were successfully written and verified in section 9
+   - If the skill already has a manifest entry:
+     - Set `active_version` to the current version
+     - If the version already exists in `versions`, update its `platforms` (merge, deduplicate), `last_exported`, and set `status: "active"`
+     - If this is a new version, add it to `versions` with `status: "active"` and set any previously-active version's status to `"archived"`
+     - Preserve all other version entries in `versions` (do not delete archived versions)
+4. Write the updated manifest to `{skills_output_folder}/.export-manifest.json`
+
+**Dry-run mode:** Do NOT update the manifest. Display: "**[DRY RUN] Export manifest would be updated for {skill-name} on platform(s) {platform-list}.**"
+
+**Error handling:** If manifest write fails, warn but do not fail the workflow — the managed section was already written successfully.
+
 ## CRITICAL STEP COMPLETION NOTE
 
 ONLY WHEN the user confirms changes by selecting 'C' (or auto-proceed in dry-run) and the write is verified will you load and read fully `{nextStepFile}` to execute the token report.
@@ -205,8 +372,11 @@ ONLY WHEN the user confirms changes by selecting 'C' (or auto-proceed in dry-run
 ### ✅ SUCCESS:
 
 - Managed section format loaded from {managedSectionData}
-- Target file correctly determined from platform flag
-- Complete skill index rebuilt from all exported skills
+- Target file(s) correctly determined from platform flag or config.yaml ides list
+- Multi-platform loop executed for all target_platforms
+- Root paths rewritten per platform in managed section
+- Complete skill index rebuilt from exported skills only (filtered via .export-manifest.json per ADR-K)
+- Export manifest updated after successful write (non-dry-run only)
 - Correct case detected (create/append/regenerate)
 - Clear diff preview shown to user
 - User confirmation received before writing
@@ -218,6 +388,8 @@ ONLY WHEN the user confirms changes by selecting 'C' (or auto-proceed in dry-run
 
 - Modifying content outside `<!-- SKF:BEGIN/END -->` markers
 - Not rebuilding the COMPLETE skill index (only adding current skill)
+- Including un-exported skills in managed section (bypasses ADR-K publishing gate)
+- Updating export manifest during dry-run
 - Writing without user confirmation
 - Not verifying write after completion
 - Not detecting the correct case (create/append/regenerate)

package/src/workflows/export-skill/steps-c/step-05-token-report.md

@@ -72,14 +72,14 @@ For each artifact, estimate tokens using the heuristic: **words * 1.3** (approxi
 | Artifact | Words | Est. Tokens | Notes |
 |----------|-------|-------------|-------|
 | context-snippet.md | {n} | ~{t} | Passive context (always-on) |
-| Managed section (all skills) | {n} | ~{t} | In {target-file}, all {count} skills |
+| Managed section (all skills) | {n} | ~{t} | In {target-file-list}, all {count} skills |
 | SKILL.md | {n} | ~{t} | Active skill (on-trigger) |
 | metadata.json | {n} | ~{t} | Machine-readable |
 | references/ | {n} | ~{t} | {count} files |
 | **Package total** | **{n}** | **~{t}** | **All artifacts combined** |
 
 **Context Budget Impact:**
-- **Always-on cost:** ~{managed-section-tokens} tokens (managed section in {target-file})
+- **Always-on cost:** ~{managed-section-tokens} tokens (managed section in {target-file-list})
 - **On-trigger cost:** ~{skill-tokens} tokens (when SKILL.md is loaded)
 - **Full disclosure cost:** ~{total-tokens} tokens (if references/ also loaded)
 

package/src/workflows/export-skill/steps-c/step-06-summary.md

@@ -1,6 +1,7 @@
 ---
 name: 'step-06-summary'
 description: 'Display export summary with distribution instructions'
+nextStepFile: '../../shared/health-check.md'
 ---
 
 # Step 6: Summary
@@ -55,7 +56,7 @@ To present a complete export summary showing all files written, token counts, an
 
 **Skill:** {skill-name}
 **Type:** {skill_type} | **Authority:** {source_authority} | **Tier:** {confidence_tier}
-**Platform:** {platform} → {target-file}
+**Platform(s):** {platform-list} → {target-file-list}
 
 ---
 
@@ -64,7 +65,8 @@ To present a complete export summary showing all files written, token counts, an
 | File | Status | Tokens |
 |------|--------|--------|
 | context-snippet.md | {✅ written / ⚠️ skipped (passive off) / 👁️ previewed} | ~{t} |
-| {target-file} managed section | {✅ updated (case {n}) / ⚠️ skipped / 👁️ previewed} | ~{t} |
+| {target-file-1} managed section | {✅ updated (case {n}) / ⚠️ skipped / 👁️ previewed} | ~{t} |
+| {target-file-N} managed section | {✅ updated (case {n}) / ⚠️ skipped / 👁️ previewed} | ~{t} |
 | Package structure | ✅ validated | ~{t} total |
 
 **Total context cost:** ~{always-on-tokens} tokens always-on, ~{on-trigger-tokens} tokens on-trigger"
@@ -102,7 +104,7 @@ Your skill is committed to the project's `skills/` directory and ships with your
 
 **Team members** will automatically have access when they pull the latest changes.
 
-**To update team context:** Ensure {target-file} is committed with the managed section update."
+**To update team context:** Ensure all target files ({target-file-list}) are committed with the managed section updates."
 
 **If `community`:**
 
@@ -110,12 +112,30 @@ Your skill is committed to the project's `skills/` directory and ships with your
 
 Your skill is generated from an external dependency for local use.
 
-**Location:** `{skills_output_folder}/{skill-name}/`
+**Location:** `{skills_output_folder}/{skill-name}/{version}/{skill-name}/`
 **Scope:** This project only — not for publishing to agentskills.io
 
 **Note:** Community skills are generated from third-party source code. Only `official` skills (generated by the library maintainer) should be published to the ecosystem."
 
-### 3. Dry Run Reminder (If Applicable)
+### 3. Use It In This Project
+
+Always show this section (regardless of `source_authority`) so the author can install the skill they just forged into the current project and try it immediately:
+
+"### Use It In This Project
+
+To install this skill into the current project right now:
+
+```
+npx skills add {resolved_skill_package}
+```
+
+Replace `{resolved_skill_package}` with the absolute path to the package folder shown above (from step-02), e.g. `{skills_output_folder}/{skill-name}/{version}/{skill-name}/`.
+
+For other source formats (registry name, git URL, tarball, etc.), see the **Installation → Source Formats** section at <https://www.npmjs.com/package/skills>.
+
+If the installed skill's commands are not available in the same IDE session, reload plugins (e.g. for Claude Code users, run `/reload-plugins`) or restart your AI editor. Next time you will see the command `/{skill-name}` (e.g. `/{skill-name}`)."
+
+### 4. Dry Run Reminder (If Applicable)
 
 **If dry-run mode was active:**
 
@@ -125,7 +145,7 @@ No files were written. To run the export for real:
 
 **Re-run without `--dry-run`** to write all files."
 
-### 4. Recommended Next Steps
+### 5. Recommended Next Steps
 
 "### Next Steps
 
@@ -133,15 +153,19 @@ No files were written. To run the export for real:
 - **update-skill** — After refactoring source code, regenerate the skill
 - **test-skill** — Verify skill completeness and accuracy"
 
-### 5. Workflow Complete
+### 6. Workflow Complete
 
 "---
 
 **Skill forged and delivered.** ⚒️"
 
+### 7. Workflow Health Check
+
+Load and execute `{nextStepFile}` for workflow self-improvement check.
+
 ## CRITICAL STEP COMPLETION NOTE
 
-This is the final step. The workflow is complete. No further steps to load.
+This step chains to the shared health check. After the health check completes, the export-skill workflow is fully done.
 
 ---
 
@@ -152,6 +176,8 @@ This is the final step. The workflow is complete. No further steps to load.
 - Complete summary with all files and their status
 - Token counts included from step-05
 - Distribution instructions appropriate for source_authority
+- Local install command (`npx skills add {resolved_skill_package}`) displayed with npmjs.com/package/skills link for alternate source formats
+- Plugin reload hint shown (reload plugins or restart AI editor to see `/{skill-name}`)
 - Dry-run correctly indicated (if applicable)
 - Recommended next workflows listed
 - Clear workflow completion signal
@@ -160,6 +186,7 @@ This is the final step. The workflow is complete. No further steps to load.
 
 - Missing files from summary
 - Wrong distribution instructions for source_authority
+- Omitting the local install command / npmjs source-formats link
 - Not indicating dry-run status
 - Writing additional files (console-only step)
 - Not ending the workflow cleanly

package/src/workflows/quick-skill/steps-c/step-01-resolve-target.md

@@ -69,6 +69,16 @@ Provide a **GitHub URL** or **package name** and I'll resolve it to source and c
 
 Wait for user input.
 
+### 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/`:**

package/src/workflows/quick-skill/steps-c/step-03-quick-extract.md

@@ -54,6 +54,8 @@ To read the resolved GitHub repository source and extract the public API surface
 
 **CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
 
+**Ref-aware source reading:** When `source_ref` is set from tag resolution (see step-01), 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.
+
 ### 1. Read README
 
 Read `README.md` from the repository root via web browsing.

package/src/workflows/quick-skill/steps-c/step-05-validate.md

@@ -105,7 +105,7 @@ Check that SKILL.md has these required sections populated:
 Check context-snippet.md format compliance:
 
 - [ ] **Vercel-aligned indexed format** — pipe-delimited with version, retrieval instruction, section anchors
-- [ ] **First line** matches pattern: `[{name} v{version}]|root: skills/{name}/`
+- [ ] **First line** matches pattern: `[{name} v{version}]|root: {prefix}{name}/` where prefix is `skills/` or a platform root (`.claude/skills/`, `.cursor/skills/`, `.agents/skills/`)
 - [ ] **Second line** starts with: `|IMPORTANT:`
 - [ ] **Approximate token count** is ~80-120 tokens