skill-drift 0.1.0__py3-none-any.whl

skill_drift/__init__.py

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

skill_drift/__main__.py

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

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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+skill_drift/__init__.py,sha256=tlreCNmeuLuObBv65Yy4Z3mq_UtdNz9oSt3dK0ByKGw,66
+skill_drift/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+skill_drift/audit.py,sha256=EvgDX-YFlpE95w98MWdBatYLPyCP5n5OMABCgDk6MH0,4657
+skill_drift/cli.py,sha256=2_5ikg5D2YsCqnkapQ_MDh7kqZy_1mvt4EWyEywyIQM,1949
+skill_drift/skills.py,sha256=c8AbYAXs5Nkdk3znLfxCEK4mErnxQaeqDoISOZM64l8,2992
+skill_drift-0.1.0.dist-info/licenses/LICENSE,sha256=BY32OKHQwPwe_UT_YvyEpQOiKWFIyUZHQ7yXG4iWt-c,1081
+skill_drift-0.1.0.dist-info/METADATA,sha256=hEE2ABUvZcXgP6GkKvhIPQtCsKEJfVsuY85VBFm8_Nk,7031
+skill_drift-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+skill_drift-0.1.0.dist-info/entry_points.txt,sha256=eDM-LCBeV1WO8M2TAo4Vl-cXKT03MF9QEebLYQMoPt0,53
+skill_drift-0.1.0.dist-info/top_level.txt,sha256=BtvcRxlm-UvndS0_1uZeli_k9XObfb2uGNt0VI5jrHA,12
+skill_drift-0.1.0.dist-info/RECORD,,

skill_drift-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

skill_drift-0.1.0.dist-info/entry_points.txt

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

skill_drift-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

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