agent-skilldoctor 0.1.0__tar.gz

agent_skilldoctor-0.1.0/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: agent-skilldoctor
+Version: 0.1.0
+Summary: Audit AI agent skill directories: broken SKILL.md files, duplicate and shadowed skills across install roots
+Author: juzorei
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/juzorei/skilldoctor
+Keywords: agent-skills,claude-code,codex,skill-doctor,linting,agent-skills-marketplace
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# skilldoctor
+
+Audit AI agent skill installations: broken SKILL.md files, duplicate skills shadowing each other across install roots.
+
+The silent failure mode of agent skills: the same skill installed in two directories — you edit one, the agent loads the other, and the fix "doesn't work". Or a broken one (bad frontmatter, name mismatch) that never triggers, so the model just doesn't use it — with no error anywhere.
+
+```text
+$ skilldoctor scan
+scanned 4 skill directories, found 48 skills
+
+DUPLICATES / SHADOWING
+  brainstorming
+  -> wins  project zcode   C:\proj\.zcode\skills\brainstorming
+           user   zcode   C:\Users\me\.zcode\skills\brainstorming
+     project-level skills shadow user-level ones in agents that document precedence
+
+BROKEN
+  some-skill (C:\Users\me\.claude\skills\some-skill)
+     - name 'different-name' != directory 'some-skill'
+```
+
+- `skilldoctor scan` — every layout it knows (project + user): `.claude/skills`, `.codex/skills`, `.agents/skills`, `.zcode/skills`, `.cursor/skills`. Exit 1 if anything is wrong: CI-gateable. Conflicts come with a reason and, where the agent documents precedence, the marked winner.
+- `skilldoctor check <skill-dir>` — validate one skill: frontmatter present, name matches the directory, kebab-case, description present and under 1024 chars.
+
+The checks are deliberately mechanical — every one of them corresponds to a real "skill silently doesn't load" failure. `--json` everywhere. Python 3.11+, stdlib only.
+
+Precedence honesty: where an agent documents `project over user`, the winner is marked. Where precedence between roots is undocumented (`.claude` vs `.agents`), skilldoctor reports the duplicate and refuses to guess — that guess is how edits get lost.
+
+Install: `pip install agent-skilldoctor` — or from this repo:
+`pip install "git+https://github.com/juzorei/skilldoctor#subdirectory=tools/skilldoctor"`
+
+The companion agent skill lives in [skills/skill-hygiene-audit](../skills/skill-hygiene-audit): how to read the report, dedupe without losing local edits (diff before delete), fix the broken copies, and re-scan after every install. Skills: `npx skills add juzorei/skilldoctor`.

agent_skilldoctor-0.1.0/README.md

@@ -0,0 +1,32 @@
+# skilldoctor
+
+Audit AI agent skill installations: broken SKILL.md files, duplicate skills shadowing each other across install roots.
+
+The silent failure mode of agent skills: the same skill installed in two directories — you edit one, the agent loads the other, and the fix "doesn't work". Or a broken one (bad frontmatter, name mismatch) that never triggers, so the model just doesn't use it — with no error anywhere.
+
+```text
+$ skilldoctor scan
+scanned 4 skill directories, found 48 skills
+
+DUPLICATES / SHADOWING
+  brainstorming
+  -> wins  project zcode   C:\proj\.zcode\skills\brainstorming
+           user   zcode   C:\Users\me\.zcode\skills\brainstorming
+     project-level skills shadow user-level ones in agents that document precedence
+
+BROKEN
+  some-skill (C:\Users\me\.claude\skills\some-skill)
+     - name 'different-name' != directory 'some-skill'
+```
+
+- `skilldoctor scan` — every layout it knows (project + user): `.claude/skills`, `.codex/skills`, `.agents/skills`, `.zcode/skills`, `.cursor/skills`. Exit 1 if anything is wrong: CI-gateable. Conflicts come with a reason and, where the agent documents precedence, the marked winner.
+- `skilldoctor check <skill-dir>` — validate one skill: frontmatter present, name matches the directory, kebab-case, description present and under 1024 chars.
+
+The checks are deliberately mechanical — every one of them corresponds to a real "skill silently doesn't load" failure. `--json` everywhere. Python 3.11+, stdlib only.
+
+Precedence honesty: where an agent documents `project over user`, the winner is marked. Where precedence between roots is undocumented (`.claude` vs `.agents`), skilldoctor reports the duplicate and refuses to guess — that guess is how edits get lost.
+
+Install: `pip install agent-skilldoctor` — or from this repo:
+`pip install "git+https://github.com/juzorei/skilldoctor#subdirectory=tools/skilldoctor"`
+
+The companion agent skill lives in [skills/skill-hygiene-audit](../skills/skill-hygiene-audit): how to read the report, dedupe without losing local edits (diff before delete), fix the broken copies, and re-scan after every install. Skills: `npx skills add juzorei/skilldoctor`.

agent_skilldoctor-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agent-skilldoctor"
+version = "0.1.0"
+description = "Audit AI agent skill directories: broken SKILL.md files, duplicate and shadowed skills across install roots"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "juzorei" }]
+keywords = ["agent-skills", "claude-code", "codex", "skill-doctor", "linting", "agent-skills-marketplace"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Quality Assurance",
+]
+
+[project.urls]
+Homepage = "https://github.com/juzorei/skilldoctor"
+
+[project.scripts]
+skilldoctor = "skilldoctor.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

agent_skilldoctor-0.1.0/setup.cfg

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

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

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: agent-skilldoctor
+Version: 0.1.0
+Summary: Audit AI agent skill directories: broken SKILL.md files, duplicate and shadowed skills across install roots
+Author: juzorei
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/juzorei/skilldoctor
+Keywords: agent-skills,claude-code,codex,skill-doctor,linting,agent-skills-marketplace
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# skilldoctor
+
+Audit AI agent skill installations: broken SKILL.md files, duplicate skills shadowing each other across install roots.
+
+The silent failure mode of agent skills: the same skill installed in two directories — you edit one, the agent loads the other, and the fix "doesn't work". Or a broken one (bad frontmatter, name mismatch) that never triggers, so the model just doesn't use it — with no error anywhere.
+
+```text
+$ skilldoctor scan
+scanned 4 skill directories, found 48 skills
+
+DUPLICATES / SHADOWING
+  brainstorming
+  -> wins  project zcode   C:\proj\.zcode\skills\brainstorming
+           user   zcode   C:\Users\me\.zcode\skills\brainstorming
+     project-level skills shadow user-level ones in agents that document precedence
+
+BROKEN
+  some-skill (C:\Users\me\.claude\skills\some-skill)
+     - name 'different-name' != directory 'some-skill'
+```
+
+- `skilldoctor scan` — every layout it knows (project + user): `.claude/skills`, `.codex/skills`, `.agents/skills`, `.zcode/skills`, `.cursor/skills`. Exit 1 if anything is wrong: CI-gateable. Conflicts come with a reason and, where the agent documents precedence, the marked winner.
+- `skilldoctor check <skill-dir>` — validate one skill: frontmatter present, name matches the directory, kebab-case, description present and under 1024 chars.
+
+The checks are deliberately mechanical — every one of them corresponds to a real "skill silently doesn't load" failure. `--json` everywhere. Python 3.11+, stdlib only.
+
+Precedence honesty: where an agent documents `project over user`, the winner is marked. Where precedence between roots is undocumented (`.claude` vs `.agents`), skilldoctor reports the duplicate and refuses to guess — that guess is how edits get lost.
+
+Install: `pip install agent-skilldoctor` — or from this repo:
+`pip install "git+https://github.com/juzorei/skilldoctor#subdirectory=tools/skilldoctor"`
+
+The companion agent skill lives in [skills/skill-hygiene-audit](../skills/skill-hygiene-audit): how to read the report, dedupe without losing local edits (diff before delete), fix the broken copies, and re-scan after every install. Skills: `npx skills add juzorei/skilldoctor`.

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

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+src/agent_skilldoctor.egg-info/PKG-INFO
+src/agent_skilldoctor.egg-info/SOURCES.txt
+src/agent_skilldoctor.egg-info/dependency_links.txt
+src/agent_skilldoctor.egg-info/entry_points.txt
+src/agent_skilldoctor.egg-info/top_level.txt
+src/skilldoctor/__init__.py
+src/skilldoctor/__main__.py
+src/skilldoctor/cli.py
+src/skilldoctor/scan.py
+tests/test_skilldoctor.py

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,2 @@
+[console_scripts]
+skilldoctor = skilldoctor.cli:main

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

@@ -0,0 +1 @@
+skilldoctor

agent_skilldoctor-0.1.0/src/skilldoctor/__init__.py

@@ -0,0 +1,3 @@
+"""Agent skill hygiene: broken SKILL.md lints and duplicate/shadow detection."""
+
+__version__ = "0.1.0"

agent_skilldoctor-0.1.0/src/skilldoctor/__main__.py

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

agent_skilldoctor-0.1.0/src/skilldoctor/cli.py

@@ -0,0 +1,129 @@
+"""skilldoctor CLI: audit agent skill directories for broken, duplicate and shadowed skills."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+from .scan import Diagnosis, scan
+
+
+def _skill_json(s):
+    return {"name": s.name, "agent": s.agent, "scope": s.scope, "path": str(s.path),
+            "ok": s.ok, "problems": s.problems}
+
+
+def _conflict_json(c):
+    return {"name": c.name, "reason": c.reason,
+            "winner": str(c.winner.path) if c.winner else None,
+            "copies": [_skill_json(s) for s in c.copies]}
+
+
+def diag_json(diag: Diagnosis) -> dict:
+    return {
+        "dirs_scanned": len(diag.scanned_dirs),
+        "skills_total": len(diag.skills),
+        "broken": [_skill_json(s) for s in diag.broken],
+        "conflicts": [_conflict_json(c) for c in diag.conflicts],
+    }
+
+
+def cmd_scan(args) -> int:
+    diag = scan(base_dir=Path(args.directory).resolve() if args.directory else None)
+    if args.json:
+        print(json.dumps(diag_json(diag), indent=2))
+    else:
+        print(f"scanned {len(diag.scanned_dirs)} skill directories, found {len(diag.skills)} skills\n")
+        if diag.conflicts:
+            print("DUPLICATES / SHADOWING")
+            for c in diag.conflicts:
+                print(f"  {c.name}")
+                for s in c.copies:
+                    mark = "-> wins " if c.winner is s else "          "
+                    print(f"  {mark}{s.scope:<7} {s.agent:<13} {s.path}")
+                print(f"     {c.reason}")
+            print()
+        if diag.broken:
+            print("BROKEN")
+            for s in diag.broken:
+                print(f"  {s.name} ({s.path})")
+                for p in s.problems:
+                    print(f"     - {p}")
+            print()
+        if not diag.conflicts and not diag.broken:
+            print("clean: no duplicates, no broken skills")
+    has_issues = bool(diag.conflicts or diag.broken)
+    return 1 if has_issues else 0
+
+
+def cmd_check(args) -> int:
+    """Check one skill directory: frontmatter validity and lint rules."""
+    from .scan import MAX_DESCRIPTION, NAME_RE, frontmatter
+
+    path = Path(args.skill_dir)
+    skill_md = path / "SKILL.md"
+    problems = []
+    if not path.is_dir():
+        print(f"skilldoctor: error: {path} is not a directory", file=sys.stderr)
+        return 2
+    if not skill_md.is_file():
+        print(json.dumps({"ok": False, "problems": ["missing SKILL.md"]}) if args.json
+              else "BROKEN: missing SKILL.md")
+        return 1
+    fm = frontmatter(skill_md.read_text(encoding="utf-8", errors="replace"))
+    if fm is None:
+        problems.append("no frontmatter block")
+        fm = {}
+    name = str(fm.get("name", "")).strip()
+    desc = str(fm.get("description", "")).strip()
+    if not name:
+        problems.append("missing name")
+    else:
+        if name != path.name:
+            problems.append(f"name {name!r} != directory {path.name!r}")
+        if not NAME_RE.match(name):
+            problems.append(f"name {name!r} is not kebab-case")
+    if not desc:
+        problems.append("empty description (the skill will never trigger)")
+    elif len(desc) > MAX_DESCRIPTION:
+        problems.append(f"description {len(desc)} chars (>{MAX_DESCRIPTION}: may be rejected by some agents)")
+    if args.json:
+        print(json.dumps({"ok": not problems, "problems": problems}, indent=2))
+    else:
+        print("OK" if not problems else "BROKEN")
+        for p in problems:
+            print(f"  - {p}")
+    return 1 if problems else 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="skilldoctor", description=__doc__)
+    parser.add_argument("--version", action="version", version=f"skilldoctor {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("scan", help="scan all known skill directories (project + user) for conflicts")
+    p.add_argument("--directory", help="project root to scan (default: cwd)")
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=cmd_scan)
+
+    p = sub.add_parser("check", help="validate one skill directory's SKILL.md")
+    p.add_argument("skill_dir")
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=cmd_check)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return args.func(args)
+    except OSError as exc:
+        print(f"skilldoctor: error: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

agent_skilldoctor-0.1.0/src/skilldoctor/scan.py

@@ -0,0 +1,163 @@
+"""skilldoctor: find broken, duplicate and shadowed agent skills across install directories.
+
+Agents discover skills from several directories, each with its own precedence.
+The same skill name installed twice is the classic silent failure: the editor
+changes one copy, the agent loads the other. skilldoctor maps every skill
+directory it can find and reports the conflicts.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+NAME_RE = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
+MAX_DESCRIPTION = 1024
+
+# Discovery layouts, by agent. Precedence order documented per agent; where an
+# agent's docs don't specify precedence between dirs, we report duplicates
+# without claiming which one wins (`winner` is None).
+KNOWN_DIRS = {
+    "claude-code": {"project": [".claude/skills"], "user": ["~/.claude/skills"]},
+    "codex": {"project": [".codex/skills"], "user": ["~/.codex/skills"]},
+    "agents-generic": {"project": [".agents/skills"], "user": ["~/.agents/skills"]},
+    "zcode": {"project": [".zcode/skills"], "user": ["~/.zcode/skills"]},
+    "cursor": {"project": [".cursor/skills"], "user": []},
+}
+
+
+@dataclass
+class SkillMeta:
+    name: str
+    path: Path
+    description: str = ""
+    problems: list[str] = field(default_factory=list)
+    agent: str = ""
+    scope: str = ""          # project | user
+
+    @property
+    def ok(self) -> bool:
+        return not self.problems
+
+
+def frontmatter(text: str) -> dict | None:
+    text = text.replace("\r\n", "\n")
+    if not text.startswith("---"):
+        return None
+    end = text.find("\n---", 3)
+    if end < 0:
+        return None
+    block = text[3:end].strip("\n")
+    fields: dict[str, str] = {}
+    for line in block.splitlines():
+        key, sep, value = line.partition(":")
+        if sep and not line.startswith((" ", "\t")):
+            fields[key.strip()] = value.strip()
+    return fields
+
+
+def parse_skill(path: Path, agent: str, scope: str) -> SkillMeta:
+    meta = SkillMeta(name=path.name, path=path, agent=agent, scope=scope)
+    skill_md = path / "SKILL.md"
+    if not skill_md.is_file():
+        meta.problems.append("missing SKILL.md")
+        return meta
+    text = skill_md.read_text(encoding="utf-8", errors="replace")
+    fm = frontmatter(text)
+    if fm is None:
+        meta.problems.append("SKILL.md has no frontmatter block")
+        return meta
+    declared = str(fm.get("name", "")).strip()
+    desc = str(fm.get("description", "")).strip()
+    if not declared:
+        meta.problems.append("frontmatter has no name")
+    else:
+        if declared != path.name:
+            meta.problems.append(f"name {declared!r} != directory {path.name!r}")
+        if not NAME_RE.match(declared):
+            meta.problems.append(f"name {declared!r} is not kebab-case")
+    if not desc:
+        meta.problems.append("empty description (never triggers)")
+    elif len(desc) > MAX_DESCRIPTION:
+        meta.problems.append(f"description {len(desc)} chars (>{MAX_DESCRIPTION}: may be rejected)")
+    meta.description = desc
+    meta.name = declared or path.name
+    return meta
+
+
+def candidates(roots_for: dict[str, dict[str, list[str]]] | None = None,
+               base_dir: Path | None = None) -> list[tuple[str, str, Path]]:
+    """Yield (agent, scope, directory) for every configured layout."""
+    layouts = roots_for or KNOWN_DIRS
+    base = base_dir or Path.cwd()
+    home = Path.home()
+    out = []
+    for agent, scopes in layouts.items():
+        for scope, dirs in scopes.items():
+            for d in dirs:
+                expanded = Path(d)
+                if str(expanded).startswith("~"):
+                    expanded = home / str(expanded)[2:]
+                if not expanded.is_absolute():
+                    expanded = base / expanded
+                out.append((agent, scope, expanded))
+    return out
+
+
+@dataclass
+class Diagnosis:
+    @dataclass
+    class Conflict:
+        name: str
+        copies: list[SkillMeta]
+        winner: SkillMeta | None = None
+        reason: str = ""
+
+    skills: list[SkillMeta] = field(default_factory=list)
+    conflicts: list[Conflict] = field(default_factory=list)
+    scanned_dirs: list[Path] = field(default_factory=list)
+
+    @property
+    def broken(self) -> list[SkillMeta]:
+        return [s for s in self.skills if not s.ok]
+
+
+def scan(roots_for: dict | None = None, base_dir: Path | None = None) -> Diagnosis:
+    diag = Diagnosis()
+    # project scope beats user scope across agents that document precedence;
+    # within the same scope, agent-specific dirs win over the generic .agents
+    order = {"project": 0, "user": 1}
+    by_name: dict[str, list[SkillMeta]] = {}
+    rank: dict[int, int] = {}
+    seen_dirs = set()
+    for agent, scope, d in candidates(roots_for, base_dir):
+        if not d.is_dir():
+            continue
+        real = d.resolve()
+        if real in seen_dirs:
+            continue
+        seen_dirs.add(real)
+        diag.scanned_dirs.append(d)
+        for child in sorted(p for p in d.iterdir() if p.is_dir()):
+            skill = parse_skill(child, agent, scope)
+            diag.skills.append(skill)
+            by_name.setdefault(skill.name, []).append(skill)
+    for name, copies in by_name.items():
+        if len(copies) < 2:
+            continue
+        # winner: project scope first; then non-generic agent; then earlier layout
+        def rank_of(s: SkillMeta, i: int):
+            return (order.get(s.scope, 2), 1 if s.agent == "agents-generic" else 0, i)
+        winner = None
+        if all(s.ok for s in copies):
+            candidate_scopes = {s.scope for s in copies}
+            if len(candidate_scopes) > 1:
+                winner = min(copies, key=lambda s: order.get(s.scope, 1))
+                reason = "project-level skills shadow user-level ones in agents that document precedence"
+            else:
+                reason = "same skill in multiple install roots; which one wins is agent-specific — dedupe to be safe"
+        else:
+            reason = "at least one copy is broken; the working copy may still be shadowed"
+        diag.conflicts.append(Diagnosis.Conflict(name, copies, winner, reason))
+    return diag

agent_skilldoctor-0.1.0/tests/test_skilldoctor.py

@@ -0,0 +1,136 @@
+import json
+
+import pytest
+
+from skilldoctor.cli import main
+from skilldoctor.scan import KNOWN_DIRS, candidates, parse_skill, scan
+
+
+def make_skill(dir_path, name=None, description="does something", fm_name=None, extra=""):
+    d = dir_path / (name or "test-skill") if name else dir_path / "test-skill"
+    d.mkdir(parents=True)
+    fm_name = fm_name if fm_name is not None else d.name
+    body = f"---\nname: {fm_name}\ndescription: {description}\n---\n\n# {d.name}\n{extra}\n"
+    (d / "SKILL.md").write_text(body, encoding="utf-8")
+    return d
+
+
+def pointed_roots(tmp_path):
+    """Point every agent layout at fixtures under tmp_path to keep tests hermetic."""
+    return {
+        "claude-code": {"project": [str(tmp_path / "proj" / ".claude" / "skills")],
+                        "user": [str(tmp_path / "user" / ".claude" / "skills")]},
+        "agents-generic": {"project": [str(tmp_path / "proj" / ".agents" / "skills")],
+                           "user": [str(tmp_path / "user" / ".agents" / "skills")]},
+    }
+
+
+def test_detects_project_shadowing_user(tmp_path):
+    roots = pointed_roots(tmp_path)
+    make_skill(tmp_path / "proj" / ".claude" / "skills", "my-skill")
+    make_skill(tmp_path / "user" / ".claude" / "skills", "my-skill")
+    diag = scan(roots_for=roots, base_dir=tmp_path)
+    assert len(diag.conflicts) == 1
+    conflict = diag.conflicts[0]
+    assert conflict.winner is not None and conflict.winner.scope == "project"
+    assert "shadow" in conflict.reason
+
+
+def test_same_scope_duplicate_flagged_without_false_winner(tmp_path):
+    roots = pointed_roots(tmp_path)
+    make_skill(tmp_path / "user" / ".claude" / "skills", "dup")
+    make_skill(tmp_path / "user" / ".agents" / "skills", "dup")
+    diag = scan(roots_for=roots, base_dir=tmp_path)
+    assert len(diag.conflicts) == 1
+    assert diag.conflicts[0].winner is None
+    assert "agent-specific" in diag.conflicts[0].reason
+
+
+def test_no_conflict_when_clean(tmp_path):
+    roots = pointed_roots(tmp_path)
+    make_skill(tmp_path / "proj" / ".claude" / "skills", "alpha")
+    make_skill(tmp_path / "user" / ".claude" / "skills", "beta")
+    diag = scan(roots_for=roots, base_dir=tmp_path)
+    assert not diag.conflicts and not diag.broken
+    assert len(diag.skills) == 2
+
+
+def test_broken_skill_problems(tmp_path):
+    d = tmp_path / "broken"
+    d.mkdir()
+    (d / "SKILL.md").write_text("no frontmatter here\n", encoding="utf-8")
+    meta = parse_skill(d, "claude-code", "project")
+    assert not meta.ok and any("frontmatter" in p for p in meta.problems)
+
+    d2 = tmp_path / "wrong-name"
+    d2.mkdir()
+    (d2 / "SKILL.md").write_text(
+        "---\nname: different-name\ndescription: x\n---\n", encoding="utf-8")
+    meta2 = parse_skill(d2, "claude-code", "project")
+    assert any("!=" in p for p in meta2.problems)
+
+    d3 = tmp_path / "kebab"
+    d3.mkdir()
+    (d3 / "SKILL.md").write_text("---\nname: BadName\ndescription: x\n---\n", encoding="utf-8")
+    meta3 = parse_skill(d3, "claude-code", "project")
+    assert any("kebab" in p for p in meta3.problems)
+
+
+def test_missing_skillmd_is_broken(tmp_path):
+    d = tmp_path / "empty"
+    d.mkdir()
+    meta = parse_skill(d, "claude-code", "user")
+    assert meta.problems == ["missing SKILL.md"]
+
+
+@pytest.mark.parametrize("long_desc", [False, True])
+def test_description_length_rule(tmp_path, long_desc):
+    d = tmp_path / ("long" if long_desc else "short")
+    d.mkdir()
+    desc = "x" * 1200 if long_desc else "short description"
+    (d / "SKILL.md").write_text(
+        f"---\nname: {d.name}\ndescription: {desc}\n---\n", encoding="utf-8")
+    meta = parse_skill(d, "claude-code", "project")
+    assert (any("1024" in p for p in meta.problems)) == long_desc
+
+
+def test_same_real_dir_scanned_once(tmp_path):
+    # two layouts pointing at the same resolved directory must not double-count
+    target = str(tmp_path / "shared")
+    roots = {"a": {"project": [target]}, "b": {"project": [target]}}
+    make_skill(tmp_path / "shared", "solo")
+    diag = scan(roots_for=roots, base_dir=tmp_path)
+    assert len(diag.skills) == 1 and not diag.conflicts
+
+
+def test_cli_scan_exit_codes(tmp_path, monkeypatch, capsys):
+    import skilldoctor.scan as scanmod
+
+    roots = pointed_roots(tmp_path)
+    make_skill(tmp_path / "proj" / ".claude" / "skills", "s")
+    make_skill(tmp_path / "user" / ".claude" / "skills", "s")
+    monkeypatch.setattr(scanmod, "KNOWN_DIRS", roots)
+    assert main(["scan", "--directory", str(tmp_path), "--json"]) == 1
+    out = json.loads(capsys.readouterr().out)
+    assert out["skills_total"] == 2 and out["conflicts"]
+
+    # a clean world: no skills anywhere -> exit 0
+    empty_roots = {"claude-code": {"project": [str(tmp_path / "nothing" / "here")]}}
+    monkeypatch.setattr(scanmod, "KNOWN_DIRS", empty_roots)
+    assert main(["scan", "--directory", str(tmp_path), "--json"]) == 0
+    assert json.loads(capsys.readouterr().out)["skills_total"] == 0
+
+
+def test_cli_check(tmp_path, capsys):
+    ok = make_skill(tmp_path, "good-skill")
+    assert main(["check", str(ok)]) == 0
+    assert "OK" in capsys.readouterr().out
+    assert main(["check", str(ok), "--json"]) == 0
+
+    bad = tmp_path / "odd_name"
+    bad.mkdir()
+    (bad / "SKILL.md").write_text("---\nname: mismatch\n---\n", encoding="utf-8")
+    assert main(["check", str(bad)]) == 1
+    out = capsys.readouterr().out
+    assert "mismatch" in out and "description" in out
+    assert main(["check", str(tmp_path / "missing-dir")]) == 2