kctl-skill 0.2.0__tar.gz

kctl_skill-0.2.0/.gitignore

@@ -0,0 +1,36 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local
+
+# Agent memory (claude-mem regenerates AGENTS.md locally; not a committed guide)
+AGENTS.md

kctl_skill-0.2.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: kctl-skill
+Version: 0.2.0
+Summary: Toolchain for authoring, linting, building, and installing Kodemeio agent skills
+Requires-Python: >=3.12
+Requires-Dist: kctl-lib>=0.14.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.9.0

kctl_skill-0.2.0/README.md

@@ -0,0 +1,132 @@
+# kctl-skill
+
+Toolchain for authoring, linting, building, and installing **Kodemeio agent skills** —
+the `skills/<name>/SKILL.md` bundles that Claude and other agents load to operate the
+`kctl-*` CLI fleet. `kctl-skill` is the single generator and gate for all of them: it
+replaces the 42 near-identical `commands/skill_cmd.py` files and the shared
+`kctl_lib/skill_generator.py` module with one tool that knows what a skill is, so
+individual CLIs no longer have to.
+
+> **Status:** the toolchain is under active development. This package is currently
+> scaffolding only — the commands documented below describe the intended surface and
+> will land in subsequent tasks.
+
+See the full design: `docs/standards/kctl-skill-architecture.md`.
+
+## Install / run
+
+```bash
+uv sync --all-extras --all-packages
+uv run kctl-skill --help
+```
+
+Like `kctl-conform`, this is a `kind = "meta"` developer tool — it has no profile
+surface, no `--json`/`--profile` globals, and no external service to talk to. It reads
+and writes the local filesystem (`skills/` at the repo root and the Typer app registry
+of whichever CLI it is introspecting).
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `kctl-skill new <name> [--cli kctl-x]` | Scaffold a new skill from the template — profile rules, discovery, and safety sections pre-filled; domain-specific sections marked `TODO`. |
+| `kctl-skill build [<name>...]` | Regenerate `references/*.md` from Typer introspection of the declared CLI. Never touches `SKILL.md`. |
+| `kctl-skill lint [<name>...]` | Run the static `SKILL-*` rule family against one or all skills. |
+| `kctl-skill eval [<name>...]` | Run behavioural evals — discovery and execution scenarios defined per skill. |
+| `kctl-skill link [--clean] [--dry-run]` | Symlink-install skills into `~/.agents/skills/` (and `~/.claude/skills/` pointing at that). `--clean` removes stale copies; `--dry-run` previews without touching the filesystem. |
+| `kctl-skill list` | Inventory of all skills with health status (drift, orphans, staleness). |
+| `kctl-skill doctor` | Environment checks (skills root exists, CLIs resolvable, symlinks intact). |
+
+### Example invocations
+
+```bash
+# Scaffold a new tier-1 tool skill for kctl-pg
+uv run kctl-skill new pg-admin --cli kctl-pg
+
+# Regenerate references/ for every skill after a CLI's commands changed
+uv run kctl-skill build
+
+# Lint just the odoo-admin skill
+uv run kctl-skill lint odoo-admin
+
+# Preview what `link` would install, without writing anything
+uv run kctl-skill link --dry-run
+
+# Symlink-install every skill for local development
+uv run kctl-skill link
+
+# Show every skill's health at a glance
+uv run kctl-skill list
+```
+
+## `skill.toml` — build configuration
+
+Every skill carries a `skill.toml` sidecar. It is the toolchain's only control
+surface: it declares the tier (which selects the applicable lint budget), the CLI to
+introspect for tier-1 skills, and how command groups map onto generated reference
+files.
+
+```toml
+tier = "tool"            # "tool" (tier 1) | "domain" (tier 2)
+cli  = "kctl-odoo"        # tier 1 only -- the console script to introspect
+
+# Group clusters -> one generated reference file each.
+# Every group in the CLI must appear in exactly one cluster; `kctl-skill build`
+# errors on an unassigned or duplicated group so new commands cannot go missing.
+[references]
+"users-access"            = ["users", "groups", "access-rights", "roles"]
+"modules-database"        = ["modules", "database", "backup", "addons"]
+"inventory-manufacturing" = ["inventory", "stock", "mrp", "bom"]
+```
+
+For `tier = "domain"` skills the `cli` and `[references]` keys are omitted — their
+references are hand-authored, and `kctl-skill build` skips them entirely.
+
+## The `SKILL-*` rule family
+
+`kctl-skill lint` implements these rules; `kctl-conform` imports and runs them so
+there is one gate (`just conform`) and one baseline for the whole workspace.
+
+| Rule | Sev | Checks |
+|---|---|---|
+| SKILL-001 | error | `SKILL.md` exists at `skills/<name>/SKILL.md` |
+| SKILL-002 | error | Valid YAML frontmatter with `name` and `description` |
+| SKILL-003 | error | `name` equals directory name, ≤64 chars, `[a-z0-9-]+` only, no reserved words |
+| SKILL-004 | error | `description` non-empty, ≤1024 chars, no XML tags |
+| SKILL-005 | error | `skill.toml` exists and parses; `tier` is `tool` or `domain`; `tool` tier declares a resolvable `cli` |
+| SKILL-006 | error | For `tier = "tool"`: every command group of the declared CLI appears in exactly one `[references]` cluster |
+| SKILL-010 | error | `SKILL.md` body ≤500 lines (spec ceiling) |
+| SKILL-011 | warn | `SKILL.md` body ≤200 lines (`tier = "tool"`) or ≤300 lines (`tier = "domain"`) |
+| SKILL-012 | warn | Reference file >100 lines has a `## Contents` table of contents |
+| SKILL-020 | error | Description in third person — rejects leading `"I "`, `"You can"`, `"Use this to"` |
+| SKILL-021 | warn | Description contains a *when to use* clause |
+| SKILL-022 | error | Description is not the generated boilerplate |
+| SKILL-030 | error | Every relative link in `SKILL.md` resolves to an existing file |
+| SKILL-031 | error | References are one level deep — no linking onward to another skill-local `.md` |
+| SKILL-032 | warn | Orphan detection — every file in `references/` is linked from `SKILL.md` |
+| SKILL-040 | warn | No agent-specific constructs (`allowed-tools`, subagent references, `/slash-command`) |
+| SKILL-041 | error | No Windows-style paths |
+| SKILL-050 | error | Secret scan — high-entropy and known-prefix credential patterns |
+| SKILL-051 | warn | No absolute `/home/<user>` paths |
+| SKILL-060 | warn | Generated `references/` stale versus current CLI registry hash |
+| SKILL-061 | warn | No unresolved `TODO`/`TBD` markers from the scaffold template |
+| SKILL-070 | warn | Skill has ≥3 eval scenarios |
+
+## Package classification
+
+Registered in `kctl-conform` as `kind = "meta"`, like `kctl-conform` itself. Its own
+`[tool.kctl-conform]` block in `pyproject.toml` exempts a small set of CLI rules that
+are genuinely not applicable to a profile-less local authoring tool (no `--json`/
+`--profile` globals, no `doctor ai-summary`, commands living directly in `cli.py`, no
+`core/client.py`, and a trimmed `test_standard.py`).
+
+## Tests
+
+```bash
+uv run pytest packages/kctl-skill/tests/ -v
+```
+
+## Further reading
+
+- `docs/standards/kctl-skill-architecture.md` — the full standard this package
+  implements and enforces, including the rule rationale and migration notes.

kctl_skill-0.2.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kctl-skill"
+version = "0.2.0"
+description = "Toolchain for authoring, linting, building, and installing Kodemeio agent skills"
+requires-python = ">=3.12"
+dependencies = ["kctl-lib>=0.14.0", "typer>=0.9.0", "rich>=13.0"]
+
+[project.scripts]
+kctl-skill = "kctl_skill.cli:app"
+
+[tool.uv.sources]
+kctl-lib = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kctl_skill"]
+
+[tool.kctl-conform]
+kind = "meta"
+# Rules genuinely N/A for a profile-less local authoring tool:
+#   AFFORD-001 = no global --json/--profile options
+#   AFFORD-004 = no `doctor ai-summary` (no external service to probe)
+#   LAYOUT-003 = commands live in cli.py; no commands/ package
+#   LAYOUT-006 = no core/client.py (reads the local filesystem, no API client)
+#   TEST-002  = test_standard.py has Version/Help only; no config/completions groups
+# Task 11 DELETES the two rules below; drop these entries in that task.
+#   AFFORD-006 = no `skill generate` (generation centralises in this very package)
+#   LAYOUT-005 = no skills/<x>-admin/ (skills move to the repo root)
+exempt = [
+    "AFFORD-001",
+    "AFFORD-004",
+    "AFFORD-006",
+    "LAYOUT-003",
+    "LAYOUT-005",
+    "LAYOUT-006",
+    "TEST-002",
+]

kctl_skill-0.2.0/src/kctl_skill/__init__.py

@@ -0,0 +1,5 @@
+"""kctl-skill: author, lint, build, and install Kodemeio agent skills."""
+
+from __future__ import annotations
+
+__version__ = "0.2.0"

kctl_skill-0.2.0/src/kctl_skill/cli.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+import json as _json
+from dataclasses import asdict as _asdict
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from kctl_lib import cli_entrypoint, register_introspection_commands
+
+from . import __version__
+from .discovery import discover_skills, find_repo_root
+from .generate import build_skill
+from .install import KIND_LINK, KIND_OK, KIND_REMOVE_COPY, KIND_SKIP_FOREIGN, apply_links, plan_links
+from .lint import has_errors, lint_all
+from .model import TIER_DOMAIN, TIER_TOOL
+from .scaffold import scaffold_skill
+
+app = typer.Typer(
+    name="kctl-skill",
+    help="Author, lint, build, and install Kodemeio agent skills.",
+    no_args_is_help=True,
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"kctl-skill {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show version and exit.",
+    ),
+) -> None:
+    """kctl-skill CLI."""
+
+
+@app.command("lint")
+def lint_cmd(
+    names: Annotated[list[str] | None, typer.Argument(help="Skill names to lint. Omit for all.")] = None,
+    json_out: Annotated[bool, typer.Option("--json", help="Emit JSON.")] = False,
+    warnings_as_errors: Annotated[bool, typer.Option("--warnings-as-errors", help="Exit 1 on warnings too.")] = False,
+) -> None:
+    """Lint skills against the SKILL-* rule family."""
+    root = find_repo_root()
+    wanted = list(names) if names else None
+    findings = lint_all(root, names=wanted)
+
+    if json_out:
+        typer.echo(_json.dumps({"findings": [_asdict(f) for f in findings]}, indent=2))
+    else:
+        for f in findings:
+            typer.echo(f"{f.severity:<5} {f.rule_id}  {f.location} — {f.detail}")
+        errors = sum(1 for f in findings if f.severity == "error")
+        warns = len(findings) - errors
+        count = len(discover_skills(root)) if wanted is None else len(wanted)
+        typer.echo(f"\n{errors} error(s), {warns} warning(s) across {count} skill(s)")
+
+    if has_errors(findings) or (warnings_as_errors and findings):
+        raise typer.Exit(code=1)
+
+
+@app.command("new")
+def new_cmd(
+    name: Annotated[str, typer.Argument(help="Skill name (lowercase, hyphens).")],
+    cli: Annotated[str, typer.Option("--cli", help="Console script to introspect. Implies tool tier.")] = "",
+) -> None:
+    """Scaffold a new skill directory."""
+    root = find_repo_root()
+    tier = TIER_TOOL if cli else TIER_DOMAIN
+    path = scaffold_skill(root, name, cli or None, tier)
+    typer.echo(f"created {path.relative_to(root).as_posix()} ({tier} tier)")
+    typer.echo("next: fill the TODO sections, then run `kctl-skill lint`")
+
+
+@app.command("build")
+def build_cmd(
+    names: Annotated[list[str] | None, typer.Argument(help="Skill names to build. Omit for all.")] = None,
+) -> None:
+    """Regenerate references/ for tool-tier skills from live CLI introspection."""
+    root = find_repo_root()
+    wanted = set(names) if names else None
+    total = 0
+    for ctx in discover_skills(root):
+        if wanted is not None and ctx.name not in wanted:
+            continue
+        written = build_skill(ctx)
+        if written:
+            typer.echo(f"{ctx.name}: {len(written)} reference file(s)")
+            total += len(written)
+    typer.echo(f"\n{total} reference file(s) written")
+
+
+@app.command("list")
+def list_cmd() -> None:
+    """List every skill with its tier, CLI binding, and reference count."""
+    root = find_repo_root()
+    skills = discover_skills(root)
+    for ctx in skills:
+        refs = len(list(ctx.references_dir().glob("*.md"))) if ctx.references_dir().is_dir() else 0
+        evals = len(list(ctx.evals_dir().glob("*.json"))) if ctx.evals_dir().is_dir() else 0
+        cli = ctx.config.cli or "-"
+        typer.echo(f"{ctx.name:<28} {ctx.config.tier:<7} {cli:<16} refs={refs:<3} evals={evals}")
+    typer.echo(f"\n{len(skills)} skill(s)")
+
+
+@app.command("doctor")
+def doctor_cmd(
+    home: Annotated[str, typer.Option("--home", help="Override the home directory (testing).")] = "",
+) -> None:
+    """Diagnose the skills tree and its installation: drift, staleness, and broken links."""
+    root = find_repo_root()
+    home_path = Path(home) if home else Path.home()
+    skills = discover_skills(root)
+
+    typer.echo(f"repo root:  {root}")
+    typer.echo(f"skills:     {len(skills)}")
+
+    tool = [c for c in skills if c.config.tier == TIER_TOOL]
+    typer.echo(f"tool tier:  {len(tool)}   domain tier: {len(skills) - len(tool)}")
+
+    findings = lint_all(root)
+    errors = sum(1 for f in findings if f.severity == "error")
+    stale = sum(1 for f in findings if f.rule_id == "SKILL-060")
+    typer.echo(f"lint:       {errors} error(s), {len(findings) - errors} warning(s)")
+    typer.echo(f"stale refs: {stale} (run `kctl-skill build` to refresh)")
+
+    # clean=False makes this read-only: no action can remove anything.
+    actions = plan_links(root, home_path, clean=False)
+    linked = sum(1 for a in actions if a.kind == KIND_OK)
+    missing = sum(1 for a in actions if a.kind == KIND_LINK)
+    foreign = sum(1 for a in actions if a.kind == KIND_SKIP_FOREIGN)
+    typer.echo(f"install:    {linked} linked, {missing} not linked, {foreign} blocked by a foreign path")
+    if foreign:
+        typer.echo("            run `kctl-skill link --clean` to replace stale copies")
+
+    if errors:
+        raise typer.Exit(code=1)
+
+
+@app.command("link")
+def link_cmd(
+    clean: Annotated[bool, typer.Option("--clean", help="Replace stale copied directories with symlinks.")] = False,
+    dry_run: Annotated[bool, typer.Option("--dry-run", help="Print the plan and exit without changes.")] = False,
+    yes: Annotated[bool, typer.Option("--yes", help="Skip the confirmation prompt for --clean removals.")] = False,
+    home: Annotated[str, typer.Option("--home", help="Override the home directory (testing).")] = "",
+) -> None:
+    """Symlink this repo's skills into ~/.agents/skills and ~/.claude/skills."""
+    root = find_repo_root()
+    home_path = Path(home) if home else Path.home()
+    actions = plan_links(root, home_path, clean=clean)
+
+    for action in actions:
+        typer.echo(f"{action.kind:<13} {action.path} — {action.reason}")
+
+    if dry_run:
+        typer.echo("\ndry run — nothing changed")
+        return
+
+    removals = [a for a in actions if a.kind == KIND_REMOVE_COPY]
+    if removals and not yes:
+        typer.echo(f"\n{len(removals)} directory/ies will be DELETED and replaced by symlinks:")
+        for a in removals:
+            typer.echo(f"  {a.path}")
+        typer.confirm("Proceed?", abort=True)
+
+    changed = apply_links(actions)
+    typer.echo(f"\n{changed} change(s) applied")
+
+
+# Later tasks append new commands/groups above this line.
+# register_introspection_commands and cli_entrypoint must remain the last two
+# statements in this module -- introspection needs every command registered
+# first, and cli_entrypoint wraps the fully-assembled app for error handling.
+register_introspection_commands(app)
+app = cli_entrypoint(app)

kctl_skill-0.2.0/src/kctl_skill/core/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

kctl_skill-0.2.0/src/kctl_skill/core/callbacks.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from kctl_lib import AppContextBase
+
+
+@dataclass
+class AppContext(AppContextBase):
+    """Typer context for kctl-skill. Inherits lazy Output init from the base."""

kctl_skill-0.2.0/src/kctl_skill/core/config.py

@@ -0,0 +1,19 @@
+"""Workspace root resolution for the skills toolchain."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .exceptions import SkillError
+
+_WORKSPACE_MARKER = "[tool.uv.workspace]"
+
+
+def find_repo_root(start: Path | None = None) -> Path:
+    """Walk upward until a pyproject.toml declaring [tool.uv.workspace] is found."""
+    current = (start or Path.cwd()).resolve()
+    for candidate in (current, *current.parents):
+        pyproject = candidate / "pyproject.toml"
+        if pyproject.is_file() and _WORKSPACE_MARKER in pyproject.read_text(encoding="utf-8"):
+            return candidate
+    raise SkillError(f"no uv workspace root found from {current}")

kctl_skill-0.2.0/src/kctl_skill/core/exceptions.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from kctl_lib import KctlError
+
+
+class SkillError(KctlError):
+    """Raised when a skill directory or its configuration is unusable."""

kctl_skill-0.2.0/src/kctl_skill/discovery.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+from .core.config import find_repo_root
+from .core.exceptions import SkillError
+from .model import TIER_DOMAIN, SkillConfig, SkillCtx
+
+# Re-exported so callers can pull discovery + root resolution from one module.
+__all__ = ["discover_skills", "find_repo_root", "load_skill_config"]
+
+
+def load_skill_config(path: Path) -> SkillConfig:
+    """Parse a skill.toml. Raises SkillError with an actionable message on failure."""
+    if not path.is_file():
+        raise SkillError(f"skill.toml not found at {path}")
+    try:
+        data = tomllib.loads(path.read_text(encoding="utf-8"))
+    except tomllib.TOMLDecodeError as exc:
+        raise SkillError(f"invalid TOML in {path}: {exc}") from exc
+    except OSError as exc:
+        raise SkillError(f"cannot read {path}: {exc}") from exc
+
+    raw_refs = data.get("references", {})
+    references: dict[str, list[str]] = {}
+    if isinstance(raw_refs, dict):
+        for cluster, groups in raw_refs.items():
+            if isinstance(groups, list):
+                references[str(cluster)] = [str(g) for g in groups]
+
+    cli = data.get("cli")
+    return SkillConfig(
+        tier=str(data.get("tier", TIER_DOMAIN)),
+        cli=str(cli) if cli else None,
+        references=references,
+    )
+
+
+def discover_skills(root: Path) -> list[SkillCtx]:
+    """Return every skill under <root>/skills/, sorted by name.
+
+    A directory is a skill if it contains SKILL.md. A missing skill.toml is
+    treated as a domain-tier skill with no generated references, so a
+    hand-written skill works before the sidecar is added.
+    """
+    skills_dir = root / "skills"
+    if not skills_dir.is_dir():
+        return []
+    out: list[SkillCtx] = []
+    for d in sorted(p for p in skills_dir.iterdir() if p.is_dir()):
+        if not (d / "SKILL.md").is_file():
+            continue
+        toml_path = d / "skill.toml"
+        config = load_skill_config(toml_path) if toml_path.is_file() else SkillConfig()
+        out.append(SkillCtx(name=d.name, path=d, config=config))
+    return out

kctl_skill-0.2.0/src/kctl_skill/generate.py

@@ -0,0 +1,153 @@
+"""Generate a tool-tier skill's references/ from live Typer introspection.
+
+This module never writes SKILL.md. Routers are hand-authored; only the command
+surface is generated. That separation is what makes hand-written prose
+structurally impossible to clobber on a rebuild.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import importlib
+from pathlib import Path
+from typing import Any
+
+import typer
+from kctl_lib.introspection import dump_command_tree
+
+from .core.exceptions import SkillError
+from .model import TIER_TOOL, SkillCtx
+
+HASH_MARKER = "registry_hash:"
+_TOC_THRESHOLD = 100
+
+
+def load_cli_app(cli_name: str) -> typer.Typer:
+    """Import a console-script name's Typer app: 'kctl-odoo' -> kctl_odoo.cli:app."""
+    module_name = f"{cli_name.replace('-', '_')}.cli"
+    try:
+        module = importlib.import_module(module_name)
+    except ImportError as exc:
+        raise SkillError(f"cannot import {module_name} for CLI {cli_name!r}: {exc}") from exc
+    app = getattr(module, "app", None)
+    if not isinstance(app, typer.Typer):
+        raise SkillError(f"{module_name} does not export a Typer `app` attribute")
+    return app
+
+
+def command_tree_for_cli(cli_name: str) -> dict[str, Any]:
+    return dump_command_tree(load_cli_app(cli_name))
+
+
+def group_names_for_cli(cli_name: str) -> list[str]:
+    """Top-level command group names, sorted. Root-level leaf commands are excluded."""
+    tree = command_tree_for_cli(cli_name)
+    return sorted(g["name"] for g in tree.get("groups", []))
+
+
+def registry_hash(tree: dict[str, Any]) -> str:
+    """12-char digest over every group's name and leaf count — the staleness signal."""
+    parts: list[str] = []
+    for group in tree.get("groups", []):
+        leaves = len(group.get("commands", [])) + len(group.get("groups", []))
+        parts.append(f"{group['name']}:{leaves}")
+    raw = "|".join(sorted(parts))
+    return hashlib.sha256(raw.encode("utf-8")).hexdigest()[:12]
+
+
+def registry_hash_for_cli(cli_name: str) -> str:
+    return registry_hash(command_tree_for_cli(cli_name))
+
+
+def _flag_summary(params: list[dict[str, Any]]) -> str:
+    """Render a compact `<arg> [--opt]` signature from a command's param schema."""
+    parts: list[str] = []
+    for p in params:
+        if p.get("param_type") == "argument":
+            parts.append(f"<{p['name']}>")
+        else:
+            opt = next((o for o in p.get("opts", []) if o.startswith("--")), None)
+            if opt:
+                parts.append(opt if p.get("required") else f"[{opt}]")
+    return " ".join(parts)
+
+
+def _first_sentence(text: str) -> str:
+    first = text.strip().split("\n\n")[0].replace("\n", " ").strip()
+    for marker in ("Examples:", "Example:"):
+        if marker in first:
+            first = first[: first.index(marker)].strip()
+    return first
+
+
+def _render_group(cli_name: str, group: dict[str, Any], lines: list[str]) -> None:
+    lines.append(f"### `{cli_name} {group['name']}`")
+    lines.append("")
+    if group.get("help"):
+        lines.append(_first_sentence(group["help"]))
+        lines.append("")
+    commands = group.get("commands", [])
+    if commands:
+        lines.append("| Command | Description |")
+        lines.append("|---------|-------------|")
+        for cmd in commands:
+            sig = _flag_summary(cmd.get("params", []))
+            path = f"{group['name']} {cmd['name']}" + (f" {sig}" if sig else "")
+            lines.append(f"| `{path}` | {_first_sentence(cmd.get('help', ''))} |")
+        lines.append("")
+    for sub in group.get("groups", []):
+        _render_group(cli_name, {**sub, "name": f"{group['name']} {sub['name']}"}, lines)
+
+
+def render_reference(cli_name: str, cluster: str, groups: list[dict[str, Any]], hash_: str) -> str:
+    """Render one reference file for a cluster of command groups."""
+    body: list[str] = []
+    for group in groups:
+        _render_group(cli_name, group, body)
+
+    header = [
+        f"<!-- generated by `kctl-skill build` — do not edit. {HASH_MARKER} {hash_} -->",
+        "",
+        f"# {cli_name} — {cluster}",
+        "",
+        f"Discover exact flags before invoking: `{cli_name} commands tree --filter <group> --json`",
+        "",
+    ]
+
+    toc = ["## Contents", ""]
+    toc.extend(f"- `{cli_name} {g['name']}` — {_first_sentence(g.get('help', '')) or 'commands'}" for g in groups)
+    toc.append("")
+
+    # SKILL-012 measures the FINAL file, so the threshold has to be applied to
+    # the rendered length including header and ToC — not to `body` alone.
+    if len(header) + len(toc) + len(body) > _TOC_THRESHOLD:
+        header.extend(toc)
+
+    return "\n".join(header + body).rstrip() + "\n"
+
+
+def build_skill(ctx: SkillCtx) -> list[Path]:
+    """Regenerate every references/<cluster>.md for a tool-tier skill.
+
+    Domain-tier skills own their references by hand and are skipped.
+    Returns the list of files written.
+    """
+    if ctx.config.tier != TIER_TOOL or not ctx.config.cli:
+        return []
+
+    tree = command_tree_for_cli(ctx.config.cli)
+    hash_ = registry_hash(tree)
+    by_name = {g["name"]: g for g in tree.get("groups", [])}
+
+    refs_dir = ctx.references_dir()
+    refs_dir.mkdir(parents=True, exist_ok=True)
+
+    written: list[Path] = []
+    for cluster, group_names in sorted(ctx.config.references.items()):
+        groups = [by_name[n] for n in group_names if n in by_name]
+        if not groups:
+            continue
+        target = refs_dir / f"{cluster}.md"
+        target.write_text(render_reference(ctx.config.cli, cluster, groups, hash_), encoding="utf-8")
+        written.append(target)
+    return written