bmad-module-skill-forge 0.2.0 → 0.3.0

package/src/workflows/create-skill/data/extraction-patterns.md

@@ -61,3 +61,251 @@ Same extraction as Forge tier. Deep tier adds enrichment in step-04, not extract
 ### Confidence
 - Extraction: same as Forge (T1)
 - Enrichment annotations added in step-04: T2
+
+---
+
+## AST Extraction Protocol
+
+When AST tools are available (Forge/Deep tier), follow this deterministic protocol to prevent output overflow on large codebases.
+
+**"Files in scope"** = files remaining after applying `include_patterns` and `exclude_patterns` from the brief, filtered by the target language extension. This is NOT the total repository file count from step-01's tree listing. Use the filtered count from step-03 section 2 as the decision tree input.
+
+### Decision Tree
+
+Apply the first matching condition:
+
+```
+Files in scope ≤ 100
+  → Use ast-grep MCP tool: find_code(pattern, max_results=100, output_format="text")
+  → Parse compact text output directly into extraction inventory
+
+Files in scope 101–500
+  → Use ast-grep MCP tool: find_code_by_rule(yaml, max_results=150, output_format="text")
+  → Use scoped YAML rules (see recipes below) to filter at the AST level
+  → Parse compact text output into extraction inventory
+
+Files in scope > 500
+  → CLI streaming fallback: ast-grep --json=stream + line-by-line Python processing
+  → Process in directory batches, cap per-batch output
+  → Merge batch results into extraction inventory
+```
+
+### Safety Valve
+
+If any ast-grep operation (MCP or CLI) visibly causes a timeout, returns an error related to output size, or produces unexpectedly large output: immediately switch to the CLI streaming fallback with `--json=stream`. Do not retry the same approach. When falling back to the CLI streaming template, inject the brief's `scope.exclude` patterns into the `EXCLUDES` list (use `[]` if absent) — this applies regardless of which path triggered the fallback. Note: `max_results` in the MCP tool and `| head -N` in the CLI path provide hard caps, but this safety valve covers cases where the upstream tool itself fails before returning results (e.g., OOM during JSON serialization).
+
+### MCP Tool Usage (Preferred)
+
+**Simple pattern search:**
+
+```
+find_code(
+  project_folder="{source_path}",
+  pattern="async def $NAME($$$PARAMS)",
+  language="python",
+  max_results=100,
+  output_format="text"
+)
+```
+
+**Scoped YAML rule search (for larger repos):**
+
+```
+find_code_by_rule(
+  project_folder="{source_path}",
+  yaml="id: public-api\nlanguage: python\nrule:\n  pattern: 'def $NAME($$$PARAMS)'\n  inside:\n    kind: module\n    stopBy: end\nconstraints:\n  NAME:\n    regex: '^[^_]'",
+  max_results=150,
+  output_format="text"
+)
+```
+
+### CLI Streaming Fallback
+
+When MCP tools are unavailable or the repo exceeds 500 files in scope, use `--json=stream` (NEVER `--json` or `--json=pretty`) with line-by-line Python processing:
+
+```bash
+# Note: use $$$ for variadic params in ast-grep patterns (e.g., 'def $NAME($$$PARAMS)')
+# {exclude_patterns} = Python list from brief's scope.exclude, e.g. ['tests/**', '**/test_*']
+# If scope.exclude is absent or empty in the brief, inject [] as the default.
+# Patterns are matched against the full file path as emitted by ast-grep.
+# Ensure paths are relative to the same root as the patterns (strip ./ prefix if needed).
+ast-grep -p '{pattern}' -l {language} --json=stream {path} | python3 -c "
+import sys, json, fnmatch
+
+EXCLUDES = {exclude_patterns}
+
+for line in sys.stdin:
+    try:
+        m = json.loads(line)
+        f = m.get('file','')
+        if EXCLUDES and any(fnmatch.fnmatch(f, pat) for pat in EXCLUDES):
+            continue
+        v = m.get('metaVariables',{})
+        name = v.get('single',{}).get('NAME',{}).get('text','')
+        if name and not name.startswith('_'):
+            ln = m.get('range',{}).get('start',{}).get('line',0)+1
+            sig = m.get('text','').split(chr(10))[0].strip()
+            print(f'[AST:{f}:L{ln}] {sig}')
+    except: pass
+" | head -200
+```
+
+**Critical constraints:**
+
+- ALWAYS use `--json=stream` — never `--json` (loads entire array into memory)
+- ALWAYS process line-by-line (`for line in sys.stdin`) — never `json.load(sys.stdin)`
+- ALWAYS cap output with `| head -N` as a safety valve
+- For repos > 500 files, process in directory batches of 20-50 files each
+
+### YAML Rule Recipes by Language
+
+**Python — public functions:**
+
+```yaml
+id: python-public-functions
+language: python
+rule:
+  pattern: 'def $NAME($$$PARAMS)'
+  inside:
+    kind: module
+    stopBy: end
+constraints:
+  NAME:
+    regex: '^[^_]'
+```
+
+**Python — public classes:**
+
+```yaml
+id: python-public-classes
+language: python
+rule:
+  pattern: 'class $NAME($$$BASES)'
+  inside:
+    kind: module
+    stopBy: end
+constraints:
+  NAME:
+    regex: '^[^_]'
+```
+
+**JavaScript/TypeScript — exported functions:**
+
+```yaml
+id: js-exported-functions
+language: typescript
+rule:
+  pattern: 'export function $NAME($$$PARAMS)'
+```
+
+**JavaScript/TypeScript — exported constants:**
+
+```yaml
+id: js-exported-constants
+language: typescript
+rule:
+  pattern: 'export const $NAME = $VALUE'
+```
+
+**Rust — public functions:**
+
+```yaml
+id: rust-public-functions
+language: rust
+rule:
+  any:
+    - pattern: 'pub fn $NAME($$$PARAMS) -> $RET'
+    - pattern: 'pub fn $NAME($$$PARAMS)'
+```
+
+**Go — exported functions (capitalized):**
+
+```yaml
+id: go-exported-functions
+language: go
+rule:
+  pattern: 'func $NAME($$$PARAMS) $RET'
+constraints:
+  NAME:
+    regex: '^[A-Z]'
+```
+
+### Re-Export Tracing
+
+After initial AST extraction, some top-level exports may resolve to **module imports** rather than direct function definitions. This is common in Python libraries that use `__init__.py` re-exports for a clean public API.
+
+**Detection heuristic:** For each top-level export from `__init__.py` (or equivalent entry point), check if the import path resolves to a directory (contains `__init__.py`) rather than a `.py` file with a matching `def` or `class`. If the initial AST scan found no function/class definition for a known public export, it is likely a module re-export.
+
+**Tracing protocol:**
+
+1. Read the entry point file (e.g., `{package}/__init__.py`) and extract all `from .X import Y` statements
+2. For each import where Y was NOT found by the initial AST scan:
+   - Check if the import path resolves to a directory (e.g., `{package}/api/v1/delete/` exists with `__init__.py`)
+   - If directory: read its `__init__.py` to find the actual re-exported symbol
+   - Trace the symbol to its definition file and run AST extraction on that file
+3. Cite the actual definition location: `[AST:{definition_file}:L{line}]`
+
+**Examples:**
+
+```python
+# Module re-export — follow required
+from .api.v1.delete import delete    # delete/ is a directory → read delete/__init__.py
+
+# Direct function import — no follow needed
+from .api.v1.add.add import add      # add.py exists with def add()
+```
+
+**Unresolvable imports:** If the import statement is a star-import (`from .X import *`) or a conditional import (`try`/`except`), the symbol cannot be reliably traced via this protocol. Record it with `[SRC:{package}/__init__.py:L{line}]` (T1-low) and a note: "star/conditional import — manual trace required."
+
+**Scope limit:** Only trace re-exports for symbols listed in the top-level entry point's public API. Do not recursively trace beyond one level of `__init__.py` indirection. If a re-export cannot be resolved after one level, record it with a `[SRC:{package}/__init__.py:L{line}]` citation (T1-low) from the import statement itself.
+
+**Other languages:** JS/TS barrel files (`index.ts` with `export { X } from './module'`) follow the same principle — trace the re-export to the definition file. Rust `pub use` and Go package-level re-exports are less common but follow the same heuristic when encountered.
+
+---
+
+## Tier Degradation Rules
+
+### Remote Source at Forge/Deep Tier
+
+When `source_repo` is a remote URL (GitHub URL or owner/repo format) and the tier is Forge or Deep:
+
+- **ast-grep requires local files** — it cannot operate on remote URLs
+
+**Ephemeral clone strategy (preferred):**
+
+1. Check `git` availability (`git --version`). `git` is effectively guaranteed at Deep tier (via `gh` dependency) but NOT guaranteed at Forge tier.
+2. If `git` is available: perform an ephemeral shallow clone to a system temp path (`{system_temp}/skf-ephemeral-{skill-name}-{timestamp}/`).
+3. For create-skill: use `--depth 1 --single-branch --filter=blob:none`; if `include_patterns` are specified, apply mode selection: if `exclude_patterns` are absent, use cone mode (convert include_patterns to directory roots; use `--skip-checks` for individual file paths); if `exclude_patterns` are present, use `--no-cone` mode (pass gitignore-style patterns with `!`-prefixed excludes — includes first, then negations). See source-resolution-protocols.md for the full conversion rules.
+4. For update-skill: use sparse-checkout with `--skip-checks` scoped to the changed files from the change manifest only (file paths require `--skip-checks`). No `--branch` flag — uses the remote default branch (must match the branch used during original create-skill run).
+5. If clone succeeds: use the local clone path for AST extraction. All results are T1 with `[AST:...]` citations.
+6. Cleanup: delete the temp directory after extraction inventory is built and all data is in context. The clone never persists beyond the extraction step.
+
+**Fallback (clone fails or `git` unavailable):**
+
+- The extraction step MUST warn the user explicitly before degrading
+- **create-skill:** Warning must include actionable guidance — clone locally and update `source_repo` in the brief to the local path
+- **update-skill:** Warning must include actionable guidance — clone locally, re-run [CS] Create Skill with the local path to regenerate provenance data, then re-run the update
+- Extraction proceeds using Quick tier strategy (source reading via gh_bridge)
+- All results labeled T1-low with `[SRC:...]` citations
+- The degradation reason is recorded in the evidence report
+
+Silent degradation is **forbidden**. The user must always know when AST extraction was skipped and why.
+
+### AST Tool Unavailable at Forge/Deep Tier
+
+When the tier is Forge or Deep but ast-grep is not functional:
+
+- The extraction step MUST warn the user explicitly before degrading
+- Warning must include actionable guidance: run [SF] Setup Forge to detect tools
+- Extraction proceeds using Quick tier strategy
+- All results labeled T1-low
+- The degradation reason is recorded in the evidence report
+
+### Per-File AST Failure
+
+When ast-grep fails on an individual file (parse error, unsupported syntax):
+
+- Fall back to source reading for **that file only**
+- Other files continue with AST extraction
+- The affected file's results are labeled T1-low; unaffected files retain T1
+- Log a warning noting which file degraded and why

package/src/workflows/create-skill/data/skill-sections.md

@@ -2,30 +2,60 @@
 
 ## agentskills.io Compliant Format
 
-### Frontmatter (Required)
+### Frontmatter (Required — agentskills.io Compliance)
 
 ```yaml
 ---
 name: {skill-name}
-version: {source-version}
-description: {skill-name} — {export-count} verified functions
-author: {source-author}
+description: >
+  {Trigger-optimized description of what the skill does and when to use it.
+  Include specific keywords for agent discovery.
+  Mention what NOT to use it for if applicable.
+  1-1024 characters.}
 ---
 ```
 
-### Section Order
+**Frontmatter rules (agentskills.io specification):**
 
-1. **Overview** — What this skill provides, source repo, version, tier used
-2. **Quick Start** — Most common 3-5 functions with minimal examples
-3. **API Reference** — Grouped by module/file, each function with:
-   - Signature with types
-   - Parameters table
-   - Return type
-   - Usage example (from source tests/docs if available)
-   - Provenance citation: `[AST:{file}:L{line}]` or `[SRC:{file}:L{line}]`
-4. **Type Definitions** — Exported types, interfaces, enums
-5. **Integration Patterns** — Co-import patterns detected by ast_bridge (Forge/Deep only)
-6. **Manual Sections** — Seeded with `<!-- [MANUAL] -->` markers for update-skill
+- `name`: 1-64 characters, lowercase alphanumeric + hyphens only, must match parent directory name
+- `description`: 1-1024 characters, trigger-optimized for agent matching
+- Only 6 fields permitted: `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`
+- `version` and `author` belong in metadata.json, NOT in frontmatter
+
+### Two-Tier Section Structure
+
+SKILL.md uses a two-tier structure to ensure actionable content survives `split-body` extraction.
+
+#### Tier 1 — Always Inline (survives split-body, target <300 lines)
+
+| # | Section | Budget | Purpose |
+|---|---------|--------|---------|
+| 1 | **Overview** | ~10 lines | What the library does, source repo, version, tier, export count |
+| 2 | **Quick Start** | ~30 lines | 3-5 core functions with one runnable end-to-end example |
+| 3 | **Common Workflows** | ~30 lines | 4-5 typical function call sequences for common tasks |
+| 4 | **Key API Summary** | ~20 lines | Table of top 10-15 functions (name, purpose, key params) |
+| 4b | **Migration & Deprecation Warnings** | ~10 lines | T2-future warnings inline (Deep tier only, skip if none) |
+| 5 | **Key Types** | ~20 lines | Most important enum/type values inline |
+| 6 | **Architecture at a Glance** | ~10 lines | Bullet list of subsystem categories |
+| 7 | **CLI** | ~10 lines | Basic CLI commands (skip if no CLI) |
+| 8 | **Manual Sections** | ~5 lines | `<!-- [MANUAL] -->` markers for update-skill |
+
+#### Tier 2 — Reference-Eligible (extracted by split-body into references/)
+
+| # | Section | Purpose |
+|---|---------|---------|
+| 9 | **Full API Reference** | Complete signatures, parameter tables, return types, examples, citations |
+| 10 | **Full Type Definitions** | All types, interfaces, enums with full field details |
+| 11 | **Full Integration Patterns** | Co-import patterns, adapter details, pipeline internals (Forge/Deep only) |
+
+#### Assembly Rules
+
+- Tier 1 sections are assembled first — they form the standalone body
+- Tier 2 sections are assembled after — they are progressive disclosure detail
+- Tier 1 sections are kept short enough that `split-body` targets the larger Tier 2 sections (`## Full` headings) into `references/`
+- After split-body, SKILL.md retains all Tier 1 content — actionable without loading references
+- An agent loading only SKILL.md (no references) must get enough to act
+- **Section 4b (Migration & Deprecation Warnings)** is conditional: only emitted for Deep tier when T2-future annotations exist. Quick/Forge tiers and Deep tiers without T2-future annotations omit it entirely (no empty section). Parsers and validators must treat this section as optional.
 
 ### Provenance Citation Format
 
@@ -50,15 +80,31 @@ Place after Quick Start and after API Reference sections.
 
 ---
 
-## context-snippet.md Format
+## context-snippet.md Format (Vercel-aligned indexed format)
 
-Compressed 2-line-per-skill format for CLAUDE.md managed section:
+Indexed pipe-delimited format for CLAUDE.md managed section (~80-120 tokens per skill). Aligned with Vercel's research finding that retrieval instructions + indexed file maps + inline gotchas dramatically improve agent performance.
 
 ```markdown
-{skill-name} -> skills/{skill-name}/
-  exports: {comma-separated top 10 function names}
+[{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#quick-start}
+|api: {top exports with () for functions, comma-separated}
+|key-types:{SKILL.md#key-types} — {inline summary of most important type values}
+|gotchas: {2-3 most critical pitfalls or breaking changes, inline}
 ```
 
+### Format rules
+
+- **Line 1:** Skill name + version + root path — version signals training data staleness
+- **Line 2 (IMPORTANT):** Retrieval instruction — always present, tells agent to read SKILL.md before acting
+- **Lines 3+:** Pipe-delimited index mapping topics to SKILL.md sections (with `#anchor` pointers)
+- **Inline content:** Each index line includes a brief inline summary (~10 words) so the agent can decide whether to read the full section
+- **gotchas line:** 2-3 most critical pitfalls inline — prevents mistakes without requiring a file read
+- **Token budget:** ~80-120 tokens per skill (justified by Vercel's finding that indexed format maintains performance at 80% compression)
+- **T1-now content only** — no T2 annotations in the snippet
+- **Section anchors** (`#quick-start`, `#key-types`) must match actual SKILL.md heading slugs
+- **Version** comes from source detection (per issue #32), not brief default
+
 ---
 
 ## metadata.json Structure
@@ -67,13 +113,15 @@ Compressed 2-line-per-skill format for CLAUDE.md managed section:
 {
   "name": "{skill-name}",
   "version": "{source-version}",
-  "skill_type": "individual",
+  "skill_type": "single",
   "source_authority": "{official|community|internal}",
   "source_repo": "{github-url}",
+  "source_root": "{resolved-source-path}",
   "source_commit": "{commit-hash}",
-  "forge_tier": "{quick|forge|deep}",
+  "confidence_tier": "{Quick|Forge|Deep}",
   "spec_version": "1.3",
-  "generated_at": "{ISO-8601}",
+  "generation_date": "{ISO-8601}",
+  "exports": [],
   "tool_versions": {
     "ast_grep": "{version-or-null}",
     "qmd": "{version-or-null}",
@@ -81,8 +129,11 @@ Compressed 2-line-per-skill format for CLAUDE.md managed section:
   },
   "stats": {
     "exports_documented": 0,
+    "exports_public_api": 0,
+    "exports_internal": 0,
     "exports_total": 0,
-    "coverage": 0.0,
+    "public_api_coverage": 0.0,
+    "total_coverage": 0.0,
     "confidence_t1": 0,
     "confidence_t2": 0,
     "confidence_t3": 0
@@ -125,7 +176,10 @@ Each reference file includes:
   "generated_at": "{ISO-8601}",
   "entries": [
     {
-      "claim": "getToken accepts userId and optional TokenOptions",
+      "export_name": "getToken",
+      "export_type": "function",
+      "params": ["userId: string", "options?: TokenOptions"],
+      "return_type": "Token",
       "source_file": "src/auth/index.ts",
       "source_line": 42,
       "confidence": "T1",

package/src/workflows/create-skill/data/source-resolution-protocols.md

@@ -0,0 +1,130 @@
+# Source Resolution Protocols
+
+## Remote Source Resolution (Forge/Deep only)
+
+If `source_repo` is a local path: proceed with the tier-appropriate strategy as normal.
+
+If `source_repo` is a remote URL (GitHub URL or owner/repo format) AND tier is Forge or Deep:
+
+1. **Check `git` availability:** Verify `git` is functional (`git --version`). If `git` is not available, skip to the fallback warning below.
+
+2. **Ephemeral shallow clone:** Clone the repository to a system temp path for AST access:
+
+   ```
+   temp_path = {system_temp}/skf-ephemeral-{skill-name}-{timestamp}/
+   git clone --depth 1 --branch {branch} --single-branch --filter=blob:none {source_repo} {temp_path}
+   ```
+
+   **If `include_patterns` are NOT specified:**
+
+   ```
+   git clone --depth 1 --branch {branch} --single-branch --filter=blob:none {source_repo} {temp_path}
+   ```
+
+   **If `include_patterns` ARE specified**, use sparse-checkout to limit the clone scope:
+
+   ```
+   git clone --depth 1 --branch {branch} --single-branch --filter=blob:none --sparse {source_repo} {temp_path}
+   ```
+
+   **Mode selection:** Choose sparse-checkout mode based on whether `exclude_patterns` exist:
+
+   - **No `exclude_patterns`:** Use default **cone mode** (faster). Convert `include_patterns` to directory roots.
+   - **`exclude_patterns` present:** Use **`--no-cone` mode** which supports gitignore-style negation patterns (`!` prefix). This applies both include and exclude at the git level, avoiding unnecessary blob downloads.
+
+   **Cone mode (no exclude patterns):**
+
+   **IMPORTANT:** `git sparse-checkout set` expects **directories**, not glob patterns. Convert `include_patterns` before passing them:
+
+   **Classification rule:** A pattern is an **individual file** if it contains no glob characters (`*`, `?`, `[`) AND does not end with `/`. Everything else is a glob — strip it to its directory root (the path prefix before the first glob character or wildcard segment).
+
+   - Strip glob suffixes to directory roots (e.g., `src/core/**/*.py` → `src/core`, `src/api/*.ts` → `src/api`)
+   - Deduplicate the resulting directory list
+   - Individual files (e.g., `pyproject.toml`, `src/utils/helpers.py`) are kept as-is
+
+   **If only directory roots (no individual files):**
+
+   ```
+   git -C {temp_path} sparse-checkout set {converted_directory_roots}
+   ```
+
+   **If any individual files are present (or mixed):**
+
+   ```
+   git -C {temp_path} sparse-checkout set --skip-checks {converted_directory_roots} {individual_files}
+   ```
+
+   Example transformation:
+   ```
+   Brief include_patterns:        sparse-checkout args:
+   src/core/**/*.py          →    src/core          (directory root)
+   src/api/*.ts              →    src/api           (directory root)
+   examples/**/*.py          →    examples          (directory root)
+   pyproject.toml            →    pyproject.toml    (individual file, needs --skip-checks)
+   src/utils/helpers.py      →    src/utils/helpers.py (individual file, needs --skip-checks)
+   ```
+
+   **No-cone mode (exclude patterns present):**
+
+   When `exclude_patterns` exist, use `--no-cone` mode to pass both include and exclude patterns directly as gitignore-style rules:
+
+   1. Convert `include_patterns` to gitignore-style patterns. If a pattern contains no glob characters (`*`, `?`, `[`) and does not end with `/`, append `/**` to match directory contents recursively (e.g., `cognee` → `cognee/**`; `cognee/**` → kept as-is).
+   2. Convert `exclude_patterns` to negation patterns by prepending `!`. Apply the same anchoring rule (e.g., `cognee/tests` → `!cognee/tests/**`; `cognee/tests/**` → `!cognee/tests/**`; `**/test_*` → `!**/test_*`).
+   3. **CRITICAL:** List all include patterns BEFORE negated exclude patterns — git processes patterns in order and a negation can only suppress a prior inclusion.
+   4. Pass to sparse-checkout — include patterns first, then negated exclude patterns:
+
+   ```
+   git -C {temp_path} sparse-checkout set --no-cone {include_gitignore_patterns} {negated_exclude_patterns}
+   ```
+
+   Example transformation:
+   ```
+   Brief include_patterns:        Brief exclude_patterns:
+   cognee/**                      cognee/tests/**
+                                  cognee/alembic/**
+                                  **/test_*
+
+   sparse-checkout args (--no-cone):
+   'cognee/**' '!cognee/tests/**' '!cognee/alembic/**' '!**/test_*'
+   ```
+
+   **Note:** `--no-cone` mode is slower than cone mode for very large repositories but eliminates downloading excluded blobs entirely.
+
+   **Post-checkout filtering:**
+
+   After checkout, apply the original glob `include_patterns` as file-level filters when building the extraction file list — sparse-checkout gets the right directories, glob filtering narrows to the exact files. When `--no-cone` mode was used, most exclude filtering is already done at the git level, but apply `exclude_patterns` as a final pass to catch any edge cases where gitignore pattern matching diverges from the brief's glob semantics.
+
+3. **If clone succeeds:** Update the working source path to `{temp_path}` for all subsequent AST operations in this step. Proceed with the **Forge/Deep Tier** extraction strategy below. Mark `ephemeral_clone_active = true` for cleanup.
+
+4. **If clone fails (network error, auth failure, timeout):**
+
+   ⚠️ **Warn the user explicitly:**
+
+   "Ephemeral clone of `{source_repo}` failed: {error}. Degrading to source reading (T1-low) for this run. For T1 (AST-verified) confidence, clone the repository locally and update `source_repo` in your brief to the local path."
+
+   Proceed with Quick tier extraction strategy below. Note the degradation reason in context for the evidence report.
+
+**Ephemeral clone cleanup:** After extraction is complete for all files in scope (whether successful or partially failed), before presenting the Gate 2 summary (Section 6), if `ephemeral_clone_active`, delete the `{temp_path}` directory. Log: "Ephemeral source clone cleaned up." This ensures cleanup runs even if some extractions failed, as long as the step itself is still executing.
+
+---
+
+## Version Reconciliation (all tiers, source mode only)
+
+**If `source_type: "docs-only"`:** skip this section — no source files exist to reconcile.
+
+After the source path is accessible (local path from step-01, or ephemeral clone from above), check whether the source contains a version identifier and reconcile it with `brief.version`. Look for the first matching version file in the resolved source path:
+
+- Python: `pyproject.toml` (`[project] version`), `setup.py` (`version=`), `__version__` in `__init__.py`
+- JavaScript/TypeScript: `package.json` (`"version"`)
+- Rust: `Cargo.toml` (`[package] version`)
+- Go: `go.mod` (module version if tagged)
+
+**If a source version is found AND it differs from `brief.version`:**
+
+⚠️ Warn the user: "Brief version ({brief.version}) differs from source version ({source_version}). Using source version ({source_version})."
+
+Update the working version in context to the source version. Record the mismatch in context for the evidence report (step-08).
+
+**If no version file is found or version cannot be extracted:** keep `brief.version` as-is. No warning needed.
+
+**If source is remote and accessed via Quick tier (gh_bridge, no local files):** attempt to read the version file via `gh_bridge.read_file(owner, repo, "{version_file}")` for the primary version file of the detected language. If the read fails, keep `brief.version`.

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

@@ -63,9 +63,8 @@ Halt with: "Forge halted: No forge configuration found. Run [SF] Setup Forge fir
 Extract and report:
 - `tier`: Quick, Forge, or Deep
 - `tools`: which tools are available (gh, ast-grep, qmd)
-- `tier_override`: if set, use override tier instead of detected
 
-Check for `tier_override` in `{preferencesFile}`. If `tier_override` is set and differs from detected tier, use the override value.
+**Apply tier override:** Read `{preferencesFile}`. If `tier_override` is set and is a valid tier value (Quick, Forge, or Deep), use it instead of the detected tier.
 
 ### 2. Discover Skill Brief
 
@@ -89,17 +88,21 @@ Check that the loaded skill-brief.yaml contains required fields:
 **Required fields:**
 - `name` — skill identifier (kebab-case)
 - `version` — source version to compile against
-- `source_repo` — GitHub owner/repo or local path
+- `source_repo` — GitHub owner/repo or local path (**optional when `source_type: "docs-only"`**)
 - `language` — primary source language
 - `scope` — what to extract (e.g., "all public exports", specific modules)
 
 **Optional fields:**
+- `source_type` — `"source"` (default) or `"docs-only"` (external documentation only)
+- `doc_urls` — array of `{url, label}` documentation URLs (required when `source_type: "docs-only"`)
 - `source_branch` — branch to use (default: main/master)
-- `source_authority` — official/community/internal (default: community)
+- `source_authority` — official/community/internal (default: community; forced to `community` for docs-only)
 - `include_patterns` — file glob patterns to include
 - `exclude_patterns` — file glob patterns to exclude
 - `description` — human description of the skill
 
+**Docs-only validation:** When `source_type: "docs-only"`, `source_repo` is not required but `doc_urls` must have at least one entry. `source_authority` is forced to `community`.
+
 **If required fields missing:**
 Halt with specific error: "Brief validation failed: missing required field `{field}`. Update your skill-brief.yaml and re-run."
 

package/src/workflows/create-skill/steps-c/step-02-ecosystem-check.md

@@ -53,16 +53,18 @@ To search the agentskills.io ecosystem for an existing official skill matching t
 
 ### 1. Check Ecosystem for Existing Skill
 
-**If skills_ref tool is available:**
+**Note:** Ecosystem lookup requires the agentskills.io registry API, which is not yet available. The `skill-check` CLI validates local skills but does not query a remote registry.
+
+**If agentskills.io registry API is available:**
 
 Query the ecosystem using the skill name from the brief:
-- `skills_ref.check_ecosystem(brief.name)`
+- Call the registry API with brief.name — check if an official skill already exists
 - Enforce 5-second timeout — if the query does not return within 5 seconds, treat as no match
 - Cache results for 24 hours (if re-running same skill)
 
-**If skills_ref tool is NOT available:**
+**If registry API is NOT available (current default):**
 
-Skip silently. Tool unavailability is not an error. Proceed as if no match was found.
+Skip completely and silently. Do not output any message about API unavailability or the ecosystem check being skipped. Emit zero text to the console. Proceed exactly as if no match was found.
 
 ### 2. Evaluate Results
 
@@ -124,7 +126,7 @@ If no match is found, this step auto-proceeds with no user interaction.
 
 ### ✅ SUCCESS:
 
-- Ecosystem check attempted (or gracefully skipped if tool unavailable)
+- Ecosystem check attempted via registry API (or gracefully skipped if API unavailable)
 - 5-second timeout enforced on ecosystem queries
 - Match presented factually with clear options if found
 - No-match case auto-proceeds silently
@@ -134,10 +136,11 @@ If no match is found, this step auto-proceeds with no user interaction.
 ### ❌ SYSTEM FAILURE:
 
 - Halting the workflow because ecosystem check failed or timed out
-- Treating tool unavailability as an error
+- Treating API unavailability as an error
+- Confusing `npx skill-check check` (local validation) with ecosystem lookup
 - Displaying "no match found" messages (absence should be silent)
 - Beginning extraction or compilation work in this step
 - Proceeding without user decision when a match IS found
 - Not enforcing the 5-second timeout
 
-**Master Rule:** This step is advisory. Tool failures and timeouts are silent skips, not errors. Only a confirmed match requires user interaction.
+**Master Rule:** This step is advisory. API unavailability and timeouts are silent skips, not errors. Only a confirmed match requires user interaction.