skill-drift 0.1.0__tar.gz

skill_drift-0.1.0/LICENSE

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

skill_drift-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: skill-drift
+Version: 0.1.0
+Summary: Offline heuristic auditing of skill package claims
+Author: skill-drift contributors
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# skill-drift
+
+`skill-drift` 0.1.0 checks whether an agent skill package's stated paths and
+basic metadata still match the disk. It is deterministic, offline, and uses
+only the Python standard library at runtime: no daemon, LLM, network, or keys.
+A finding means **check this claim**.
+
+Requires Python 3.9+. Install with `pip install .`, or install a built wheel.
+
+```sh
+skill-drift audit [path] [--json] [--fail-on high|medium] [--ignore G]
+skill-drift --version
+skill-drift --help
+python -m skill_drift audit .
+```
+
+Path defaults to the current directory. Repeat `--ignore` for multiple glob
+patterns; patterns match the claim text, apply to all checks, and excluded
+unique findings are counted as ignored.
+
+## Discovery and parsing
+
+A package is any directory containing a file named exactly `SKILL.md`.
+Discovery recursively includes the supplied directory itself and hidden
+folders such as `.claude/skills` and `.cursor/skills`. It skips `.git`,
+`node_modules`, `dist`, `__pycache__`, `.venv`, and `venv`; directory symlinks
+are not traversed. No packages gives PASS, exit 0, and `no skills found`.
+Unreadable or invalid UTF-8 SKILL.md files produce parse errors.
+
+The file must begin with an exact `---` line and close its frontmatter with
+another `---` line. Supported YAML is a subset: `key: value`, quoted or
+unquoted scalar values, and block lists under a key. Blank lines and full-line
+comments are accepted. Nested maps, anchors, tags, flow collections, multiline
+scalars, duplicate keys, and malformed blocks are parse errors. Name and
+description must be scalars. Quoted values are treated literally, without
+YAML escape processing; inline comments are not interpreted.
+
+## Checks and severities
+
+| Kind | Severity | Trigger |
+| --- | --- | --- |
+| missing-frontmatter | HIGH | No opening frontmatter delimiter |
+| missing-name | HIGH | Missing or empty name |
+| missing-description | HIGH | Missing or empty description |
+| name-mismatch | MEDIUM | Name differs from package directory name |
+| referenced-file | HIGH | Referenced path does not exist |
+| script-not-executable | MEDIUM | Referenced scripts/ file has neither any executable bit nor a shebang |
+| duplicate-skill-name | MEDIUM | Same nonempty name appears in multiple packages; each package is flagged |
+| empty-body | MEDIUM | Stripped body has fewer than 50 characters |
+
+Name and description are HIGH by design because they make a skill loadable
+and discoverable. Name matching is a convention, not universal across hosts.
+
+Path checks inspect the body after frontmatter, using backticked or bare
+tokens containing `/` and ending in `.py`, `.js`, `.ts`, `.md`, `.json`,
+`.yaml`, `.yml`, `.toml`, `.sh`, `.go`, `.rs`, or `.txt`, plus references
+under `scripts/`, `references/`, `examples/`, `tests/`, `docs/`, and `bin/`.
+URLs beginning http:// or https://, absolute paths, and tokens containing `*`
+are skipped. Paths resolve against the skill directory first, then the audit
+root. A trailing slash requires a directory. Shebang detection checks the
+first two bytes for `#!`; permission checks inspect mode bits.
+
+Findings include skill directory relative to the root, file, 1-based line,
+kind, claim, severity, and detail. Metadata diagnostics use the opening lines;
+body path diagnostics use their actual line. Findings deduplicate by
+(skill, line, kind, claim). At most 500 are displayed, ordered by skill then
+line (then kind and claim); truncation and omitted count are explicit.
+Totals and verdict include all unignored findings, including omitted ones.
+Human and JSON reports contain the same counts, per-kind and per-severity
+totals, ignored count, parse-error count, and verdict.
+
+## Exit codes
+
+| Code | Verdict | Meaning |
+| --- | --- | --- |
+| 0 | PASS | No unignored findings or parse errors |
+| 1 | WARN | Findings exist, all below the threshold |
+| 2 | FAIL | Any finding reaches the threshold, or any parse error |
+
+Default threshold is HIGH. With `--fail-on medium`, every finding fails.
+An invalid audit path also produces exit 2. CLI argument errors use argparse's
+exit 2. The warn-only case uses exit 1 even though no finding reaches the
+threshold.
+
+## Examples
+
+All included examples are synthetic and need no credentials or services.
+
+```sh
+skill-drift audit examples/sample-skills/good-skill
+# PASS: 1 skills found; no findings; exit 0
+skill-drift audit examples/sample-skills/broken-skill
+# FAIL: 1 skills found; exit 2
+# HIGH missing-description: description
+# MEDIUM name-mismatch: outdated-skill
+# HIGH referenced-file: scripts/renamed.sh
+# HIGH referenced-file: references/moved.md
+skill-drift audit examples/sample-skills/broken-skill --json
+# Valid JSON: HIGH=3, MEDIUM=1, verdict=FAIL, exit_code=2
+```
+
+The good package references an executable `scripts/check.sh`. The broken
+package demonstrates a missing description, mismatched name, missing script,
+and missing reference. The actual report also includes locations and details.
+
+## Limitations
+
+Checks are heuristic pattern matching, not semantic judgement. Paraphrased
+claims are not checked. Commands are never executed; only their path tokens
+are checked. Paths with spaces and unusual punctuation may be missed or
+misidentified. Existence says nothing about correctness, safety, importability,
+or successful execution. External targets and glob expansions are not checked.
+The YAML subset rejects complex YAML instead of guessing. Filesystem changes
+during a run can affect results; this is a snapshot-style audit, not a monitor.
+
+## Differentiation
+
+- **instruction-drift** audits instruction files (AGENTS.md, CLAUDE.md,
+  MUSE.md, CONTRIBUTING.md) against a repository. This audits skill packages:
+  SKILL.md, frontmatter, scripts, and references against the disk.
+- **skill-tax** audits what a SKILL.md costs in tokens. This audits whether
+  the skill still works through its checkable package claims.
+- **skill-pin-verify** audits pinning/signatures. This audits the truth of
+  package contents through offline heuristics.
+- **frontmatter-guard** audits plugin.json manifests. This audits SKILL.md
+  frontmatter.
+- **Heavy runtimes** require more infrastructure. This is an offline stdlib
+  CLI with no daemon, no LLM, and no network.
+
+## Development
+
+```sh
+PYTHONPATH=src python -m unittest discover -s tests -v
+python -m build
+python -m venv /tmp/skill-drift-smoke
+/tmp/skill-drift-smoke/bin/pip install dist/skill_drift-0.1.0-py3-none-any.whl
+/tmp/skill-drift-smoke/bin/skill-drift audit examples/sample-skills/good-skill
+```
+
+Tests use unittest, temporary synthetic fixtures, and no network. Setuptools
+and wheel are build-time dependencies; `build` is the development frontend.
+Build artifacts are local only and should be removed before sharing a tree.
+
+MIT licensed. See LICENSE.

skill_drift-0.1.0/README.md

@@ -0,0 +1,144 @@
+# skill-drift
+
+`skill-drift` 0.1.0 checks whether an agent skill package's stated paths and
+basic metadata still match the disk. It is deterministic, offline, and uses
+only the Python standard library at runtime: no daemon, LLM, network, or keys.
+A finding means **check this claim**.
+
+Requires Python 3.9+. Install with `pip install .`, or install a built wheel.
+
+```sh
+skill-drift audit [path] [--json] [--fail-on high|medium] [--ignore G]
+skill-drift --version
+skill-drift --help
+python -m skill_drift audit .
+```
+
+Path defaults to the current directory. Repeat `--ignore` for multiple glob
+patterns; patterns match the claim text, apply to all checks, and excluded
+unique findings are counted as ignored.
+
+## Discovery and parsing
+
+A package is any directory containing a file named exactly `SKILL.md`.
+Discovery recursively includes the supplied directory itself and hidden
+folders such as `.claude/skills` and `.cursor/skills`. It skips `.git`,
+`node_modules`, `dist`, `__pycache__`, `.venv`, and `venv`; directory symlinks
+are not traversed. No packages gives PASS, exit 0, and `no skills found`.
+Unreadable or invalid UTF-8 SKILL.md files produce parse errors.
+
+The file must begin with an exact `---` line and close its frontmatter with
+another `---` line. Supported YAML is a subset: `key: value`, quoted or
+unquoted scalar values, and block lists under a key. Blank lines and full-line
+comments are accepted. Nested maps, anchors, tags, flow collections, multiline
+scalars, duplicate keys, and malformed blocks are parse errors. Name and
+description must be scalars. Quoted values are treated literally, without
+YAML escape processing; inline comments are not interpreted.
+
+## Checks and severities
+
+| Kind | Severity | Trigger |
+| --- | --- | --- |
+| missing-frontmatter | HIGH | No opening frontmatter delimiter |
+| missing-name | HIGH | Missing or empty name |
+| missing-description | HIGH | Missing or empty description |
+| name-mismatch | MEDIUM | Name differs from package directory name |
+| referenced-file | HIGH | Referenced path does not exist |
+| script-not-executable | MEDIUM | Referenced scripts/ file has neither any executable bit nor a shebang |
+| duplicate-skill-name | MEDIUM | Same nonempty name appears in multiple packages; each package is flagged |
+| empty-body | MEDIUM | Stripped body has fewer than 50 characters |
+
+Name and description are HIGH by design because they make a skill loadable
+and discoverable. Name matching is a convention, not universal across hosts.
+
+Path checks inspect the body after frontmatter, using backticked or bare
+tokens containing `/` and ending in `.py`, `.js`, `.ts`, `.md`, `.json`,
+`.yaml`, `.yml`, `.toml`, `.sh`, `.go`, `.rs`, or `.txt`, plus references
+under `scripts/`, `references/`, `examples/`, `tests/`, `docs/`, and `bin/`.
+URLs beginning http:// or https://, absolute paths, and tokens containing `*`
+are skipped. Paths resolve against the skill directory first, then the audit
+root. A trailing slash requires a directory. Shebang detection checks the
+first two bytes for `#!`; permission checks inspect mode bits.
+
+Findings include skill directory relative to the root, file, 1-based line,
+kind, claim, severity, and detail. Metadata diagnostics use the opening lines;
+body path diagnostics use their actual line. Findings deduplicate by
+(skill, line, kind, claim). At most 500 are displayed, ordered by skill then
+line (then kind and claim); truncation and omitted count are explicit.
+Totals and verdict include all unignored findings, including omitted ones.
+Human and JSON reports contain the same counts, per-kind and per-severity
+totals, ignored count, parse-error count, and verdict.
+
+## Exit codes
+
+| Code | Verdict | Meaning |
+| --- | --- | --- |
+| 0 | PASS | No unignored findings or parse errors |
+| 1 | WARN | Findings exist, all below the threshold |
+| 2 | FAIL | Any finding reaches the threshold, or any parse error |
+
+Default threshold is HIGH. With `--fail-on medium`, every finding fails.
+An invalid audit path also produces exit 2. CLI argument errors use argparse's
+exit 2. The warn-only case uses exit 1 even though no finding reaches the
+threshold.
+
+## Examples
+
+All included examples are synthetic and need no credentials or services.
+
+```sh
+skill-drift audit examples/sample-skills/good-skill
+# PASS: 1 skills found; no findings; exit 0
+skill-drift audit examples/sample-skills/broken-skill
+# FAIL: 1 skills found; exit 2
+# HIGH missing-description: description
+# MEDIUM name-mismatch: outdated-skill
+# HIGH referenced-file: scripts/renamed.sh
+# HIGH referenced-file: references/moved.md
+skill-drift audit examples/sample-skills/broken-skill --json
+# Valid JSON: HIGH=3, MEDIUM=1, verdict=FAIL, exit_code=2
+```
+
+The good package references an executable `scripts/check.sh`. The broken
+package demonstrates a missing description, mismatched name, missing script,
+and missing reference. The actual report also includes locations and details.
+
+## Limitations
+
+Checks are heuristic pattern matching, not semantic judgement. Paraphrased
+claims are not checked. Commands are never executed; only their path tokens
+are checked. Paths with spaces and unusual punctuation may be missed or
+misidentified. Existence says nothing about correctness, safety, importability,
+or successful execution. External targets and glob expansions are not checked.
+The YAML subset rejects complex YAML instead of guessing. Filesystem changes
+during a run can affect results; this is a snapshot-style audit, not a monitor.
+
+## Differentiation
+
+- **instruction-drift** audits instruction files (AGENTS.md, CLAUDE.md,
+  MUSE.md, CONTRIBUTING.md) against a repository. This audits skill packages:
+  SKILL.md, frontmatter, scripts, and references against the disk.
+- **skill-tax** audits what a SKILL.md costs in tokens. This audits whether
+  the skill still works through its checkable package claims.
+- **skill-pin-verify** audits pinning/signatures. This audits the truth of
+  package contents through offline heuristics.
+- **frontmatter-guard** audits plugin.json manifests. This audits SKILL.md
+  frontmatter.
+- **Heavy runtimes** require more infrastructure. This is an offline stdlib
+  CLI with no daemon, no LLM, and no network.
+
+## Development
+
+```sh
+PYTHONPATH=src python -m unittest discover -s tests -v
+python -m build
+python -m venv /tmp/skill-drift-smoke
+/tmp/skill-drift-smoke/bin/pip install dist/skill_drift-0.1.0-py3-none-any.whl
+/tmp/skill-drift-smoke/bin/skill-drift audit examples/sample-skills/good-skill
+```
+
+Tests use unittest, temporary synthetic fixtures, and no network. Setuptools
+and wheel are build-time dependencies; `build` is the development frontend.
+Build artifacts are local only and should be removed before sharing a tree.
+
+MIT licensed. See LICENSE.

skill_drift-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "skill-drift"
+version = "0.1.0"
+description = "Offline heuristic auditing of skill package claims"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [{name = "skill-drift contributors"}]
+dependencies = []
+
+[project.scripts]
+skill-drift = "skill_drift.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

skill_drift-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

skill_drift-0.1.0/src/skill_drift/__init__.py

@@ -0,0 +1,2 @@
+"""Offline skill package drift auditing."""
+__version__ = '0.1.0'

skill_drift-0.1.0/src/skill_drift/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

skill_drift-0.1.0/src/skill_drift/audit.py

@@ -0,0 +1,89 @@
+"""Offline heuristic checks; never executes package code."""
+from collections import Counter
+from dataclasses import asdict, dataclass
+from fnmatch import fnmatchcase
+from pathlib import Path
+import re
+from .skills import discover, read_skill
+
+@dataclass
+class Finding:
+    skill: str
+    file: str
+    line: int
+    kind: str
+    claim: str
+    severity: str
+    detail: str
+
+TOKEN = re.compile(r'`([^`\n]+)`|([^\s`<>"\']+)')
+EXT = re.compile(r'\.(py|js|ts|md|json|yaml|yml|toml|sh|go|rs|txt)$')
+DIR = re.compile(r'^(?:\./)?(?:scripts|references|examples|tests|docs|bin)/')
+
+
+def claims(line):
+    for match in TOKEN.finditer(line):
+        token = (match[1] or match[2]).strip('()[]{}.,;:!?')
+        if token.startswith(('http://', 'https://', '/', '~/', '\\')) or '*' in token or re.match(r'^[A-Za-z]:[/\\]', token):
+            continue
+        if '/' in token and (EXT.search(token) or DIR.match(token)):
+            yield token
+
+
+def audit(root, fail_on='high', ignore=(), limit=500):
+    root = Path(root).resolve()
+    packages = [read_skill(p) for p in discover(root)]
+    findings = []
+    errors = []
+    names = Counter(s.metadata.get('name') for s in packages if s.metadata.get('name'))
+    ignored = 0
+    seen = set()
+    for skill in packages:
+        relative = skill.directory.relative_to(root).as_posix()
+        if skill.error:
+            errors.append({'skill': relative, 'file': 'SKILL.md', 'line': 1, 'detail': skill.error})
+            continue
+        def add(line, kind, claim, severity, detail):
+            nonlocal ignored
+            key = (relative, line, kind, claim)
+            if key in seen:
+                return
+            seen.add(key)
+            if any(fnmatchcase(claim, pattern) for pattern in ignore):
+                ignored += 1
+                return
+            findings.append(Finding(relative, 'SKILL.md', line, kind, claim, severity, detail))
+        if skill.missing_frontmatter:
+            add(1, 'missing-frontmatter', 'frontmatter', 'HIGH', 'Expected opening --- frontmatter line')
+        else:
+            for key in ('name', 'description'):
+                if not skill.metadata.get(key, '').strip():
+                    add(1, 'missing-' + key, key, 'HIGH', 'Required nonempty frontmatter field')
+            name = skill.metadata.get('name')
+            if name and name != skill.directory.name:
+                add(2, 'name-mismatch', name, 'MEDIUM', 'Directory name is ' + skill.directory.name)
+            if name and names[name] > 1:
+                add(2, 'duplicate-skill-name', name, 'MEDIUM', 'Name occurs in multiple skill packages')
+        if len(skill.body.strip()) < 50:
+            add(skill.body_line, 'empty-body', 'body', 'MEDIUM', 'Body is shorter than 50 characters')
+        for number, line in enumerate(skill.body.splitlines(), skill.body_line):
+            for claim in claims(line):
+                local = skill.directory / claim
+                target = local if local.exists() else root / claim
+                exists = target.is_dir() if claim.endswith('/') else target.exists()
+                if not exists:
+                    add(number, 'referenced-file', claim, 'HIGH', 'Referenced path does not exist')
+                elif re.match(r'^(?:\./)?scripts/', claim) and target.is_file():
+                    try:
+                        shebang = target.open('rb')
+                        with shebang:
+                            starts = shebang.read(2) == b'#!'
+                        if not target.stat().st_mode & 0o111 and not starts:
+                            add(number, 'script-not-executable', claim, 'MEDIUM', 'No executable bit and no shebang')
+                    except OSError as error:
+                        errors.append({'skill': relative, 'file': claim, 'line': number, 'detail': str(error)})
+    findings.sort(key=lambda f: (f.skill, f.line, f.kind, f.claim))
+    # Verdict considers all findings, including those beyond the display cap.
+    failed = bool(errors) or any(f.severity == 'HIGH' or fail_on == 'medium' for f in findings)
+    code = 2 if failed else (1 if findings else 0)
+    return {'skills_found': len(packages), 'totals': {'kind': dict(sorted(Counter(f.kind for f in findings).items())), 'severity': dict(sorted(Counter(f.severity for f in findings).items()))}, 'findings': [asdict(f) for f in findings[:limit]], 'ignored_count': ignored, 'parse_error_count': len(errors), 'parse_errors': errors, 'truncated': len(findings) > limit, 'omitted_count': max(0, len(findings)-limit), 'verdict': ('FAIL' if code == 2 else 'WARN' if code == 1 else 'PASS'), 'exit_code': code, 'note': 'no skills found' if not packages else ''}

skill_drift-0.1.0/src/skill_drift/cli.py

@@ -0,0 +1,34 @@
+"""Command line interface."""
+import argparse
+import json
+from . import __version__
+from .audit import audit
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog='skill-drift', description='Audit skill package claims offline')
+    parser.add_argument('--version', action='version', version='%(prog)s ' + __version__)
+    commands = parser.add_subparsers(dest='command', required=True)
+    command = commands.add_parser('audit')
+    command.add_argument('path', nargs='?', default='.')
+    command.add_argument('--json', action='store_true')
+    command.add_argument('--fail-on', choices=('high', 'medium'), default='high')
+    command.add_argument('--ignore', action='append', default=[], metavar='G')
+    args = parser.parse_args(argv)
+    try:
+        report = audit(args.path, args.fail_on, args.ignore)
+    except (ValueError, OSError) as error:
+        report = {'skills_found': 0, 'totals': {'kind': {}, 'severity': {}}, 'findings': [], 'ignored_count': 0, 'parse_error_count': 1, 'parse_errors': [{'skill': '.', 'file': 'SKILL.md', 'line': 1, 'detail': str(error)}], 'truncated': False, 'omitted_count': 0, 'verdict': 'FAIL', 'exit_code': 2, 'note': ''}
+    if args.json:
+        print(json.dumps(report, sort_keys=True))
+    else:
+        print('%s: %s skills found' % (report['verdict'], report['skills_found']))
+        if report['note']:
+            print(report['note'])
+        for finding in report['findings']:
+            print('{skill}:{file}:{line}: {severity} {kind}: {claim} — {detail}'.format(**finding))
+        for error in report['parse_errors']:
+            print('{skill}:{file}:{line}: parse error: {detail}'.format(**error))
+        print('Totals: ' + json.dumps(report['totals'], sort_keys=True))
+        print('Ignored: %s; parse errors: %s; truncated: %s (omitted %s)' % (report['ignored_count'], report['parse_error_count'], report['truncated'], report['omitted_count']))
+    return report['exit_code']

skill_drift-0.1.0/src/skill_drift/skills.py

@@ -0,0 +1,81 @@
+"""Deterministic discovery and deliberately small frontmatter parser."""
+from dataclasses import dataclass
+from pathlib import Path
+import os
+import re
+
+SKIP = {'.git', 'node_modules', 'dist', '__pycache__', '.venv', 'venv'}
+
+@dataclass
+class Skill:
+    directory: Path
+    metadata: dict
+    body: str
+    body_line: int
+    error: str = ''
+    missing_frontmatter: bool = False
+
+
+def discover(root):
+    root = Path(root)
+    if not root.is_dir():
+        raise ValueError('audit path must be an existing directory')
+    found = []
+    def walk_error(error):
+        raise ValueError(str(error))
+    for directory, dirs, files in os.walk(root, onerror=walk_error):
+        dirs[:] = sorted(d for d in dirs if d not in SKIP)
+        if 'SKILL.md' in files:
+            found.append(Path(directory))
+    return sorted(found, key=lambda p: p.relative_to(root).as_posix())
+
+
+def scalar(value):
+    value = value.strip()
+    if not value:
+        return ''
+    if value[0] in "\"'":
+        if len(value) < 2 or value[-1] != value[0]:
+            raise ValueError('unterminated quoted scalar')
+        return value[1:-1]
+    if re.search(r'(^|\s)[&*!]|:\s|^[>|\[\]{}]|^[-?]\s', value):
+        raise ValueError('unsupported complex YAML scalar')
+    return value
+
+
+def read_skill(directory):
+    directory = Path(directory)
+    try:
+        lines = (directory / 'SKILL.md').read_text(encoding='utf-8').splitlines()
+        if not lines or lines[0] != '---':
+            return Skill(directory, {}, '\n'.join(lines), 1, missing_frontmatter=True)
+        try:
+            end = lines.index('---', 1)
+        except ValueError:
+            raise ValueError('frontmatter has no closing --- line')
+        metadata = {}
+        current = None
+        for number, line in enumerate(lines[1:end], 2):
+            if not line.strip() or line.lstrip().startswith('#'):
+                continue
+            item = re.fullmatch(r'\s+-\s+(.+)', line)
+            if item and current:
+                if metadata[current] == '':
+                    metadata[current] = []
+                if not isinstance(metadata[current], list):
+                    raise ValueError('list under nonempty scalar')
+                metadata[current].append(scalar(item[1]))
+                continue
+            match = re.fullmatch(r'([A-Za-z_][\w-]*):\s*(.*)', line)
+            if not match:
+                raise ValueError('unsupported YAML at line %s' % number)
+            current = match[1]
+            if current in metadata:
+                raise ValueError('duplicate frontmatter key: ' + current)
+            metadata[current] = scalar(match[2])
+        for key in ('name', 'description'):
+            if key in metadata and not isinstance(metadata[key], str):
+                raise ValueError(key + ' must be a scalar')
+        return Skill(directory, metadata, '\n'.join(lines[end+1:]), end+2)
+    except (OSError, UnicodeError, ValueError) as error:
+        return Skill(directory, {}, '', 1, error=str(error))

skill_drift-0.1.0/src/skill_drift.egg-info/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: skill-drift
+Version: 0.1.0
+Summary: Offline heuristic auditing of skill package claims
+Author: skill-drift contributors
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# skill-drift
+
+`skill-drift` 0.1.0 checks whether an agent skill package's stated paths and
+basic metadata still match the disk. It is deterministic, offline, and uses
+only the Python standard library at runtime: no daemon, LLM, network, or keys.
+A finding means **check this claim**.
+
+Requires Python 3.9+. Install with `pip install .`, or install a built wheel.
+
+```sh
+skill-drift audit [path] [--json] [--fail-on high|medium] [--ignore G]
+skill-drift --version
+skill-drift --help
+python -m skill_drift audit .
+```
+
+Path defaults to the current directory. Repeat `--ignore` for multiple glob
+patterns; patterns match the claim text, apply to all checks, and excluded
+unique findings are counted as ignored.
+
+## Discovery and parsing
+
+A package is any directory containing a file named exactly `SKILL.md`.
+Discovery recursively includes the supplied directory itself and hidden
+folders such as `.claude/skills` and `.cursor/skills`. It skips `.git`,
+`node_modules`, `dist`, `__pycache__`, `.venv`, and `venv`; directory symlinks
+are not traversed. No packages gives PASS, exit 0, and `no skills found`.
+Unreadable or invalid UTF-8 SKILL.md files produce parse errors.
+
+The file must begin with an exact `---` line and close its frontmatter with
+another `---` line. Supported YAML is a subset: `key: value`, quoted or
+unquoted scalar values, and block lists under a key. Blank lines and full-line
+comments are accepted. Nested maps, anchors, tags, flow collections, multiline
+scalars, duplicate keys, and malformed blocks are parse errors. Name and
+description must be scalars. Quoted values are treated literally, without
+YAML escape processing; inline comments are not interpreted.
+
+## Checks and severities
+
+| Kind | Severity | Trigger |
+| --- | --- | --- |
+| missing-frontmatter | HIGH | No opening frontmatter delimiter |
+| missing-name | HIGH | Missing or empty name |
+| missing-description | HIGH | Missing or empty description |
+| name-mismatch | MEDIUM | Name differs from package directory name |
+| referenced-file | HIGH | Referenced path does not exist |
+| script-not-executable | MEDIUM | Referenced scripts/ file has neither any executable bit nor a shebang |
+| duplicate-skill-name | MEDIUM | Same nonempty name appears in multiple packages; each package is flagged |
+| empty-body | MEDIUM | Stripped body has fewer than 50 characters |
+
+Name and description are HIGH by design because they make a skill loadable
+and discoverable. Name matching is a convention, not universal across hosts.
+
+Path checks inspect the body after frontmatter, using backticked or bare
+tokens containing `/` and ending in `.py`, `.js`, `.ts`, `.md`, `.json`,
+`.yaml`, `.yml`, `.toml`, `.sh`, `.go`, `.rs`, or `.txt`, plus references
+under `scripts/`, `references/`, `examples/`, `tests/`, `docs/`, and `bin/`.
+URLs beginning http:// or https://, absolute paths, and tokens containing `*`
+are skipped. Paths resolve against the skill directory first, then the audit
+root. A trailing slash requires a directory. Shebang detection checks the
+first two bytes for `#!`; permission checks inspect mode bits.
+
+Findings include skill directory relative to the root, file, 1-based line,
+kind, claim, severity, and detail. Metadata diagnostics use the opening lines;
+body path diagnostics use their actual line. Findings deduplicate by
+(skill, line, kind, claim). At most 500 are displayed, ordered by skill then
+line (then kind and claim); truncation and omitted count are explicit.
+Totals and verdict include all unignored findings, including omitted ones.
+Human and JSON reports contain the same counts, per-kind and per-severity
+totals, ignored count, parse-error count, and verdict.
+
+## Exit codes
+
+| Code | Verdict | Meaning |
+| --- | --- | --- |
+| 0 | PASS | No unignored findings or parse errors |
+| 1 | WARN | Findings exist, all below the threshold |
+| 2 | FAIL | Any finding reaches the threshold, or any parse error |
+
+Default threshold is HIGH. With `--fail-on medium`, every finding fails.
+An invalid audit path also produces exit 2. CLI argument errors use argparse's
+exit 2. The warn-only case uses exit 1 even though no finding reaches the
+threshold.
+
+## Examples
+
+All included examples are synthetic and need no credentials or services.
+
+```sh
+skill-drift audit examples/sample-skills/good-skill
+# PASS: 1 skills found; no findings; exit 0
+skill-drift audit examples/sample-skills/broken-skill
+# FAIL: 1 skills found; exit 2
+# HIGH missing-description: description
+# MEDIUM name-mismatch: outdated-skill
+# HIGH referenced-file: scripts/renamed.sh
+# HIGH referenced-file: references/moved.md
+skill-drift audit examples/sample-skills/broken-skill --json
+# Valid JSON: HIGH=3, MEDIUM=1, verdict=FAIL, exit_code=2
+```
+
+The good package references an executable `scripts/check.sh`. The broken
+package demonstrates a missing description, mismatched name, missing script,
+and missing reference. The actual report also includes locations and details.
+
+## Limitations
+
+Checks are heuristic pattern matching, not semantic judgement. Paraphrased
+claims are not checked. Commands are never executed; only their path tokens
+are checked. Paths with spaces and unusual punctuation may be missed or
+misidentified. Existence says nothing about correctness, safety, importability,
+or successful execution. External targets and glob expansions are not checked.
+The YAML subset rejects complex YAML instead of guessing. Filesystem changes
+during a run can affect results; this is a snapshot-style audit, not a monitor.
+
+## Differentiation
+
+- **instruction-drift** audits instruction files (AGENTS.md, CLAUDE.md,
+  MUSE.md, CONTRIBUTING.md) against a repository. This audits skill packages:
+  SKILL.md, frontmatter, scripts, and references against the disk.
+- **skill-tax** audits what a SKILL.md costs in tokens. This audits whether
+  the skill still works through its checkable package claims.
+- **skill-pin-verify** audits pinning/signatures. This audits the truth of
+  package contents through offline heuristics.
+- **frontmatter-guard** audits plugin.json manifests. This audits SKILL.md
+  frontmatter.
+- **Heavy runtimes** require more infrastructure. This is an offline stdlib
+  CLI with no daemon, no LLM, and no network.
+
+## Development
+
+```sh
+PYTHONPATH=src python -m unittest discover -s tests -v
+python -m build
+python -m venv /tmp/skill-drift-smoke
+/tmp/skill-drift-smoke/bin/pip install dist/skill_drift-0.1.0-py3-none-any.whl
+/tmp/skill-drift-smoke/bin/skill-drift audit examples/sample-skills/good-skill
+```
+
+Tests use unittest, temporary synthetic fixtures, and no network. Setuptools
+and wheel are build-time dependencies; `build` is the development frontend.
+Build artifacts are local only and should be removed before sharing a tree.
+
+MIT licensed. See LICENSE.

skill_drift-0.1.0/src/skill_drift.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+src/skill_drift/__init__.py
+src/skill_drift/__main__.py
+src/skill_drift/audit.py
+src/skill_drift/cli.py
+src/skill_drift/skills.py
+src/skill_drift.egg-info/PKG-INFO
+src/skill_drift.egg-info/SOURCES.txt
+src/skill_drift.egg-info/dependency_links.txt
+src/skill_drift.egg-info/entry_points.txt
+src/skill_drift.egg-info/top_level.txt
+tests/test_audit.py
+tests/test_cli.py
+tests/test_discovery.py

skill_drift-0.1.0/src/skill_drift.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

skill_drift-0.1.0/src/skill_drift.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+skill-drift = skill_drift.cli:main

skill_drift-0.1.0/src/skill_drift.egg-info/top_level.txt

@@ -0,0 +1 @@
+skill_drift

skill_drift-0.1.0/tests/test_audit.py

@@ -0,0 +1,88 @@
+import tempfile
+import unittest
+from pathlib import Path
+from skill_drift.audit import audit
+
+BODY = 'Follow this synthetic procedure carefully using local fixture data only. '
+
+class AuditTests(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory(); self.addCleanup(self.tmp.cleanup)
+        self.root = Path(self.tmp.name)
+    def skill(self, name='demo', front=None, body=BODY):
+        p = self.root/name; p.mkdir(parents=True, exist_ok=True)
+        (p/'SKILL.md').write_text('---\n'+(front if front is not None else 'name: '+name+'\ndescription: synthetic')+'\n---\n'+body)
+        return p
+    def report(self, **kw): return audit(self.root, **kw)
+    def kinds(self): return self.report()['totals']['kind']
+    def test_good(self):
+        self.skill(); self.assertEqual(self.report()['exit_code'], 0)
+    def test_missing_frontmatter(self):
+        p=self.skill(); (p/'SKILL.md').write_text(BODY)
+        self.assertEqual(self.kinds(), {'missing-frontmatter':1}); self.assertEqual(self.report()['exit_code'],2)
+    def test_missing_name(self):
+        self.skill(front='description: synthetic'); self.assertEqual(self.kinds(), {'missing-name':1})
+    def test_empty_name(self):
+        self.skill(front='name: ""\ndescription: synthetic'); self.assertIn('missing-name',self.kinds())
+    def test_missing_description(self):
+        self.skill(front='name: demo'); self.assertEqual(self.report()['totals']['severity'], {'HIGH':1})
+    def test_empty_description(self):
+        self.skill(front='name: demo\ndescription:'); self.assertIn('missing-description',self.kinds())
+    def test_mismatch_warn(self):
+        self.skill(front='name: other\ndescription: synthetic'); self.assertEqual(self.report()['exit_code'],1)
+    def test_mismatch_fail(self):
+        self.skill(front='name: other\ndescription: synthetic'); self.assertEqual(self.report(fail_on='medium')['exit_code'],2)
+    def test_missing_reference(self):
+        self.skill(body=BODY+'`references/missing.md`'); self.assertEqual(self.kinds(), {'referenced-file':1})
+    def test_existing_reference(self):
+        p=self.skill(body=BODY+'references/a.md'); (p/'references').mkdir(); (p/'references/a.md').touch()
+        self.assertEqual(self.report()['exit_code'],0)
+    def test_script_no_exec(self):
+        p=self.skill(body=BODY+'scripts/a.sh'); (p/'scripts').mkdir(); f=p/'scripts/a.sh'; f.write_text('echo synthetic'); f.chmod(0o644)
+        self.assertEqual(self.kinds(), {'script-not-executable':1})
+    def test_script_shebang(self):
+        p=self.skill(body=BODY+'scripts/a.sh'); (p/'scripts').mkdir(); f=p/'scripts/a.sh'; f.write_text('#!/bin/sh\n'); f.chmod(0o644)
+        self.assertEqual(self.report()['exit_code'],0)
+    def test_script_exec(self):
+        p=self.skill(body=BODY+'scripts/a.sh'); (p/'scripts').mkdir(); f=p/'scripts/a.sh'; f.touch(); f.chmod(0o755)
+        self.assertEqual(self.report()['exit_code'],0)
+    def test_skipped_tokens(self):
+        self.skill(body=BODY+'`https://example.invalid/a.md` http://example.invalid/b.py /abs/a.md `scripts/*.sh`')
+        self.assertEqual(self.report()['exit_code'],0)
+    def test_root_fallback(self):
+        self.skill(body=BODY+'docs/a.md'); (self.root/'docs').mkdir(); (self.root/'docs/a.md').touch()
+        self.assertEqual(self.report()['exit_code'],0)
+    def test_local_precedence(self):
+        p=self.skill(body=BODY+'scripts/a.sh'); (p/'scripts').mkdir(); f=p/'scripts/a.sh'; f.write_text('#!/bin/sh'); f.chmod(0o644)
+        (self.root/'scripts').mkdir(); f=self.root/'scripts/a.sh'; f.touch(); f.chmod(0o644)
+        self.assertEqual(self.report()['exit_code'],0)
+    def test_duplicate_names(self):
+        self.skill(); self.skill('other',front='name: demo\ndescription: synthetic')
+        self.assertEqual(self.kinds()['duplicate-skill-name'],2)
+    def test_short_body(self):
+        self.skill(body='short'); self.assertEqual(self.kinds(), {'empty-body':1})
+    def test_body_boundary(self):
+        self.skill(body='x'*50); self.assertEqual(self.report()['exit_code'],0)
+    def test_ignore(self):
+        self.skill(body=BODY+'scripts/missing.sh references/missing.md')
+        r=self.report(ignore=['scripts/*','references/*']); self.assertEqual(r['ignored_count'],2); self.assertEqual(r['exit_code'],0)
+    def test_dedup(self):
+        self.skill(body=BODY+'scripts/a.sh `scripts/a.sh`'); self.assertEqual(self.kinds()['referenced-file'],1)
+    def test_distinct_lines(self):
+        self.skill(body=BODY+'scripts/a.sh\nscripts/a.sh'); self.assertEqual(self.kinds()['referenced-file'],2)
+    def test_directory_claim(self):
+        p=self.skill(body=BODY+'references/'); self.assertEqual(self.report()['exit_code'],2)
+        (p/'references').mkdir(); self.assertEqual(self.report()['exit_code'],0)
+    def test_directory_cannot_be_file(self):
+        p=self.skill(body=BODY+'docs/'); (p/'docs').touch(); self.assertEqual(self.report()['exit_code'],2)
+    def test_realistic(self):
+        self.skill(front='name: old\ndescription: synthetic',body=BODY+'`scripts/old.py` `references/old.md`')
+        self.assertEqual(self.report()['totals']['severity'], {'HIGH':2,'MEDIUM':1}); self.assertEqual(self.report()['exit_code'],2)
+    def test_cap(self):
+        self.skill(body=BODY+'\n'+'\n'.join('docs/%s.md'%i for i in range(510)))
+        r=self.report(); self.assertEqual(len(r['findings']),500); self.assertEqual(r['omitted_count'],10); self.assertTrue(r['truncated']); self.assertEqual(r['totals']['kind']['referenced-file'],510)
+    def test_order(self):
+        self.skill('z',body=BODY+'docs/z.md'); self.skill('a',body=BODY+'docs/a.md')
+        self.assertEqual([f['skill'] for f in self.report()['findings']], ['a','z'])
+    def test_body_line(self):
+        self.skill(body=BODY+'docs/a.md'); self.assertEqual(self.report()['findings'][0]['line'],5)

skill_drift-0.1.0/tests/test_cli.py

@@ -0,0 +1,49 @@
+import contextlib
+import io
+import json
+import tempfile
+import unittest
+from pathlib import Path
+from skill_drift.cli import main
+
+class CliTests(unittest.TestCase):
+    def setUp(self):
+        self.tmp=tempfile.TemporaryDirectory(); self.addCleanup(self.tmp.cleanup); self.root=Path(self.tmp.name)
+    def run_cli(self,*args):
+        output=io.StringIO()
+        with contextlib.redirect_stdout(output): code=main(list(args))
+        return code,output.getvalue()
+    def write(self,front='name: demo\ndescription: synthetic',body='Synthetic instructions for a local fixture with sufficient detail.'):
+        p=self.root/'demo'; p.mkdir(exist_ok=True); (p/'SKILL.md').write_text('---\n'+front+'\n---\n'+body)
+    def test_no_skills(self):
+        code,out=self.run_cli('audit',str(self.root)); self.assertEqual(code,0); self.assertIn('no skills found',out)
+    def test_good(self):
+        self.write(); self.assertEqual(self.run_cli('audit',str(self.root))[0],0)
+    def test_high(self):
+        self.write(front='name: demo'); self.assertEqual(self.run_cli('audit',str(self.root))[0],2)
+    def test_warn(self):
+        self.write(front='name: old\ndescription: synthetic'); self.assertEqual(self.run_cli('audit',str(self.root))[0],1)
+    def test_medium_threshold(self):
+        self.write(front='name: old\ndescription: synthetic'); self.assertEqual(self.run_cli('audit',str(self.root),'--fail-on','medium')[0],2)
+    def test_json(self):
+        self.write(); code,out=self.run_cli('audit',str(self.root),'--json'); r=json.loads(out); self.assertEqual(code,r['exit_code']); self.assertEqual(r['verdict'],'PASS')
+    def test_parse_error(self):
+        self.write(front='name: demo\ndescription: |'); code,out=self.run_cli('audit',str(self.root),'--json'); self.assertEqual(code,2); self.assertEqual(json.loads(out)['parse_error_count'],1)
+    def test_missing_path(self):
+        code,out=self.run_cli('audit',str(self.root/'missing'),'--json'); self.assertEqual(code,2); self.assertEqual(json.loads(out)['parse_error_count'],1)
+    def test_repeat_ignore(self):
+        self.write(body='Synthetic instructions with adequate detail. scripts/a.sh docs/a.md')
+        code,out=self.run_cli('audit',str(self.root),'--ignore','scripts/*','--ignore','docs/*','--json'); self.assertEqual(code,0); self.assertEqual(json.loads(out)['ignored_count'],2)
+    def test_version(self):
+        out=io.StringIO()
+        with contextlib.redirect_stdout(out), self.assertRaises(SystemExit) as cm: main(['--version'])
+        self.assertEqual(cm.exception.code,0); self.assertIn('0.1.0',out.getvalue())
+    def test_help(self):
+        with contextlib.redirect_stdout(io.StringIO()), self.assertRaises(SystemExit) as cm: main(['--help'])
+        self.assertEqual(cm.exception.code,0)
+    def test_missing_frontmatter(self):
+        self.write(); (self.root/'demo/SKILL.md').write_text('Synthetic instructions with enough characters to pass body length.')
+        code,out=self.run_cli('audit',str(self.root)); self.assertEqual(code,2); self.assertIn('HIGH missing-frontmatter',out)
+    def test_missing_reference(self):
+        self.write(body='Synthetic instructions with enough detail. scripts/missing.sh')
+        self.assertEqual(self.run_cli('audit',str(self.root))[0],2)

skill_drift-0.1.0/tests/test_discovery.py

@@ -0,0 +1,60 @@
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+from skill_drift.skills import discover, read_skill
+
+class DiscoveryTests(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.tmp.cleanup)
+        self.root = Path(self.tmp.name)
+    def skill(self, path='demo', text=None):
+        p = self.root / path
+        p.mkdir(parents=True, exist_ok=True)
+        (p/'SKILL.md').write_text(text if text is not None else '---\nname: demo\ndescription: test\n---\nBody', encoding='utf-8')
+        return p
+    def test_root(self):
+        self.skill('.')
+        self.assertEqual(discover(self.root), [self.root])
+    def test_nested(self):
+        self.assertEqual(discover(self.root), [])
+        self.skill('a/b')
+        self.assertEqual(len(discover(self.root)), 1)
+    def test_hidden(self):
+        self.skill('.claude/skills/demo')
+        self.skill('.cursor/skills/demo')
+        self.assertEqual(len(discover(self.root)), 2)
+    def test_skips(self):
+        for d in ('.git','node_modules','dist','__pycache__','.venv','venv'):
+            self.skill(d+'/demo')
+        self.assertEqual(discover(self.root), [])
+    def test_exact_case(self):
+        (self.root/'skill.md').write_text('test')
+        self.assertEqual(discover(self.root), [])
+    def test_sorted(self):
+        self.skill('z'); self.skill('a')
+        self.assertEqual([p.name for p in discover(self.root)], ['a','z'])
+    def test_bad_path(self):
+        with self.assertRaises(ValueError): discover(self.root/'absent')
+    def test_bad_utf8(self):
+        p = self.skill(); (p/'SKILL.md').write_bytes(b'\xff')
+        self.assertTrue(read_skill(p).error)
+    def test_permission_error(self):
+        p = self.skill()
+        with patch.object(Path, 'read_text', side_effect=PermissionError('denied')):
+            self.assertIn('denied', read_skill(p).error)
+    def test_quotes_lists(self):
+        s = read_skill(self.skill(text='---\nname: "demo"\ndescription: \'test\'\nfiles:\n  - a.md\n  - "b.md"\n---\nBody'))
+        self.assertFalse(s.error)
+        self.assertEqual(s.metadata['files'], ['a.md','b.md'])
+    def test_missing_close(self):
+        self.assertTrue(read_skill(self.skill(text='---\nname: demo')).error)
+    def test_complex_yaml(self):
+        for field in ('description: |','description: >','description: &anchor value','description: {a: b}','description: [a, b]','extra:\n  nested: value','description: *anchor'):
+            with self.subTest(field=field):
+                self.assertTrue(read_skill(self.skill(text='---\nname: demo\n'+field+'\n---\nBody')).error)
+    def test_duplicate_key(self):
+        self.assertTrue(read_skill(self.skill(text='---\nname: a\nname: b\n---\nBody')).error)
+    def test_unterminated_quote(self):
+        self.assertTrue(read_skill(self.skill(text='---\nname: "demo\n---\nBody')).error)