bmad-module-skill-forge 2.0.0 → 2.0.1

package/.claude-plugin/marketplace.json

@@ -30,7 +30,7 @@
       "name": "skill-forge",
       "source": "./",
       "description": "Evidence-based agent skills compiler with progressive capability tiers (Quick/Forge/Forge+/Deep).",
-      "version": "2.0.0",
+      "version": "2.0.1",
       "author": {
         "name": "Armel"
       },

package/.nvmrc

@@ -1 +1 @@
-22
+24

package/docs/_data/pinned.yaml

@@ -26,7 +26,7 @@
 # Enforced two ways: (1) release.yaml bumps this line in the same commit
 # as package.json + marketplace.json on every release; (2) validate-docs-drift.js
 # cross-checks this value against package.json.version and fails on mismatch.
-skf_version: "2.0.0"
+skf_version: "2.0.1"
 
 # Path to the oh-my-skills repo, resolved relative to this repo's root.
 # Override at runtime with the OMS environment variable if oh-my-skills

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-module-skill-forge",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "BMAD module — Turn code and docs into instructions AI agents can actually follow. Progressive capability tiers (Quick/Forge/Forge+/Deep).",
   "keywords": [
     "bmad",
@@ -53,7 +53,7 @@
     "test:cli": "node test/test-cli-integration.js",
     "test:install": "node test/test-installation-components.js",
     "test:knowledge": "node test/test-knowledge-base.js",
-    "test:python": "uv run --with pytest --with pyyaml --with jsonschema pytest test/test-compute-score-contract.py test/test-skf-preflight.py test/test-skf-skill-inventory.py test/test-skf-validate-output.py test/test-skf-validate-frontmatter.py test/test-skf-manifest-ops.py test/test-skf-rebuild-managed-sections.py test/test-skf-atomic-write.py test/test-skf-severity-classify.py test/test-skf-structural-diff.py test/test-skf-detect-tools.py test/test-skf-forge-tier-rw.py test/test-skf-emit-result-envelope.py test/test-skf-qmd-classify-collections.py test/test-skf-merge-ccc-exclusions.py test/test-skf-resolve-package.py test/test-skf-extract-public-api.py test/test-skf-render-quick-metadata.py test/test-skf-validate-brief-inputs.py test/test-skf-emit-brief-result-envelope.py test/test-skf-write-skill-brief.py test/test-skf-detect-workspaces.py test/test-skf-recommend-scope-type.py test/test-skf-detect-language.py test/test-skf-language-corpora.py test/test-skf-merge-doc-urls.py test/test-skf-derive-assembly-shape.py test/test-skf-description-guard.py test/test-skf-detect-scripts-assets.py test/test-skf-hash-content.py test/test-skf-validate-brief-schema.py test/test-skf-check-workspace-drift.py test/test-skf-update-active-symlink.py test/test-skf-build-change-manifest.py test/test-skf-provenance-gap-dispatch.py test/test-skf-resolve-authoritative-files.py test/test-skf-scan-manifests.py test/test-skf-pair-intersect.py test/test-skf-enumerate-stack-skills.py test/test-skf-compare-file-hashes.py test/test-skf-load-provenance.py test/test-skf-scan-skill-md-structure.py test/test-skf-disqualify-candidates.py test/test-skf-chain-reachability.py test/test-skf-shape-detect.py test/test-skf-detect-docs.py test/test-skf-step-doc-sources.py test/test-skf-step-doc-drift.py test/test-skf-step-hard-gate.py test/test-skf-per-pipeline-thresholds.py test/test-skf-evidence-report-fallback.py test/test-skf-validate-pins.py test/test-skf-auto-shard.py test/test-skf-preapply.py test/test-skf-step-doc-rot.py test/test-skf-campaign-state.py test/test-skf-campaign-pins.py test/test-skf-campaign-deps.py test/test-skf-campaign-report.py test/test-skf-campaign-stepfiles.py test/test-skf-campaign-validate-state.py test/test-skf-campaign-provenance.py test/test-skf-campaign-parse-manifest.py test/test-skf-campaign-render-kickoff.py -v",
+    "test:python": "uv run --with pytest --with pyyaml --with jsonschema pytest test/test-compute-score-contract.py test/test-skf-preflight.py test/test-skf-skill-inventory.py test/test-skf-validate-output.py test/test-skf-validate-frontmatter.py test/test-skf-manifest-ops.py test/test-skf-rebuild-managed-sections.py test/test-skf-atomic-write.py test/test-skf-severity-classify.py test/test-skf-structural-diff.py test/test-skf-detect-tools.py test/test-skf-forge-tier-rw.py test/test-skf-emit-result-envelope.py test/test-skf-qmd-classify-collections.py test/test-skf-merge-ccc-exclusions.py test/test-skf-resolve-package.py test/test-skf-extract-public-api.py test/test-skf-render-quick-metadata.py test/test-skf-validate-brief-inputs.py test/test-skf-emit-brief-result-envelope.py test/test-skf-write-skill-brief.py test/test-skf-detect-workspaces.py test/test-skf-recommend-scope-type.py test/test-skf-detect-language.py test/test-skf-language-corpora.py test/test-skf-merge-doc-urls.py test/test-skf-derive-assembly-shape.py test/test-skf-description-guard.py test/test-skf-detect-scripts-assets.py test/test-skf-hash-content.py test/test-skf-validate-brief-schema.py test/test-skf-check-workspace-drift.py test/test-skf-update-active-symlink.py test/test-skf-build-change-manifest.py test/test-skf-provenance-gap-dispatch.py test/test-skf-resolve-authoritative-files.py test/test-skf-scan-manifests.py test/test-skf-pair-intersect.py test/test-skf-enumerate-stack-skills.py test/test-skf-compare-file-hashes.py test/test-skf-load-provenance.py test/test-skf-scan-skill-md-structure.py test/test-skf-disqualify-candidates.py test/test-skf-chain-reachability.py test/test-skf-shape-detect.py test/test-skf-detect-docs.py test/test-skf-step-doc-sources.py test/test-skf-step-doc-drift.py test/test-skf-step-hard-gate.py test/test-skf-per-pipeline-thresholds.py test/test-skf-evidence-report-fallback.py test/test-skf-validate-pins.py test/test-skf-auto-shard.py test/test-skf-preapply.py test/test-skf-step-doc-rot.py test/test-skf-campaign-state.py test/test-skf-campaign-pins.py test/test-skf-campaign-deps.py test/test-skf-campaign-report.py test/test-skf-campaign-stepfiles.py test/test-skf-campaign-validate-state.py test/test-skf-campaign-provenance.py test/test-skf-campaign-parse-manifest.py test/test-skf-campaign-render-kickoff.py test/test-skf-campaign-render-batch.py test/test-skf-shard-body.py test/test-skf-render-metadata-stats.py test/test-skf-comention-pairs.py test/test-skf-count-tokens.py test/test-skf-reconcile-coverage.py test/test-skf-verify-provenance-completeness.py test/test-skf-find-cycles.py test/test-skf-validate-feasibility-report.py test/test-skf-rewrite-skill-name.py test/test-skf-verify-no-trace.py test/test-skf-validate-inventory.py test/test-skf-check-metadata-coherence.py test/test-skf-scan-doc-rot.py test/test-skf-aggregate-coherence.py test/test-skf-dir-sizes.py test/test-skf-parse-pipeline.py test/test-skf-validate-rename-name.py test/test-skf-verify-declared-numerator.py test/test-skf-combine-external-scores.py test/test-skf-new-file-diff.py test/test-skf-coverage-tally.py test/test-skf-report-delta.py test/test-skf-verdict-rollup.py -v",
     "test:schemas": "node test/test-agent-schema.js",
     "test:workflow": "node test/test-workflow-state.js",
     "validate:refs": "node tools/validate-file-refs.js --strict",

package/src/knowledge/skill-lifecycle.md

@@ -143,7 +143,7 @@ EX → agentskills.io bundle + context snippets (flat platform paths)
 
 VS → feasibility-report-{project_name}.md (verdict + integration verdicts)
        ↓ (report consumed by RA)
-RA → refined-architecture-{project_name}.md (gaps filled, issues flagged, improvements suggested)
+RA → refined-architecture-{arch_project_name}.md (gaps filled, issues flagged, improvements suggested)
        ↓ (refined doc consumed by SS compose-mode)
 SS (compose) → SKILL.md (stack skill synthesized from individual skills + architecture)
 ```

package/src/module-help.csv

@@ -1,4 +1,4 @@
-module,skill,display-name,menu-code,description,action,args,phase,after,before,required,output-location,outputs
+module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
 skf,skf-forger,Ferris — Skill Forge Agent,FF,"Skill compilation specialist — the forge master. Invoke to access all SKF workflows via guided menu.",,,anytime,,,false,,
 skf,skf-setup,Setup Forge,SF,"Initialize forge environment — detect tools and set capability tier (Quick/Forge/Forge+/Deep)",,,anytime,,"skf-analyze-source,skf-brief-skill,skf-quick-skill,skf-verify-stack,skf-campaign",false,,forge-tier.yaml
 skf,skf-campaign,Campaign,CA,"Orchestrate multi-library skill production across sessions — dependency tracking, file-based state, and resume",,resume [--from=<skill>],anytime,skf-setup,,false,forge_data_folder,_campaign-state.yaml
@@ -10,7 +10,7 @@ skf,skf-create-stack-skill,Stack Skill,SS,"Consolidated project stack skill with
 skf,skf-update-skill,Update Skill,US,"Smart regeneration preserving [MANUAL] sections after source changes",,,anytime,skf-export-skill,,false,skills_output_folder,SKILL.md
 skf,skf-audit-skill,Audit Skill,AS,"Drift detection between skill and current source code",,,anytime,skf-export-skill,,false,,drift report
 skf,skf-verify-stack,Verify Stack,VS,"Pre-code stack feasibility verification against architecture and PRD documents",,,anytime,skf-setup,skf-refine-architecture,false,forge_data_folder,feasibility-report-{project_name}.md
-skf,skf-refine-architecture,Refine Architecture,RA,"Improve architecture doc using verified skill data and VS feasibility findings",,,anytime,skf-verify-stack,,false,output_folder,refined-architecture-{project_name}.md
+skf,skf-refine-architecture,Refine Architecture,RA,"Improve architecture doc using verified skill data and VS feasibility findings",,,anytime,skf-verify-stack,,false,output_folder,refined-architecture-{arch_project_name}.md
 skf,skf-test-skill,Test Skill,TS,"Cognitive completeness verification — quality gate before export",,,anytime,"skf-create-skill,skf-create-stack-skill,skf-quick-skill",skf-export-skill,false,,completeness score
 skf,skf-export-skill,Export Skill,EX,"Package for distribution and inject context into CLAUDE.md/AGENTS.md/.cursorrules",,,anytime,skf-test-skill,"skf-update-skill,skf-audit-skill,skf-rename-skill,skf-drop-skill",false,skills_output_folder,agentskills.io package
 skf,skf-rename-skill,Rename Skill,RS,"Rename a skill across all its versions — transactional copy-verify-delete with platform context rebuild",,,anytime,skf-export-skill,,false,skills_output_folder,renamed skill group

package/src/shared/scripts/skf-comention-pairs.py

@@ -0,0 +1,350 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# dependencies = []
+# ///
+"""SKF Co-mention Pairs — compute compose-mode co-mention pairs from an
+architecture document with the same precision guards the prompt used to run
+by hand.
+
+`detect-integrations.md` §2 (compose branch) asks the LLM to scan an
+architecture markdown document for skill-name co-mentions using three
+deterministic guards:
+
+  1. Word-boundary matching (`\\b{skill_name}\\b`, case-insensitive) — no
+     substring false positives (`react` must not match inside `reactive`).
+  2. Section filtering — paragraphs governed by an H1/H2 header that
+     normalises to one of {introduction, overview, glossary, table of
+     contents, references, appendix, index} are excluded, and heading text
+     itself is never a co-mention source.
+  3. Two-paragraph minimum — a pair (A, B) qualifies only when at least two
+     distinct body paragraphs each contain word-boundary matches for both A
+     and B.
+
+Given a fixed architecture doc and skill-name set the qualifying-pair set is
+fully determined, so this belongs in a deterministic helper rather than
+in-prompt regex/counting. It mirrors the co-import subprocess the code-mode
+branch already delegates and the `skf-pair-intersect.py` pre-pass. The LLM
+still does the semantic composition (integration-section authoring, tier
+inheritance, VS-verdict parsing) — the script only emits the qualifying pairs
+and their evidence paragraphs.
+
+Subcommand:
+  comention --doc <md-file-or-'-'> --skills <json-file-or-'-'>
+      --doc     path to the architecture markdown document, or '-' for stdin.
+      --skills  path to a JSON array of loaded skill names
+                (e.g. `["react", "express"]`), or '-' for stdin.
+                (--doc and --skills cannot both read from stdin.)
+
+      Emit JSON:
+        {
+          "pairs": [
+            {
+              "a": "<skill>", "b": "<skill>",
+              "paragraph_count": N,
+              "evidence": [{"header": "<governing-header-or-null>",
+                            "excerpt": "<collapsed paragraph text>"}, ...]
+            },
+            ...
+          ],
+          "excluded_section_count": M
+        }
+
+      Only unordered pairs (a < b lexicographically) with paragraph_count >= 2
+      are emitted. `pairs[]` is sorted by paragraph_count DESC, then (a, b)
+      ASC — stable, mirroring skf-pair-intersect.py. `evidence[]` is in
+      document order. `excluded_section_count` is the number of DISTINCT
+      excluded H1/H2 sections (by normalised header) that governed at least
+      one body paragraph — a diagnostic for the caller, not a gate.
+
+CLI examples:
+  uv run skf-comention-pairs.py comention --doc arch.md --skills skills.json
+  echo '["react","express"]' | uv run skf-comention-pairs.py comention \\
+      --doc arch.md --skills -
+
+Exit codes:
+  0  — operation succeeded (including: no qualifying pairs → empty list)
+  1  — user error (bad JSON, missing/unreadable file, both inputs on stdin,
+       malformed skills array)
+  2  — unexpected internal error
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+
+# Closed exclusion set — governing H1/H2 headers that normalise to one of
+# these drop their paragraphs from co-mention analysis (they typically
+# enumerate all libraries without describing an integration).
+EXCLUDED_HEADERS = frozenset({
+    "introduction",
+    "overview",
+    "glossary",
+    "table of contents",
+    "references",
+    "appendix",
+    "index",
+})
+
+# ATX header line: 1-6 leading hashes followed by at least one space/tab.
+# A line like `#foo` (no space) is NOT a header per CommonMark and is treated
+# as body text. Capture group 1 = hashes (level), group 2 = header text.
+_HEADER_RE = re.compile(r"^(#{1,6})[ \t]+(.*)$")
+
+_EXCERPT_LIMIT = 240
+
+
+class UserError(Exception):
+    """A caller-facing input error → exit code 1."""
+
+
+# --------------------------------------------------------------------------
+# Markdown parsing
+# --------------------------------------------------------------------------
+
+
+def _strip_closing_hashes(text: str) -> str:
+    """Remove a closed-ATX trailing run of hashes (e.g. `Overview ##`)."""
+    return re.sub(r"[ \t]*#+[ \t]*$", "", text)
+
+
+def normalize_header(text: str) -> str:
+    """Normalise a header for exclusion-set comparison: lowercase, collapse
+    internal whitespace, strip trailing punctuation."""
+    t = text.strip().lower()
+    t = re.sub(r"\s+", " ", t).strip()
+    t = t.rstrip(".,:;!?").strip()
+    return t
+
+
+def parse_body_paragraphs(doc_text: str) -> list[tuple[str | None, str]]:
+    """Split the document into body paragraphs, each tagged with the raw text
+    of its governing (nearest-preceding) H1/H2 header (or None).
+
+    Paragraphs are maximal runs of consecutive non-blank, non-header lines,
+    separated by blank lines. Header lines of ANY level are never emitted as
+    paragraphs (headings are not a co-mention source). Only H1/H2 headers
+    update the governing header; H3-H6 leave it unchanged.
+    """
+    paragraphs: list[tuple[str | None, str]] = []
+    governing: str | None = None
+    buf: list[str] = []
+
+    def _flush() -> None:
+        if buf:
+            text = "\n".join(buf).strip()
+            if text:
+                paragraphs.append((governing, text))
+            buf.clear()
+
+    for raw_line in doc_text.splitlines():
+        m = _HEADER_RE.match(raw_line)
+        if m is not None:
+            # A header terminates the current paragraph; the header line
+            # itself is not body content.
+            _flush()
+            level = len(m.group(1))
+            header_text = _strip_closing_hashes(m.group(2)).strip()
+            if level <= 2:
+                governing = header_text if header_text else None
+            continue
+        if raw_line.strip() == "":
+            _flush()
+            continue
+        buf.append(raw_line)
+    _flush()
+    return paragraphs
+
+
+# --------------------------------------------------------------------------
+# Co-mention analysis
+# --------------------------------------------------------------------------
+
+
+def _make_excerpt(text: str, limit: int = _EXCERPT_LIMIT) -> str:
+    """Collapse whitespace and truncate for a stable, compact evidence quote."""
+    collapsed = re.sub(r"\s+", " ", text).strip()
+    if len(collapsed) > limit:
+        return collapsed[: limit - 3].rstrip() + "..."
+    return collapsed
+
+
+def analyze(doc_text: str, skill_names: list[str]) -> dict:
+    """Compute qualifying co-mention pairs and their evidence.
+
+    Deterministic: same (doc_text, skill_names) → identical output.
+    """
+    names = sorted(set(skill_names))
+    patterns = {
+        n: re.compile(r"\b" + re.escape(n) + r"\b", re.IGNORECASE)
+        for n in names
+    }
+    paragraphs = parse_body_paragraphs(doc_text)
+
+    excluded_sections: set[str] = set()
+    # (a, b) -> list of evidence dicts, one per qualifying paragraph
+    pair_evidence: dict[tuple[str, str], list[dict]] = {}
+
+    for governing, text in paragraphs:
+        if governing is not None:
+            norm = normalize_header(governing)
+            if norm in EXCLUDED_HEADERS:
+                excluded_sections.add(norm)
+                continue
+        # names is sorted, so `present` is sorted → pairs are (a < b)
+        present = [n for n in names if patterns[n].search(text)]
+        if len(present) < 2:
+            continue
+        excerpt = _make_excerpt(text)
+        evidence_entry = {"header": governing, "excerpt": excerpt}
+        for i in range(len(present)):
+            for j in range(i + 1, len(present)):
+                key = (present[i], present[j])
+                pair_evidence.setdefault(key, []).append(evidence_entry)
+
+    pairs: list[dict] = []
+    for (a, b), evidence in pair_evidence.items():
+        if len(evidence) >= 2:
+            pairs.append({
+                "a": a,
+                "b": b,
+                "paragraph_count": len(evidence),
+                "evidence": evidence,
+            })
+    pairs.sort(key=lambda p: (-p["paragraph_count"], p["a"], p["b"]))
+
+    return {
+        "pairs": pairs,
+        "excluded_section_count": len(excluded_sections),
+    }
+
+
+# --------------------------------------------------------------------------
+# CLI
+# --------------------------------------------------------------------------
+
+
+def _read_source(source: str, label: str) -> str:
+    """Read text from a file path or stdin (if source == '-')."""
+    if source == "-":
+        try:
+            return sys.stdin.read()
+        except OSError as exc:
+            raise UserError(f"failed to read {label} from stdin: {exc}") from exc
+    path = Path(source)
+    if not path.is_file():
+        raise UserError(f"{label} file not found: {path}")
+    try:
+        return path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise UserError(f"failed to read {label} file {path}: {exc}") from exc
+
+
+def parse_skills(raw_text: str) -> list[str]:
+    """Parse and validate the --skills JSON array of non-empty strings."""
+    try:
+        data = json.loads(raw_text)
+    except json.JSONDecodeError as exc:
+        raise UserError(f"malformed JSON in --skills input: {exc}") from exc
+    if not isinstance(data, list):
+        raise UserError(
+            "--skills input must be a JSON array of strings; "
+            f"got {type(data).__name__}"
+        )
+    names: list[str] = []
+    for idx, item in enumerate(data):
+        if not isinstance(item, str) or not item:
+            raise UserError(
+                f"--skills[{idx}] must be a non-empty string; got {item!r}"
+            )
+        names.append(item)
+    return names
+
+
+def _cmd_comention(args: argparse.Namespace) -> int:
+    if args.doc == "-" and args.skills == "-":
+        raise UserError(
+            "--doc and --skills cannot both read from stdin ('-')"
+        )
+    # Read the file-backed input first so a single stdin source stays intact.
+    if args.doc == "-":
+        skills_text = _read_source(args.skills, "--skills")
+        doc_text = _read_source(args.doc, "--doc")
+    else:
+        doc_text = _read_source(args.doc, "--doc")
+        skills_text = _read_source(args.skills, "--skills")
+    skill_names = parse_skills(skills_text)
+
+    result = analyze(doc_text, skill_names)
+    if args.verbose:
+        print(
+            f"analyzed {len(set(skill_names))} distinct skill names; "
+            f"{len(result['pairs'])} qualifying pairs; "
+            f"{result['excluded_section_count']} excluded sections",
+            file=sys.stderr,
+        )
+    json.dump(result, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="skf-comention-pairs",
+        description=(
+            "Compute compose-mode co-mention pairs from an architecture "
+            "document (detect-integrations.md §2 compose branch)."
+        ),
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_cm = sub.add_parser(
+        "comention",
+        help=(
+            "emit qualifying co-mention pairs (>=2 body paragraphs, "
+            "word-boundary, section-filtered) as JSON"
+        ),
+    )
+    p_cm.add_argument(
+        "--doc",
+        required=True,
+        help="path to the architecture markdown document, or '-' for stdin",
+    )
+    p_cm.add_argument(
+        "--skills",
+        required=True,
+        help=(
+            "path to a JSON array of loaded skill names, or '-' for stdin. "
+            "Shape: [\"<skill>\", ...]"
+        ),
+    )
+    p_cm.add_argument(
+        "--verbose",
+        action="store_true",
+        help="print a one-line summary to stderr",
+    )
+    p_cm.set_defaults(func=_cmd_comention)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except UserError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    except Exception as exc:  # noqa: BLE001 — last-resort guard → exit 2
+        print(f"internal error: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/shared/scripts/skf-count-tokens.py

@@ -0,0 +1,222 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# ///
+"""SKF Count Tokens — Deterministic per-artifact token/word metrics for a skill package.
+
+Pre-pass that measures the exported artifacts of a single skill package and the
+shared managed section, so the export skill's token report (references/token-report.md)
+and snippet token check (references/generate-snippet.md §4) render exact numbers from
+JSON instead of re-reading every reference file to word-count it in-prompt.
+
+Metrics:
+  - words:  whitespace-split word count (`len(text.split())`) — the report's "Words" column
+  - tokens: char-over-four estimate (`len(text) // 4`) — the SKF-wide convention already
+            used by skf-validate-output.py, so every SKF token number agrees
+
+Measured artifacts (all relative to the positional skill-package dir):
+  - context-snippet.md   — the compressed passive-context snippet (if present)
+  - SKILL.md             — the active skill document
+  - metadata.json        — machine-readable metadata
+  - references/*         — every file under references/ (recursively), summed as references_total
+  - managed section      — the complete <!-- SKF:BEGIN ... --> ... <!-- SKF:END --> block,
+                           extracted from the first --target-file that contains one
+                           (shared across the batch; measured once)
+
+package_total sums context-snippet.md + SKILL.md + metadata.json + references_total and
+DELIBERATELY EXCLUDES the managed-section row — the managed section is a shared all-skills
+cost reported separately, and including it would double-count this skill's own snippet
+(see references/token-report.md §1).
+
+CLI:
+  python3 skf-count-tokens.py <skill-package-dir>
+  python3 skf-count-tokens.py <skill-package-dir> --target-file CLAUDE.md
+  python3 skf-count-tokens.py <skill-package-dir> --target-file CLAUDE.md --target-file AGENTS.md
+  python3 skf-count-tokens.py <skill-package-dir> -o report.json
+
+Exit codes: 0 = metrics emitted, 2 = error (skill package dir missing / not a directory).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+# Mirrors skf-rebuild-managed-sections.py: a BEGIN marker may carry attributes
+# (e.g. `updated:2026-07-13`) before its closing `-->`; the END marker is fixed.
+MANAGED_SECTION_RE = re.compile(
+    r"<!-- SKF:BEGIN[^>]*-->.*?<!-- SKF:END -->",
+    re.DOTALL,
+)
+
+# Core per-skill artifacts, in report order. (references/ is handled separately.)
+CORE_ARTIFACTS = [
+    ("context-snippet.md", "context-snippet"),
+    ("SKILL.md", "skill-md"),
+    ("metadata.json", "metadata"),
+]
+
+
+def estimate_tokens(text: str) -> int:
+    """Char-over-four token estimate — the SKF-wide convention (see skf-validate-output.py)."""
+    return len(text) // 4
+
+
+def count_words(text: str) -> int:
+    """Whitespace-split word count — the token report's 'Words' column."""
+    return len(text.split())
+
+
+def measure(text: str) -> dict:
+    """Return the {words, tokens} metrics for a piece of text."""
+    return {"words": count_words(text), "tokens": estimate_tokens(text)}
+
+
+def _read_text(path: Path) -> str:
+    # encoding is pinned to utf-8 so non-ASCII content is not mojibaked on
+    # Windows (cp1252 default).
+    return path.read_text(encoding="utf-8")
+
+
+def extract_managed_section(text: str) -> str | None:
+    """Return the complete BEGIN..END managed-section span (markers included), or None."""
+    m = MANAGED_SECTION_RE.search(text)
+    return m.group(0) if m else None
+
+
+def measure_reference_files(references_dir: Path) -> tuple[list[dict], dict]:
+    """Measure every file under references/ (recursively, sorted). Returns (per-file rows, total)."""
+    rows: list[dict] = []
+    total_words = 0
+    total_tokens = 0
+    if references_dir.is_dir():
+        for path in sorted(references_dir.rglob("*"), key=lambda p: p.as_posix()):
+            if not path.is_file():
+                continue
+            text = _read_text(path)
+            metrics = measure(text)
+            rows.append(
+                {
+                    "path": path.relative_to(references_dir.parent).as_posix(),
+                    "role": "reference",
+                    "exists": True,
+                    **metrics,
+                }
+            )
+            total_words += metrics["words"]
+            total_tokens += metrics["tokens"]
+    total = {"count": len(rows), "words": total_words, "tokens": total_tokens}
+    return rows, total
+
+
+def count_package(skill_dir: Path, target_files: list[Path] | None = None) -> dict:
+    """Measure a skill package's artifacts and the shared managed section.
+
+    Returns the metrics dict (see module docstring for the shape). Missing core
+    artifacts are reported with exists=False and zero metrics so package_total is
+    always well-defined and callers can render 'N/A' rows without guessing.
+    """
+    skill_dir = Path(skill_dir)
+    target_files = target_files or []
+
+    files: list[dict] = []
+
+    # Core per-skill artifacts.
+    for name, role in CORE_ARTIFACTS:
+        path = skill_dir / name
+        if path.is_file():
+            metrics = measure(_read_text(path))
+            files.append({"path": name, "role": role, "exists": True, **metrics})
+        else:
+            files.append({"path": name, "role": role, "exists": False, "words": 0, "tokens": 0})
+
+    # references/ — per-file rows + summed total.
+    ref_rows, references_total = measure_reference_files(skill_dir / "references")
+    files.extend(ref_rows)
+
+    # package_total = snippet + SKILL.md + metadata + references_total; EXCLUDES managed section.
+    core_by_role = {row["role"]: row for row in files if row["role"] in {"context-snippet", "skill-md", "metadata"}}
+    package_total = {
+        "words": sum(core_by_role[r]["words"] for r in core_by_role) + references_total["words"],
+        "tokens": sum(core_by_role[r]["tokens"] for r in core_by_role) + references_total["tokens"],
+    }
+
+    # Managed section — first --target-file that actually contains a block wins.
+    managed_section = {"present": False, "source_file": None, "words": 0, "tokens": 0}
+    for tf in target_files:
+        tf = Path(tf)
+        if not tf.is_file():
+            continue
+        section = extract_managed_section(_read_text(tf))
+        if section is not None:
+            managed_section = {
+                "present": True,
+                "source_file": tf.as_posix(),
+                **measure(section),
+            }
+            break
+
+    return {
+        "status": "ok",
+        "skill_package": skill_dir.as_posix(),
+        "files": files,
+        "references_total": references_total,
+        "managed_section": managed_section,
+        "package_total": package_total,
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="skf-count-tokens.py",
+        description=(
+            "Deterministic per-artifact word/token metrics for a skill package. Emits JSON "
+            "with per-file rows, references_total, the shared managed-section block, and a "
+            "package_total that excludes the managed section (see references/token-report.md §1). "
+            "tokens = len(text)//4 (SKF-wide convention); words = whitespace-split count."
+        ),
+    )
+    parser.add_argument(
+        "skill_package",
+        help="Resolved skill-package directory (holds context-snippet.md, SKILL.md, metadata.json, references/)",
+    )
+    parser.add_argument(
+        "--target-file",
+        action="append",
+        default=[],
+        metavar="PATH",
+        help="Context file (CLAUDE.md / AGENTS.md / .cursorrules) to extract the managed "
+        "section from; repeatable — the first file with a BEGIN..END block is measured.",
+    )
+    parser.add_argument("-o", "--output", metavar="PATH", help="Write JSON here (default: stdout)")
+    parser.add_argument("--verbose", action="store_true", help="Emit diagnostics to stderr")
+    args = parser.parse_args(argv)
+
+    skill_dir = Path(args.skill_package)
+    if not skill_dir.is_dir():
+        print(f"error: skill package directory not found: {skill_dir}", file=sys.stderr)
+        return 2
+
+    if args.verbose:
+        print(f"measuring skill package: {skill_dir}", file=sys.stderr)
+        if args.target_file:
+            print(f"managed-section candidates: {args.target_file}", file=sys.stderr)
+
+    result = count_package(skill_dir, [Path(p) for p in args.target_file])
+
+    payload = json.dumps(result, indent=2)
+    if args.output:
+        Path(args.output).write_text(payload + "\n", encoding="utf-8")
+        if args.verbose:
+            print(f"wrote {args.output}", file=sys.stderr)
+    else:
+        print(payload)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())