skillcheck 0.1.0__tar.gz

skillcheck-0.1.0/.claude/settings.local.json

@@ -0,0 +1,21 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(pip install:*)",
+      "Bash(skillcheck --version)",
+      "Bash(python -m pytest tests/ -v)",
+      "Bash(skillcheck tests/fixtures/valid_basic.md)",
+      "Bash(skillcheck tests/fixtures/bad_name_caps.md)",
+      "Bash(echo \"exit: $?\")",
+      "Bash(skillcheck tests/fixtures/bad_name_caps.md --format json)",
+      "Bash(python3 -m json.tool --no-ensure-ascii)",
+      "Bash(for f:*)",
+      "Bash(do echo:*)",
+      "Bash(python3 -m pytest tests/ -v)",
+      "Bash(skillcheck /home/brad/projects/skillcheck/SKILL.md)",
+      "Bash(skillcheck /home/brad/projects/skillcheck/SKILL.md --format json)",
+      "Bash(python3 -m pytest tests/test_sizing.py -v)",
+      "Bash(python3 -m pytest tests/)"
+    ]
+  }
+}

skillcheck-0.1.0/.github/banner.svg

@@ -0,0 +1,26 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 200" fill="none">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="800" y2="200" gradientUnits="userSpaceOnUse">
+      <stop offset="0%" stop-color="#0f0f23"/>
+      <stop offset="100%" stop-color="#1a1a3e"/>
+    </linearGradient>
+    <linearGradient id="accent" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#d4a574"/>
+      <stop offset="100%" stop-color="#e8c9a0"/>
+    </linearGradient>
+  </defs>
+  <rect width="800" height="200" rx="12" fill="url(#bg)"/>
+  <!-- check icon -->
+  <g transform="translate(280, 55)">
+    <circle cx="40" cy="40" r="36" stroke="url(#accent)" stroke-width="3" fill="none" opacity="0.9"/>
+    <polyline points="22,42 36,56 60,28" stroke="#4ade80" stroke-width="4.5" stroke-linecap="round" stroke-linejoin="round" fill="none"/>
+  </g>
+  <!-- title -->
+  <text x="400" y="108" text-anchor="middle" font-family="ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,monospace" font-size="42" font-weight="700" fill="url(#accent)">
+    <tspan dx="52">skillcheck</tspan>
+  </text>
+  <!-- subtitle -->
+  <text x="400" y="142" text-anchor="middle" font-family="-apple-system,BlinkMacSystemFont,Segoe UI,Helvetica,Arial,sans-serif" font-size="15" fill="#8b8ba7" letter-spacing="0.5">
+    Static analyzer for Claude Code SKILL.md files
+  </text>
+</svg>

skillcheck-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.env
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+*.egg
+CLAUDE.md

skillcheck-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 skillcheck contributors
+
+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.

skillcheck-0.1.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: skillcheck
+Version: 0.1.0
+Summary: Validates Claude Code SKILL.md files against the Anthropic skill specification
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: tiktoken
+Requires-Dist: tiktoken>=0.7; extra == 'tiktoken'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset=".github/banner.svg">
+  <source media="(prefers-color-scheme: light)" srcset=".github/banner.svg">
+  <img alt="skillcheck" src=".github/banner.svg" width="600">
+</picture>
+
+<br/>
+
+**Static analyzer for Claude Code `SKILL.md` files.**<br/>
+Validates frontmatter structure and body sizing against the Anthropic skill specification.
+
+<br/>
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776ab.svg)](https://python.org)
+[![PyYAML](https://img.shields.io/badge/deps-PyYAML-yellow.svg)](https://pyyaml.org)
+[![Tests](https://img.shields.io/badge/tests-73%20passed-brightgreen.svg)](#testing)
+
+</div>
+
+---
+
+## What It Does
+
+`skillcheck` catches problems in your `SKILL.md` files before they hit production:
+
+- **Frontmatter validation** — required fields, character constraints, length limits, reserved words, first/second-person voice, XML tags, unknown fields
+- **Body sizing** — line count and token estimate warnings to keep skills within context-window budgets
+- **CI-friendly** — JSON output, deterministic exit codes, zero config
+
+## Install
+
+```bash
+pip install skillcheck
+```
+
+Or install from source with dev dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```bash
+# Validate a single file
+skillcheck path/to/SKILL.md
+
+# Scan a directory recursively for all SKILL.md files
+skillcheck skills/
+
+# Machine-readable output for CI pipelines
+skillcheck skills/ --format json
+```
+
+## Example Output
+
+```
+✔ PASS  skills/deploy.md
+
+✗ FAIL  skills/pdf-tool.md
+  line 2  ✗ error    frontmatter.name.invalid-chars  Name contains uppercase chars
+  line 3  ⚠ warning  frontmatter.field.unknown       Unknown field 'author'
+
+Checked 2 files: 1 passed, 1 failed, 1 warning
+```
+
+## Options
+
+| Flag | Description |
+|---|---|
+| `--format json` | Machine-readable JSON output |
+| `--max-lines N` | Override line-count threshold (default: 500) |
+| `--max-tokens N` | Override token-count threshold (default: 8000) |
+| `--ignore PREFIX` | Suppress rules matching a prefix (repeatable) |
+| `--no-color` | Disable colored output |
+| `--version` | Show version |
+
+### Examples
+
+```bash
+# Override sizing thresholds
+skillcheck skills/ --max-lines 800 --max-tokens 6000
+
+# Suppress specific rule categories
+skillcheck SKILL.md --ignore frontmatter.description
+
+# Pipe-friendly plain output
+skillcheck SKILL.md --no-color
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|---|---|
+| `0` | No errors (warnings are allowed) |
+| `1` | One or more errors found |
+| `2` | Input error (missing file, empty directory) |
+
+## Rules
+
+| Rule ID | Severity | What it checks |
+|---|---|---|
+| `frontmatter.name.required` | error | `name` field must exist |
+| `frontmatter.name.max-length` | error | Name ≤ 64 characters |
+| `frontmatter.name.invalid-chars` | error | Lowercase, numbers, hyphens only |
+| `frontmatter.name.reserved` | error | Not a reserved word (`claude`, `anthropic`, …) |
+| `frontmatter.description.required` | error | `description` field must exist |
+| `frontmatter.description.empty` | error | Description must not be blank |
+| `frontmatter.description.max-length` | error | Description ≤ 1024 characters |
+| `frontmatter.description.xml-tags` | error | No XML/HTML tags in description |
+| `frontmatter.description.person-voice` | error | No first/second-person pronouns |
+| `frontmatter.field.unknown` | warning | Flags fields not in the spec |
+| `sizing.body.line-count` | warning | Body exceeds line threshold |
+| `sizing.body.token-estimate` | warning | Body exceeds token threshold |
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+python3 -m pytest tests/ -v
+```
+
+## License
+
+MIT

skillcheck-0.1.0/README.md

@@ -0,0 +1,128 @@
+<div align="center">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset=".github/banner.svg">
+  <source media="(prefers-color-scheme: light)" srcset=".github/banner.svg">
+  <img alt="skillcheck" src=".github/banner.svg" width="600">
+</picture>
+
+<br/>
+
+**Static analyzer for Claude Code `SKILL.md` files.**<br/>
+Validates frontmatter structure and body sizing against the Anthropic skill specification.
+
+<br/>
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776ab.svg)](https://python.org)
+[![PyYAML](https://img.shields.io/badge/deps-PyYAML-yellow.svg)](https://pyyaml.org)
+[![Tests](https://img.shields.io/badge/tests-73%20passed-brightgreen.svg)](#testing)
+
+</div>
+
+---
+
+## What It Does
+
+`skillcheck` catches problems in your `SKILL.md` files before they hit production:
+
+- **Frontmatter validation** — required fields, character constraints, length limits, reserved words, first/second-person voice, XML tags, unknown fields
+- **Body sizing** — line count and token estimate warnings to keep skills within context-window budgets
+- **CI-friendly** — JSON output, deterministic exit codes, zero config
+
+## Install
+
+```bash
+pip install skillcheck
+```
+
+Or install from source with dev dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```bash
+# Validate a single file
+skillcheck path/to/SKILL.md
+
+# Scan a directory recursively for all SKILL.md files
+skillcheck skills/
+
+# Machine-readable output for CI pipelines
+skillcheck skills/ --format json
+```
+
+## Example Output
+
+```
+✔ PASS  skills/deploy.md
+
+✗ FAIL  skills/pdf-tool.md
+  line 2  ✗ error    frontmatter.name.invalid-chars  Name contains uppercase chars
+  line 3  ⚠ warning  frontmatter.field.unknown       Unknown field 'author'
+
+Checked 2 files: 1 passed, 1 failed, 1 warning
+```
+
+## Options
+
+| Flag | Description |
+|---|---|
+| `--format json` | Machine-readable JSON output |
+| `--max-lines N` | Override line-count threshold (default: 500) |
+| `--max-tokens N` | Override token-count threshold (default: 8000) |
+| `--ignore PREFIX` | Suppress rules matching a prefix (repeatable) |
+| `--no-color` | Disable colored output |
+| `--version` | Show version |
+
+### Examples
+
+```bash
+# Override sizing thresholds
+skillcheck skills/ --max-lines 800 --max-tokens 6000
+
+# Suppress specific rule categories
+skillcheck SKILL.md --ignore frontmatter.description
+
+# Pipe-friendly plain output
+skillcheck SKILL.md --no-color
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|---|---|
+| `0` | No errors (warnings are allowed) |
+| `1` | One or more errors found |
+| `2` | Input error (missing file, empty directory) |
+
+## Rules
+
+| Rule ID | Severity | What it checks |
+|---|---|---|
+| `frontmatter.name.required` | error | `name` field must exist |
+| `frontmatter.name.max-length` | error | Name ≤ 64 characters |
+| `frontmatter.name.invalid-chars` | error | Lowercase, numbers, hyphens only |
+| `frontmatter.name.reserved` | error | Not a reserved word (`claude`, `anthropic`, …) |
+| `frontmatter.description.required` | error | `description` field must exist |
+| `frontmatter.description.empty` | error | Description must not be blank |
+| `frontmatter.description.max-length` | error | Description ≤ 1024 characters |
+| `frontmatter.description.xml-tags` | error | No XML/HTML tags in description |
+| `frontmatter.description.person-voice` | error | No first/second-person pronouns |
+| `frontmatter.field.unknown` | warning | Flags fields not in the spec |
+| `sizing.body.line-count` | warning | Body exceeds line threshold |
+| `sizing.body.token-estimate` | warning | Body exceeds token threshold |
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+python3 -m pytest tests/ -v
+```
+
+## License
+
+MIT

skillcheck-0.1.0/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: git-commit-crafter
+description: Generates conventional commit messages from staged diffs, enforcing semantic versioning conventions and team-defined scopes.
+version: "1.0.0"
+author: brad
+tags:
+  - git
+  - commits
+  - devops
+allowed-tools:
+  - Bash
+user-invocable: true
+---
+
+# git-commit-crafter
+
+Generates conventional commit messages from staged git diffs. Reads the diff, infers the change type and scope, and produces a formatted commit message ready to paste or pipe directly into `git commit`.
+
+## Trigger
+
+Invoke when the user has staged changes and needs a commit message:
+
+```
+/git-commit-crafter
+```
+
+## Behavior
+
+1. Run `git diff --cached` to read the staged changes.
+2. Identify the change type from the diff: `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, or `perf`.
+3. Infer the scope from the files touched (e.g., `auth`, `api`, `cli`, `db`).
+4. Write a subject line under 72 characters in the form `type(scope): imperative summary`.
+5. If the diff spans more than one logical concern, add a short body paragraph per concern.
+6. If any file path contains `BREAKING` or the diff removes a public API surface, append `BREAKING CHANGE:` footer.
+
+## Output format
+
+```
+feat(auth): add OAuth2 PKCE flow for CLI clients
+
+Replaces the implicit grant with PKCE to comply with RFC 9700.
+Adds a local redirect server on a random port for the callback.
+
+Closes #418
+```
+
+## Constraints
+
+- Never invent change details not present in the diff.
+- Do not reference internal ticket numbers unless they appear in branch name or diff.
+- Keep the subject line imperative mood: "add", "fix", "remove", not "added" or "fixes".
+- If the diff is empty, output: `No staged changes found. Run git add first.`
+
+## Scope inference rules
+
+| File path pattern      | Scope      |
+|------------------------|------------|
+| `src/auth/**`          | `auth`     |
+| `src/api/**`           | `api`      |
+| `src/cli/**`           | `cli`      |
+| `src/db/**`            | `db`       |
+| `tests/**`             | `test`     |
+| `docs/**`              | `docs`     |
+| `*.toml`, `*.cfg`      | `config`   |
+| Mixed or root-level    | (omit scope) |

skillcheck-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "skillcheck"
+version = "0.1.0"
+description = "Validates Claude Code SKILL.md files against the Anthropic skill specification"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+dependencies = [
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+]
+tiktoken = [
+    "tiktoken>=0.7",
+]
+
+[project.scripts]
+skillcheck = "skillcheck.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/skillcheck"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

skillcheck-0.1.0/src/skillcheck/__init__.py

@@ -0,0 +1,15 @@
+from skillcheck.core import validate
+from skillcheck.parser import ParsedSkill, ParseError
+from skillcheck.result import Diagnostic, Severity, ValidationResult
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "validate",
+    "ValidationResult",
+    "Diagnostic",
+    "Severity",
+    "ParsedSkill",
+    "ParseError",
+    "__version__",
+]

skillcheck-0.1.0/src/skillcheck/cli.py

@@ -0,0 +1,228 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from skillcheck import __version__
+from skillcheck.core import validate
+from skillcheck.result import Severity, ValidationResult
+
+# ---------------------------------------------------------------------------
+# ANSI helpers (zero dependencies)
+# ---------------------------------------------------------------------------
+
+_RESET = "\033[0m"
+_BOLD = "\033[1m"
+_DIM = "\033[2m"
+_RED = "\033[31m"
+_GREEN = "\033[32m"
+_YELLOW = "\033[33m"
+
+_SEV_SYMBOL = {Severity.ERROR: "✗", Severity.WARNING: "⚠", Severity.INFO: "·"}
+_SEV_COLOR = {Severity.ERROR: _RED, Severity.WARNING: _YELLOW, Severity.INFO: _DIM}
+
+
+def _style(text: str, *codes: str, color: bool = True) -> str:
+    """Wrap *text* in ANSI escape codes when *color* is enabled."""
+    if not color:
+        return text
+    return "".join(codes) + text + _RESET
+
+
+# ---------------------------------------------------------------------------
+# Path collection
+# ---------------------------------------------------------------------------
+
+
+def _collect_paths(target: Path) -> list[Path]:
+    """Return a list of SKILL.md files to validate.
+
+    For a directory, recursively finds all files named exactly 'SKILL.md'.
+    For a file, returns it directly without name filtering.
+    """
+    if target.is_dir():
+        return sorted(target.rglob("SKILL.md"))
+    return [target]
+
+
+# ---------------------------------------------------------------------------
+# Formatters
+# ---------------------------------------------------------------------------
+
+
+def _format_text(results: list[ValidationResult], *, color: bool = False) -> str:
+    lines: list[str] = []
+    for result in results:
+        if result.valid:
+            tag = _style("✔ PASS", _BOLD, _GREEN, color=color)
+        else:
+            tag = _style("✗ FAIL", _BOLD, _RED, color=color)
+        lines.append(f"{tag}  {result.path}")
+
+        for d in result.diagnostics:
+            sym = _SEV_SYMBOL.get(d.severity, "·")
+            sev_col = _SEV_COLOR.get(d.severity, "")
+            loc = f"line {d.line}" if d.line is not None else ""
+            sev_label = _style(f"{sym} {d.severity.value}", sev_col, color=color)
+            rule = _style(d.rule, _DIM, color=color)
+            lines.append(f"  {loc:>8}  {sev_label:<18s}  {rule}  {d.message}")
+            if d.context:
+                ctx = _style(d.context, _DIM, color=color)
+                lines.append(f"{'':>12}  {ctx}")
+
+    # summary
+    total = len(results)
+    passed = sum(1 for r in results if r.valid)
+    failed = total - passed
+    warn_count = sum(
+        1 for r in results for d in r.diagnostics if d.severity == Severity.WARNING
+    )
+    noun = "file" if total == 1 else "files"
+
+    parts = [
+        _style(f"{passed} passed", _GREEN, color=color),
+        _style(f"{failed} failed", _RED, color=color) if failed else f"{failed} failed",
+    ]
+    if warn_count:
+        w = f"{warn_count} warning{'s' if warn_count != 1 else ''}"
+        parts.append(_style(w, _YELLOW, color=color))
+
+    lines.append(f"\nChecked {total} {noun}: {', '.join(parts)}")
+    return "\n".join(lines)
+
+
+def _format_json(results: list[ValidationResult], version: str) -> str:
+    passed = sum(1 for r in results if r.valid)
+    payload = {
+        "version": version,
+        "files_checked": len(results),
+        "files_passed": passed,
+        "files_failed": len(results) - passed,
+        "results": [
+            {
+                "path": str(r.path),
+                "valid": r.valid,
+                "diagnostics": [
+                    {
+                        "rule": d.rule,
+                        "severity": d.severity.value,
+                        "message": d.message,
+                        "line": d.line,
+                        "context": d.context,
+                    }
+                    for d in r.diagnostics
+                ],
+            }
+            for r in results
+        ],
+    }
+    return json.dumps(payload, indent=2)
+
+
+# ---------------------------------------------------------------------------
+# Argument parser
+# ---------------------------------------------------------------------------
+
+_EPILOG = """\
+examples:
+  skillcheck SKILL.md                        validate a single file
+  skillcheck skills/                          scan a directory recursively
+  skillcheck SKILL.md --format json           machine-readable output for CI
+  skillcheck SKILL.md --max-lines 800         override sizing thresholds
+  skillcheck SKILL.md --ignore frontmatter    suppress a rule category
+"""
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="skillcheck",
+        description="Validate Claude Code SKILL.md files against the Anthropic skill specification.",
+        epilog=_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "path",
+        type=Path,
+        help="Path to a SKILL.md file or a directory to scan recursively.",
+    )
+    parser.add_argument(
+        "--format",
+        choices=["text", "json"],
+        default="text",
+        help="Output format (default: text).",
+    )
+    parser.add_argument(
+        "--max-lines",
+        type=int,
+        default=None,
+        metavar="N",
+        help="Override the line-count threshold (default: 500).",
+    )
+    parser.add_argument(
+        "--max-tokens",
+        type=int,
+        default=None,
+        metavar="N",
+        help="Override the token-count threshold (default: 8000).",
+    )
+    parser.add_argument(
+        "--ignore",
+        action="append",
+        dest="ignore_prefixes",
+        metavar="PREFIX",
+        default=[],
+        help="Suppress rules matching this prefix. Can be repeated.",
+    )
+    parser.add_argument(
+        "--no-color",
+        action="store_true",
+        default=False,
+        help="Disable colored output.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    return parser
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+
+def main() -> None:
+    parser = _build_parser()
+    args = parser.parse_args()
+
+    target: Path = args.path
+    if not target.exists():
+        print(f"Error: path not found: {target}", file=sys.stderr)
+        sys.exit(2)
+
+    paths = _collect_paths(target)
+    if not paths:
+        print(f"No SKILL.md files found under: {target}", file=sys.stderr)
+        sys.exit(2)
+
+    results = [
+        validate(
+            p,
+            max_lines=args.max_lines,
+            max_tokens=args.max_tokens,
+            ignore_prefixes=args.ignore_prefixes or None,
+        )
+        for p in paths
+    ]
+
+    if args.format == "json":
+        print(_format_json(results, __version__))
+    else:
+        use_color = not args.no_color and sys.stdout.isatty()
+        print(_format_text(results, color=use_color))
+
+    any_errors = any(not r.valid for r in results)
+    sys.exit(1 if any_errors else 0)