skill-linter 0.1.0__tar.gz

skill_linter-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --locked
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      # The adoption tests skip here: they need local checkouts of the skill repos.
+      - run: uv run pytest -q

skill_linter-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,21 @@
+name: Publish to PyPI
+
+# Runs only when a version tag is pushed. PyPI uses trusted publishing, so no token is stored.
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read  # checkout needs it once permissions are listed
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Tag matches the package version
+        run: test "${GITHUB_REF_NAME#v}" = "$(uv version --short)"
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

skill_linter-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+.pytest_cache/

skill_linter-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 [Jeff Smolinski](https://github.com/Jeffallan)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

skill_linter-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.5
+Name: skill-linter
+Version: 0.1.0
+Summary: Validate Agent Skills repos: spec checks, shared conventions, per-repo policy, count stamping and plugin release checks
+Project-URL: Repository, https://github.com/Jeffallan/skill-linter
+Project-URL: Issues, https://github.com/Jeffallan/skill-linter/issues
+Author: Jeff Smolinski
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: pyyaml>=6
+Description-Content-Type: text/markdown
+
+# skill-linter
+
+skill-linter checks a repo of Agent Skills before you commit or release it, and keeps the counts and version numbers in its docs current. One `[tool.skill-linter]` table in `pyproject.toml` configures it, so a new skill repo gets the same checks as the others without copying `validate-skills.py`, `validate-markdown.py` and `update-docs.py` into it.
+
+It needs Python 3.11 or later. PyYAML is the only dependency, used for workflow YAML.
+
+```sh
+uvx skill-linter check        # run without installing
+pipx install skill-linter     # or install it once
+```
+
+Status: early (0.x). Rule names and config keys may still change between minor versions.
+
+## Commands
+
+```text
+skill-linter check   [--only GROUP[,GROUP]] [--skill NAME] [--format text|json] [--root PATH]
+skill-linter stamp   [--check] [--dry-run] [--root PATH]
+skill-linter release [--format text|json] [--root PATH]
+skill-linter rules   [--format text|json]
+```
+
+- `check` runs every enabled rule except the release checks.
+- `stamp` counts skills, references, workflows and domains, then writes those counts and the version from `version.json` into the files you list. `--check` writes nothing and exits 1 when anything is stale.
+- `release` checks the tree the plugin directory will read (`plugin_root` or a `ship` list), then runs `check`.
+- `rules` lists every rule with its group, layer and severity after your overrides.
+
+`skill-linter --version` prints the installed version. Exit codes: 0 when there are no errors, 1 when there are errors or stale stamps, 2 for a usage or config error. `python -m skill_linter` runs the same CLI.
+
+## Rules
+
+Rules come in three layers:
+
+1. The [Agent Skills specification](https://agentskills.io/specification) (`SPEC-01` to `SPEC-10`). You can't switch these off.
+2. Conventions shared across the skill repos: frontmatter metadata, the description rule, Markdown lint, workflow definitions, hidden conventions such as the docs backlink and title safety, and the plugin-directory release checks (`CONV`, `DESC`, `MD`, `WF`, `H`, `P`). Each one can be switched off or lowered to a warning.
+3. Per-repo policy (`POL`, `LINK`, and your own `X-` rules). A policy rule runs only once you give it a value.
+
+Every rule has an ID and a name, such as `POL-03` and `section-order`. Output shows both, and the config accepts either. Run `skill-linter rules` for the full list.
+
+### Cross-skill references
+
+A skill can cite a file in a sibling skill or in a shared folder, written from the skill root: `` `../vue-expert/references/components.md` `` or `` `../_shared/markup-convention.md` ``. The spec wants every reference to stay inside the skill folder, so `SPEC-10` (`reference-depth`) leaves these paths to two other rules:
+
+- `CONV-15` (`cross-skill-references`) checks that the file exists, that the folder is a skill or is listed in `shared_dirs`, and that a cited skill appears in `metadata.related-skills` (a warning when it doesn't).
+- `P17` (`cross-skill-targets-ship`) checks that the cited file ships with the plugin. A skill installed on its own won't find its sibling, so these references only work when the whole plugin is installed.
+
+## Configuration
+
+Everything lives under `[tool.skill-linter]` in the repo's `pyproject.toml`. Unknown keys and unknown rule IDs are errors, so a typo can't switch a check off without anyone noticing. `tests/adoption/` holds complete configs for claude-skills and writing-with-agents.
+
+```toml
+[tool.skill-linter]
+skills_dir = "plugin/skills"
+shared_dirs = ["_shared"]
+commands_dir = "plugin/commands"
+plugin_root = "plugin"
+docs_url = "https://example.github.io/my-skills/skills/{domain}/{name}/"
+
+[tool.skill-linter.policy]
+workflow_steps = [5, 7]
+license = "MIT"
+
+[tool.skill-linter.severity]
+plugin-icon = "off"   # or P10
+
+[[tool.skill-linter.rules.custom]]
+id = "X-lead-support"
+target = "body"
+pattern = '(?is)\blead\b.*\bsupport\b'
+severity = "warning"
+message = "Name a lead and a support role"
+```
+
+Custom rules are regular expressions applied to a frontmatter field, a section, the last line, the body or the reference files. Config never runs code.
+
+### Stamping
+
+Each `[[tool.skill-linter.stamp.files]]` entry names a file and how to update it:
+
+```toml
+[[tool.skill-linter.stamp.files]]
+path = "README.md"   # .md, .mdx and .html files get marker stamping by default
+patterns = [
+  { key = "version", regex = 'version-([\d.]+)-blue\.svg' },
+  { key = "referenceFileCount.{skill}", regex = '(?m)^\s+(?P<skill>[\w-]+)/\s+\(SKILL\.md \+ (?P<count>\d+) reference(?P<s>s?)\)' },
+]
+
+[[tool.skill-linter.stamp.files]]
+path = ".claude-plugin/marketplace.json"
+json = { "/metadata/version" = "version", "/plugins/0/version" = "version" }
+patterns = [{ key = "skillCount", regex = '(\d+) specialized skills' }]
+```
+
+- Markers: `<!-- SKILL_COUNT -->67<!-- /SKILL_COUNT -->`, and likewise `WORKFLOW_COUNT`, `REFERENCE_COUNT`, `DOMAIN_COUNT` and `VERSION`. `SKILL_COUNT:<domain>` counts one domain and `REFERENCE_COUNT:<skill>` counts one skill's references.
+- `json` maps a JSON Pointer to a key and replaces only that value, leaving the file's formatting alone.
+- `patterns` replace the one group in each regex. A pattern that matches nothing is an error, which catches a sentence reworded after its pattern was written.
+- The key `referenceFileCount.{skill}` stamps a count per skill, for places where an HTML comment would show up as text, such as a file tree inside a code block. Its regex names the skill and count groups. The optional `s` group becomes `s` unless the count is 1, and a line that names no skill is an error.
+
+## Development
+
+```sh
+uv sync
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+```
+
+The adoption tests export pinned commits of the two skill repos with `git archive` and skip when those checkouts aren't present. One of them runs each repo's own `update-docs.py` and `skill-linter stamp` on the same change and checks that every file comes out identical.

skill_linter-0.1.0/README.md

@@ -0,0 +1,107 @@
+# skill-linter
+
+skill-linter checks a repo of Agent Skills before you commit or release it, and keeps the counts and version numbers in its docs current. One `[tool.skill-linter]` table in `pyproject.toml` configures it, so a new skill repo gets the same checks as the others without copying `validate-skills.py`, `validate-markdown.py` and `update-docs.py` into it.
+
+It needs Python 3.11 or later. PyYAML is the only dependency, used for workflow YAML.
+
+```sh
+uvx skill-linter check        # run without installing
+pipx install skill-linter     # or install it once
+```
+
+Status: early (0.x). Rule names and config keys may still change between minor versions.
+
+## Commands
+
+```text
+skill-linter check   [--only GROUP[,GROUP]] [--skill NAME] [--format text|json] [--root PATH]
+skill-linter stamp   [--check] [--dry-run] [--root PATH]
+skill-linter release [--format text|json] [--root PATH]
+skill-linter rules   [--format text|json]
+```
+
+- `check` runs every enabled rule except the release checks.
+- `stamp` counts skills, references, workflows and domains, then writes those counts and the version from `version.json` into the files you list. `--check` writes nothing and exits 1 when anything is stale.
+- `release` checks the tree the plugin directory will read (`plugin_root` or a `ship` list), then runs `check`.
+- `rules` lists every rule with its group, layer and severity after your overrides.
+
+`skill-linter --version` prints the installed version. Exit codes: 0 when there are no errors, 1 when there are errors or stale stamps, 2 for a usage or config error. `python -m skill_linter` runs the same CLI.
+
+## Rules
+
+Rules come in three layers:
+
+1. The [Agent Skills specification](https://agentskills.io/specification) (`SPEC-01` to `SPEC-10`). You can't switch these off.
+2. Conventions shared across the skill repos: frontmatter metadata, the description rule, Markdown lint, workflow definitions, hidden conventions such as the docs backlink and title safety, and the plugin-directory release checks (`CONV`, `DESC`, `MD`, `WF`, `H`, `P`). Each one can be switched off or lowered to a warning.
+3. Per-repo policy (`POL`, `LINK`, and your own `X-` rules). A policy rule runs only once you give it a value.
+
+Every rule has an ID and a name, such as `POL-03` and `section-order`. Output shows both, and the config accepts either. Run `skill-linter rules` for the full list.
+
+### Cross-skill references
+
+A skill can cite a file in a sibling skill or in a shared folder, written from the skill root: `` `../vue-expert/references/components.md` `` or `` `../_shared/markup-convention.md` ``. The spec wants every reference to stay inside the skill folder, so `SPEC-10` (`reference-depth`) leaves these paths to two other rules:
+
+- `CONV-15` (`cross-skill-references`) checks that the file exists, that the folder is a skill or is listed in `shared_dirs`, and that a cited skill appears in `metadata.related-skills` (a warning when it doesn't).
+- `P17` (`cross-skill-targets-ship`) checks that the cited file ships with the plugin. A skill installed on its own won't find its sibling, so these references only work when the whole plugin is installed.
+
+## Configuration
+
+Everything lives under `[tool.skill-linter]` in the repo's `pyproject.toml`. Unknown keys and unknown rule IDs are errors, so a typo can't switch a check off without anyone noticing. `tests/adoption/` holds complete configs for claude-skills and writing-with-agents.
+
+```toml
+[tool.skill-linter]
+skills_dir = "plugin/skills"
+shared_dirs = ["_shared"]
+commands_dir = "plugin/commands"
+plugin_root = "plugin"
+docs_url = "https://example.github.io/my-skills/skills/{domain}/{name}/"
+
+[tool.skill-linter.policy]
+workflow_steps = [5, 7]
+license = "MIT"
+
+[tool.skill-linter.severity]
+plugin-icon = "off"   # or P10
+
+[[tool.skill-linter.rules.custom]]
+id = "X-lead-support"
+target = "body"
+pattern = '(?is)\blead\b.*\bsupport\b'
+severity = "warning"
+message = "Name a lead and a support role"
+```
+
+Custom rules are regular expressions applied to a frontmatter field, a section, the last line, the body or the reference files. Config never runs code.
+
+### Stamping
+
+Each `[[tool.skill-linter.stamp.files]]` entry names a file and how to update it:
+
+```toml
+[[tool.skill-linter.stamp.files]]
+path = "README.md"   # .md, .mdx and .html files get marker stamping by default
+patterns = [
+  { key = "version", regex = 'version-([\d.]+)-blue\.svg' },
+  { key = "referenceFileCount.{skill}", regex = '(?m)^\s+(?P<skill>[\w-]+)/\s+\(SKILL\.md \+ (?P<count>\d+) reference(?P<s>s?)\)' },
+]
+
+[[tool.skill-linter.stamp.files]]
+path = ".claude-plugin/marketplace.json"
+json = { "/metadata/version" = "version", "/plugins/0/version" = "version" }
+patterns = [{ key = "skillCount", regex = '(\d+) specialized skills' }]
+```
+
+- Markers: `<!-- SKILL_COUNT -->67<!-- /SKILL_COUNT -->`, and likewise `WORKFLOW_COUNT`, `REFERENCE_COUNT`, `DOMAIN_COUNT` and `VERSION`. `SKILL_COUNT:<domain>` counts one domain and `REFERENCE_COUNT:<skill>` counts one skill's references.
+- `json` maps a JSON Pointer to a key and replaces only that value, leaving the file's formatting alone.
+- `patterns` replace the one group in each regex. A pattern that matches nothing is an error, which catches a sentence reworded after its pattern was written.
+- The key `referenceFileCount.{skill}` stamps a count per skill, for places where an HTML comment would show up as text, such as a file tree inside a code block. Its regex names the skill and count groups. The optional `s` group becomes `s` unless the count is 1, and a line that names no skill is an error.
+
+## Development
+
+```sh
+uv sync
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+```
+
+The adoption tests export pinned commits of the two skill repos with `git archive` and skip when those checkouts aren't present. One of them runs each repo's own `update-docs.py` and `skill-linter stamp` on the same change and checks that every file comes out identical.

skill_linter-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "skill-linter"
+version = "0.1.0"
+description = "Validate Agent Skills repos: spec checks, shared conventions, per-repo policy, count stamping and plugin release checks"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Jeff Smolinski" }]
+dependencies = ["pyyaml>=6"]
+
+[project.urls]
+Repository = "https://github.com/Jeffallan/skill-linter"
+Issues = "https://github.com/Jeffallan/skill-linter/issues"
+
+[project.scripts]
+skill-linter = "skill_linter.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.17"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/skill_linter"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["adoption: runs against pinned commits of the real skill repos (skips when absent)"]

skill_linter-0.1.0/src/skill_linter/__init__.py

@@ -0,0 +1 @@
+"""skill-linter: validate Agent Skills repos."""

skill_linter-0.1.0/src/skill_linter/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from skill_linter.cli import main
+
+sys.exit(main())

skill_linter-0.1.0/src/skill_linter/cli.py

@@ -0,0 +1,216 @@
+"""Command-line interface: skill-linter check | release | stamp | rules."""
+
+from __future__ import annotations
+
+import argparse
+import difflib
+import json
+import re
+import sys
+from importlib.metadata import version
+from pathlib import Path
+
+from skill_linter import model, release, stamp
+from skill_linter.config import Config, ConfigError, find_root, load_config
+from skill_linter.engine import all_rules, effective_severity, run, validate_config
+from skill_linter.repo import Repo
+from skill_linter.report import format_json, format_text
+
+EXIT_OK, EXIT_ERRORS, EXIT_USAGE = 0, 1, 2
+CHECK_EXCLUDES = frozenset({"release"})
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="skill-linter", description="Validate an Agent Skills repo."
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"skill-linter {version('skill-linter')}"
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    check = sub.add_parser(
+        "check", help="run every enabled rule except the release checks"
+    )
+    check.add_argument("--only", help="comma-separated rule groups to run")
+    check.add_argument(
+        "--skill", help="limit skill rules to one skill and skip repo rules"
+    )
+    check.add_argument("--format", choices=("text", "json"), default="text")
+    check.add_argument(
+        "--root",
+        type=Path,
+        help="repo root (default: nearest pyproject.toml with the table)",
+    )
+    check.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="also show info issues and skipped rules",
+    )
+
+    release_cmd = sub.add_parser(
+        "release", help="run the plugin release checks on the shipped tree, then check"
+    )
+    release_cmd.add_argument("--format", choices=("text", "json"), default="text")
+    release_cmd.add_argument("--root", type=Path)
+    release_cmd.add_argument("-v", "--verbose", action="store_true")
+
+    stamp = sub.add_parser(
+        "stamp",
+        help="write counts and the version into version.json and the stamp files",
+    )
+    stamp.add_argument(
+        "--check",
+        action="store_true",
+        help="write nothing; exit 1 if anything is stale",
+    )
+    stamp.add_argument(
+        "--dry-run", action="store_true", help="print the diff; write nothing"
+    )
+    stamp.add_argument("--root", type=Path)
+
+    rules = sub.add_parser("rules", help="list every rule")
+    rules.add_argument("--format", choices=("text", "json"), default="text")
+    rules.add_argument("--root", type=Path)
+    return parser
+
+
+def _load(root: Path | None) -> Config:
+    cfg = load_config(root.resolve()) if root else load_config(find_root(Path.cwd()))
+    validate_config(cfg)
+    return cfg
+
+
+def _groups() -> set[str]:
+    return {r.group for r in model.REGISTRY.values()} | {"custom"}
+
+
+def cmd_check(args) -> int:
+    groups = None
+    if args.only:
+        groups = {g.strip() for g in args.only.split(",") if g.strip()}
+        unknown = groups - _groups()
+        if unknown:
+            print(
+                f"unknown rule group(s): {', '.join(sorted(unknown))}", file=sys.stderr
+            )
+            return EXIT_USAGE
+    cfg = _load(args.root)
+    report = run(
+        Repo(cfg),
+        groups=groups,
+        skill=args.skill,
+        exclude_groups=CHECK_EXCLUDES - (groups or set()),
+    )
+    print(
+        format_json(report, cfg.root)
+        if args.format == "json"
+        else format_text(report, args.verbose)
+    )
+    return EXIT_ERRORS if report.has_errors else EXIT_OK
+
+
+def cmd_release(args) -> int:
+    cfg = _load(args.root)
+    repo = Repo(cfg)
+    release.shipped_tree(
+        repo
+    )  # config error (exit 2) when neither plugin_root nor ship is set
+    report = run(repo)
+    print(
+        format_json(report, cfg.root)
+        if args.format == "json"
+        else format_text(report, args.verbose)
+    )
+    return EXIT_ERRORS if report.has_errors else EXIT_OK
+
+
+def cmd_stamp(args) -> int:
+    repo = Repo(_load(args.root))
+    changes, errors = stamp.plan(repo)
+    for message in errors:
+        print(f"error: {message}", file=sys.stderr)
+    if errors:
+        return EXIT_ERRORS
+    if args.dry_run:
+        for rel, (old, new) in changes.items():
+            sys.stdout.writelines(
+                difflib.unified_diff(
+                    old.splitlines(True), new.splitlines(True), f"a/{rel}", f"b/{rel}"
+                )
+            )
+        return EXIT_OK
+    if args.check:
+        for rel in changes:
+            print(f"stale: {rel}")
+        return EXIT_ERRORS if changes else EXIT_OK
+    stamp.write(repo, changes)
+    for rel in changes:
+        print(f"stamped: {rel}")
+    return EXIT_OK
+
+
+LAYERS = {1: "spec", 2: "convention", 3: "policy"}
+
+
+def _rule_order(r) -> tuple:
+    """Registration order of groups, then IDs in numeric order (H01 before H16)."""
+    groups = list(dict.fromkeys(x.group for x in model.REGISTRY.values()))
+    prefix, number = re.match(r"^(.*?)(\d*)$", r.id).groups()
+    rank = groups.index(r.group) if r.group in groups else len(groups)
+    return (rank, prefix, int(number) if number else 0, r.id)
+
+
+def cmd_rules(args) -> int:
+    try:
+        cfg = _load(args.root)
+    except ConfigError:
+        if args.root:
+            raise
+        cfg = None
+    rows = []
+    rules = all_rules(cfg) if cfg is not None else list(model.REGISTRY.values())
+    for r in sorted(rules, key=_rule_order):
+        row = {
+            "id": r.id,
+            "name": r.name,
+            "group": r.group,
+            "layer": r.layer,
+            "default": r.severity.value,
+            "overridable": r.overridable,
+            "summary": r.summary,
+        }
+        if cfg is not None:
+            row["effective"] = effective_severity(cfg, r).value
+        rows.append(row)
+    if args.format == "json":
+        print(json.dumps(rows, indent=2))
+    else:
+        name_width = max(len(row["name"]) for row in rows)
+        for row in rows:
+            sev = row.get("effective", row["default"])
+            print(
+                f"{row['id']:<8}  {row['name']:<{name_width}}  {row['group']:<12}  "
+                f"{LAYERS[row['layer']]:<10}  {sev:<7}  {row['summary']}"
+            )
+    return EXIT_OK
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        commands = {
+            "check": cmd_check,
+            "release": cmd_release,
+            "stamp": cmd_stamp,
+            "rules": cmd_rules,
+        }
+        return commands[args.command](args)
+    except ConfigError as exc:
+        print(f"config error: {exc}", file=sys.stderr)
+        return EXIT_USAGE
+
+
+if __name__ == "__main__":
+    sys.exit(main())

skill_linter-0.1.0/src/skill_linter/commands.py

@@ -0,0 +1,117 @@
+"""Command files, their YAML definitions, and plugin locations, shared by the hidden and workflow rules."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from skill_linter.repo import Repo
+
+
+@dataclass
+class Definition:
+    file: Path
+    rel: str
+    data: dict[str, Any] | None
+    error: str | None
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self.data.get(key, default) if isinstance(self.data, dict) else default
+
+
+def load_yaml(text: str) -> tuple[Any, str | None]:
+    try:
+        return yaml.safe_load(text), None
+    except yaml.YAMLError as exc:
+        return None, str(exc).replace("\n", " ")
+
+
+def commands_dir(repo: Repo) -> Path | None:
+    return repo.cfg.path(repo.cfg.commands_dir) if repo.cfg.commands_dir else None
+
+
+def manifest_path(repo: Repo) -> Path | None:
+    if repo.cfg.manifest:
+        return repo.cfg.path(repo.cfg.manifest)
+    base = commands_dir(repo)
+    return base / "workflow-manifest.yaml" if base else None
+
+
+def definitions(repo: Repo) -> list[Definition]:
+    cached = getattr(repo, "_definitions", None)
+    if cached is not None:
+        return cached
+    base = commands_dir(repo)
+    found: list[Definition] = []
+    manifest = manifest_path(repo)
+    if base and base.is_dir():
+        for path in sorted(base.rglob("*.yaml")):
+            if manifest and path.resolve() == manifest.resolve():
+                continue
+            data, error = load_yaml(repo.read(path))
+            if error is None and not isinstance(data, dict):
+                error = "definition must be a YAML mapping"
+                data = None
+            found.append(Definition(path, repo.rel(path), data, error))
+    repo._definitions = found
+    return found
+
+
+def command_files(repo: Repo) -> list[Path]:
+    """Every .md under the commands folder, except files inside a references/ folder."""
+    base = commands_dir(repo)
+    if not base or not base.is_dir():
+        return []
+    return sorted(
+        p for p in base.rglob("*.md") if "references" not in p.relative_to(base).parts
+    )
+
+
+def frontmatter_block(text: str) -> str | None:
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return None
+    for index in range(1, len(lines)):
+        if lines[index].strip() == "---":
+            return "\n".join(lines[1:index])
+    return None
+
+
+def command_frontmatter(text: str) -> tuple[dict[str, Any] | None, str | None]:
+    """(data, error). data is None with no error when the file has no frontmatter."""
+    block = frontmatter_block(text)
+    if block is None:
+        if text.splitlines()[:1] == ["---"]:
+            return None, "frontmatter opened with --- but never closed"
+        return None, None
+    data, error = load_yaml(block)
+    if error:
+        return None, error
+    if data is None:
+        return {}, None
+    if not isinstance(data, dict):
+        return None, "frontmatter must be a YAML mapping"
+    return data, None
+
+
+def plugin_dir(repo: Repo) -> Path:
+    return repo.cfg.path(repo.cfg.plugin_root) if repo.cfg.plugin_root else repo.root
+
+
+def plugin_json_path(repo: Repo) -> Path:
+    return plugin_dir(repo) / ".claude-plugin" / "plugin.json"
+
+
+def marketplace_path(repo: Repo) -> Path:
+    return repo.root / ".claude-plugin" / "marketplace.json"
+
+
+def skill_and_command_files(repo: Repo, pattern: str = "*.md") -> list[Path]:
+    paths: list[Path] = []
+    for base in (repo.skills_dir, commands_dir(repo)):
+        if base and base.is_dir():
+            paths.extend(p for p in sorted(base.rglob(pattern)) if p.is_file())
+    return paths