Lovstudio Skill Optimizer

#!/usr/bin/env python3
"""
Bump a lovstudio skill's version and append a CHANGELOG entry.

Source of truth: README.md version badge. SKILL.md frontmatter metadata.version
is kept in sync when present.

Usage:
    python bump_version.py <skill-name> --type patch --message "fix frontmatter trigger phrases"
    python bump_version.py <skill-name> --type minor --message "add --verbose flag" --change "add -v shortcut"
    python bump_version.py <skill-name> --set 0.2.0 --message "..."
    python bump_version.py <skill-name> --type patch --message "..." --dry-run

Notes:
- --type: patch | minor | major (mutually exclusive with --set)
- --message: single-line summary used as the changelog bullet
- --change: may be repeated for additional bullet lines
- Creates CHANGELOG.md if missing (Keep a Changelog format).
"""

from __future__ import annotations

import argparse
import re
import sys
from datetime import date
from pathlib import Path

BADGE_COLOR = "CC785C"  # Lovstudio terracotta
BADGE_RE = re.compile(
    r"!\[Version\]\(https://img\.shields\.io/badge/version-(\d+\.\d+\.\d+)-[A-Za-z0-9]+\)"
)
FM_VERSION_RE = re.compile(r'(\n\s*version:\s*")(\d+\.\d+\.\d+)(")')


def find_repo_root(start: Path) -> Path:
    for p in [start] + list(start.parents):
        if (p / "CLAUDE.md").exists() and (p / "skills").is_dir():
            return p
    return start


def resolve_skill_dir(name: str, path: str | None) -> Path:
    if path:
        return Path(path).resolve()
    name = name.removeprefix("lovstudio-")
    root = find_repo_root(Path.cwd())
    return (root / "skills" / f"lovstudio-{name}").resolve()


def read_current_version(skill_dir: Path) -> str:
    readme = skill_dir / "README.md"
    if readme.exists():
        m = BADGE_RE.search(readme.read_text(encoding="utf-8"))
        if m:
            return m.group(1)
    skill_md = skill_dir / "SKILL.md"
    if skill_md.exists():
        m = FM_VERSION_RE.search(skill_md.read_text(encoding="utf-8"))
        if m:
            return m.group(2)
    return "0.0.0"


def bump(version: str, kind: str) -> str:
    major, minor, patch = (int(x) for x in version.split("."))
    if kind == "major":
        return f"{major + 1}.0.0"
    if kind == "minor":
        return f"{major}.{minor + 1}.0"
    if kind == "patch":
        return f"{major}.{minor}.{patch + 1}"
    raise ValueError(f"unknown bump type: {kind}")


def badge_line(version: str) -> str:
    return f"![Version](https://img.shields.io/badge/version-{version}-{BADGE_COLOR})"


def update_readme(skill_dir: Path, new_version: str, dry: bool) -> bool:
    readme = skill_dir / "README.md"
    if not readme.exists():
        return False
    text = readme.read_text(encoding="utf-8")
    new_badge = badge_line(new_version)
    if BADGE_RE.search(text):
        new_text = BADGE_RE.sub(new_badge, text, count=1)
    else:
        # Insert badge right after the H1 title
        lines = text.splitlines()
        inserted = False
        out = []
        for i, line in enumerate(lines):
            out.append(line)
            if not inserted and line.startswith("# "):
                out.append("")
                out.append(new_badge)
                inserted = True
        new_text = "\n".join(out)
        if not text.endswith("\n"):
            new_text += "\n"
    if new_text != text:
        if not dry:
            readme.write_text(new_text, encoding="utf-8")
        return True
    return False


def update_skill_md_version(skill_dir: Path, new_version: str, dry: bool) -> bool:
    skill_md = skill_dir / "SKILL.md"
    if not skill_md.exists():
        return False
    text = skill_md.read_text(encoding="utf-8")
    if not FM_VERSION_RE.search(text):
        return False
    new_text = FM_VERSION_RE.sub(rf'\g<1>{new_version}\g<3>', text, count=1)
    if new_text != text and not dry:
        skill_md.write_text(new_text, encoding="utf-8")
    return new_text != text


CHANGELOG_HEADER = """# Changelog

All notable changes to this skill are documented here.
Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · Versioning: [SemVer](https://semver.org/)

"""


def update_changelog(
    skill_dir: Path,
    new_version: str,
    message: str,
    changes: list[str],
    kind: str,
    dry: bool,
) -> None:
    path = skill_dir / "CHANGELOG.md"
    today = date.today().isoformat()
    section_title = {"major": "Changed", "minor": "Added", "patch": "Fixed"}.get(kind, "Changed")

    entry_lines = [f"## [{new_version}] - {today}", "", f"### {section_title}", "", f"- {message}"]
    for c in changes:
        entry_lines.append(f"- {c}")
    entry_lines.append("")
    entry = "\n".join(entry_lines) + "\n"

    if path.exists():
        existing = path.read_text(encoding="utf-8")
        if existing.startswith("# Changelog"):
            # insert after header paragraph
            head_end = existing.find("\n## ")
            if head_end == -1:
                # no prior entries
                body = existing.rstrip() + "\n\n" + entry
            else:
                body = existing[:head_end].rstrip() + "\n\n" + entry + existing[head_end + 1 :]
        else:
            body = CHANGELOG_HEADER + entry + existing
    else:
        body = CHANGELOG_HEADER + entry

    if not dry:
        path.write_text(body, encoding="utf-8")


def main():
    ap = argparse.ArgumentParser(description="Bump version and update changelog for a lovstudio skill")
    ap.add_argument("name", nargs="?", help="Skill name (with or without lovstudio- prefix)")
    ap.add_argument("--path", help="Absolute path to skill directory (overrides name)")
    group = ap.add_mutually_exclusive_group(required=True)
    group.add_argument("--type", choices=["patch", "minor", "major"], help="Semver bump kind")
    group.add_argument("--set", dest="set_version", help="Set an explicit version (e.g. 0.2.0)")
    ap.add_argument("--message", "-m", required=True, help="Primary changelog entry")
    ap.add_argument("--change", "-c", action="append", default=[], help="Additional changelog bullets")
    ap.add_argument("--dry-run", action="store_true", help="Show what would change without writing")
    args = ap.parse_args()

    if not args.name and not args.path:
        ap.error("provide a skill name or --path")

    skill_dir = resolve_skill_dir(args.name or "", args.path)
    if not skill_dir.exists():
        print(f"ERROR: skill directory not found: {skill_dir}", file=sys.stderr)
        sys.exit(1)

    current = read_current_version(skill_dir)
    if args.set_version:
        if not re.match(r"^\d+\.\d+\.\d+$", args.set_version):
            print(f"ERROR: --set value must be semver x.y.z (got {args.set_version})", file=sys.stderr)
            sys.exit(1)
        new_version = args.set_version
        kind = "minor"  # default section label for manual sets
    else:
        new_version = bump(current, args.type)
        kind = args.type

    print(f"skill:    {skill_dir.name}")
    print(f"current:  {current}")
    print(f"new:      {new_version}")
    print(f"message:  {args.message}")
    if args.dry_run:
        print("(dry run — no files written)")

    update_readme(skill_dir, new_version, args.dry_run)
    update_skill_md_version(skill_dir, new_version, args.dry_run)
    update_changelog(skill_dir, new_version, args.message, args.change, kind, args.dry_run)

    print("done.")


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Audit a lovstudio skill against repo conventions + official skill-creator best practices.

Usage:
    python lint_skill.py <skill-name>           # e.g. any2pdf or lovstudio-any2pdf
    python lint_skill.py <skill-name> --json
    python lint_skill.py --path /abs/path/to/skills/lovstudio-any2pdf

Outputs a list of findings with severity (error/warn/info) and a `fix_hint` field
to help the orchestrating skill prioritize automatic fixes.
"""

from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path

SEVERITIES = ("error", "warn", "info")

FRONTMATTER_REQUIRED = ["name", "description", "license", "compatibility", "metadata"]
METADATA_REQUIRED = ["author", "version", "tags"]
STANDARD_NAME_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
USER_CONFIG_CUES = (
    "## User Configuration",
    "## 用户配置",
    "user-config.md",
    "LOVSTUDIO_SKILLS_PROFILE",
    "LOVSTUDIO_SKILLS_HOME",
    "LOVSTUDIO_SKILLS_WORKSPACE_ROOT",
    "LOVSTUDIO_SKILLS_OUTPUT_DIR",
    "LOVSTUDIO_SKILLS_BRAND_PROFILE",
    "LOVSTUDIO_SKILLS_DESIGN_GUIDE",
    "LOVSTUDIO_MAINTAIN_PARTNERS_SITE_ROOT",
    "LOVSTUDIO_MAINTAIN_PARTNERS_FILE",
    # Legacy cues accepted during migration.
    "AGENT_SKILL_PROFILE",
    "LOVSTUDIO_SKILL_PROFILE",
    "PARTNERS_SITE_ROOT",
    "PARTNERS_FILE",
)
LOCAL_PATH_PATTERNS = (
    ("LOCAL_MARK_PATH", re.compile(r"/Users/mark(?:/|\b)"), "/Users/mark"),
    ("LOCAL_LOVSTUDIO_PATH", re.compile(r"(?<![A-Za-z0-9_])~/?lovstudio(?:/|\b)|\$HOME/lovstudio(?:/|\b)"), "~/lovstudio"),
    ("LOCAL_CLAUDE_PATH", re.compile(r"~/\.claude|/\.claude/skills|\$HOME/\.claude"), "~/.claude"),
    ("LOCAL_AGENTS_PATH", re.compile(r"~/\.agents|/\.agents/skills|\$HOME/\.agents"), "~/.agents"),
    ("CLIENT_PLUGIN_ENV", re.compile(r"CLAUDE_PLUGIN_ROOT"), "CLAUDE_PLUGIN_ROOT"),
)
NEGATIVE_LOCAL_PATH_CONTEXT_RE = re.compile(
    r"must not assume|do not hard-?code|not require|should not require|avoid hard-?coded|"
    r"without assuming|move user-specific paths",
    re.I,
)


def has_required_local_path(text: str, pattern: re.Pattern) -> bool:
    for line in text.splitlines():
        if not pattern.search(line):
            continue
        if NEGATIVE_LOCAL_PATH_CONTEXT_RE.search(line):
            continue
        return True
    return False


def looks_like_skills_root(path: Path) -> bool:
    if not path.exists() or not path.is_dir():
        return False
    try:
        for child in path.iterdir():
            if child.is_dir() and (child / "SKILL.md").exists():
                return True
            if child.is_dir() and child.name.endswith("-skill") and (child / "SKILL.md").exists():
                return True
    except OSError:
        return False
    return False


def find_repo_root(start: Path) -> Path:
    for p in [start] + list(start.parents):
        if looks_like_skills_root(p):
            return p
        if (p / "skills.yaml").exists() and (p / "skills").is_dir():
            return p
        if (p / "CLAUDE.md").exists() and (p / "skills").is_dir():
            return p
    return start


def resolve_skill_dir(name: str, path: str | None) -> Path:
    if path:
        return Path(path).resolve()
    raw = name
    name = name.removeprefix("lovstudio-")
    if name.endswith("-skill"):
        name = name[: -len("-skill")]
    root = find_repo_root(Path.cwd())
    candidates = [
        root / f"{name}-skill",
        root / f"lovstudio-{name}",
        root / name,
        root / "skills" / f"lovstudio-{name}",
        root / "skills" / name,
        root / "skills" / f"{name}-skill",
        root / raw,
    ]
    for c in candidates:
        if (c / "SKILL.md").exists():
            return c.resolve()
    return candidates[0].resolve()


def discover_skill_dirs(root: Path) -> list[Path]:
    dirs = []
    for skill_md in root.rglob("SKILL.md"):
        parts = set(skill_md.parts)
        if ".git" in parts or "node_modules" in parts:
            continue
        dirs.append(skill_md.parent)
    return sorted(set(dirs))


def parse_frontmatter(text: str) -> tuple[dict, str]:
    """Naive YAML frontmatter parser — enough for lint purposes."""
    if not text.startswith("---"):
        return {}, text
    end = text.find("\n---", 3)
    if end == -1:
        return {}, text
    fm_block = text[3:end].strip("\n")
    body = text[end + 4 :].lstrip("\n")
    data: dict = {}
    current_key = None
    buf: list[str] = []
    for line in fm_block.splitlines():
        if not line.strip():
            continue
        m = re.match(r"^([A-Za-z_][A-Za-z0-9_]*):\s*(.*)$", line)
        if m and not line.startswith((" ", "\t")):
            if current_key is not None:
                data[current_key] = "\n".join(buf).strip() if buf else data.get(current_key, "")
            current_key = m.group(1)
            val = m.group(2).strip()
            buf = []
            if val in (">", "|", ">-", "|-"):
                data[current_key] = ""
            elif val == "":
                data[current_key] = {}  # likely nested
            else:
                data[current_key] = val.strip('"').strip("'")
                current_key = None
        elif current_key and line.startswith((" ", "\t")):
            stripped = line.strip()
            # nested key under metadata
            m2 = re.match(r"^([A-Za-z_][A-Za-z0-9_]*):\s*(.*)$", stripped)
            if m2 and isinstance(data.get(current_key), dict):
                data[current_key][m2.group(1)] = m2.group(2).strip().strip('"').strip("'")
            else:
                buf.append(stripped)
    if current_key is not None and buf:
        if isinstance(data.get(current_key), str) and data[current_key] == "":
            data[current_key] = "\n".join(buf).strip()
    return data, body


class Linter:
    def __init__(self, skill_dir: Path):
        self.dir = skill_dir
        dir_name = skill_dir.name
        short = dir_name
        if short.endswith("-skill"):
            short = short[: -len("-skill")]
        short = short.removeprefix("lovstudio-")
        self.name = short
        self.expected_standard_name = f"lovstudio-{short}"
        self.findings: list[dict] = []

    def add(self, severity: str, code: str, message: str, fix_hint: str = "", file: str = ""):
        self.findings.append(
            {
                "severity": severity,
                "code": code,
                "message": message,
                "fix_hint": fix_hint,
                "file": file,
            }
        )

    # --- Checks ---

    def check_structure(self):
        if not self.dir.exists():
            self.add("error", "DIR_MISSING", f"Skill directory not found: {self.dir}")
            return
        source_dir_ok = self.dir.name == self.name or self.dir.name == f"{self.name}-skill" or self.dir.name == self.expected_standard_name
        if not source_dir_ok or not STANDARD_NAME_RE.match(self.dir.name.removesuffix("-skill")):
            self.add(
                "warn",
                "DIR_NONSTANDARD",
                f"Directory '{self.dir.name}' is not in a recognized source/install format",
                "Use <name>-skill for source repos or lovstudio-<name> for installed/distributed dirs",
            )
        for required in ("SKILL.md", "README.md"):
            f = self.dir / required
            if not f.exists():
                self.add(
                    "error",
                    f"MISSING_{required.split('.')[0]}",
                    f"{required} is missing",
                    f"Create {required} using the templates in skill-creator references",
                    file=required,
                )

    def check_skill_md(self):
        path = self.dir / "SKILL.md"
        if not path.exists():
            return
        text = path.read_text(encoding="utf-8")
        fm, body = parse_frontmatter(text)

        for key in FRONTMATTER_REQUIRED:
            if key not in fm:
                self.add(
                    "error",
                    "FM_MISSING_FIELD",
                    f"SKILL.md frontmatter missing required field '{key}'",
                    f"Add '{key}:' to frontmatter",
                    file="SKILL.md",
                )

        name = fm.get("name", "")
        if name and not STANDARD_NAME_RE.match(name):
            self.add(
                "error",
                "FM_NAME_INVALID",
                f"frontmatter name '{name}' is not Agent Skills-compatible",
                f"Use name: {self.expected_standard_name}",
                file="SKILL.md",
            )
        elif name and name != self.expected_standard_name:
            self.add(
                "warn",
                "FM_NAME_MISMATCH",
                f"frontmatter name '{name}' does not match standard expected name '{self.expected_standard_name}'",
                f"Set name: {self.expected_standard_name} or document why this is author-only",
                file="SKILL.md",
            )

        desc = fm.get("description", "") or ""
        if isinstance(desc, str):
            if len(desc) < 80:
                self.add(
                    "warn",
                    "FM_DESC_TOO_SHORT",
                    "description is shorter than 80 chars — likely missing trigger info",
                    "Expand description to cover: what it does + when to trigger + specific user phrases",
                    file="SKILL.md",
                )
            if "trigger" not in desc.lower() and "mention" not in desc.lower() and "use when" not in desc.lower():
                self.add(
                    "warn",
                    "FM_DESC_NO_TRIGGER",
                    "description lacks explicit trigger cues (e.g. 'Use when...', 'trigger when user mentions...')",
                    "Add 'Use when ...' and 'Also trigger when the user mentions \"...\"' phrases",
                    file="SKILL.md",
                )

        meta = fm.get("metadata")
        if isinstance(meta, dict):
            for k in METADATA_REQUIRED:
                if k not in meta:
                    self.add(
                        "warn",
                        "FM_META_FIELD",
                        f"metadata.{k} missing",
                        f"Add metadata.{k}",
                        file="SKILL.md",
                    )
            version = meta.get("version", "")
            if version and not re.match(r"^\d+\.\d+\.\d+$", version):
                self.add(
                    "warn",
                    "FM_VERSION_FORMAT",
                    f"metadata.version '{version}' is not semver x.y.z",
                    "Use semver format like 0.1.0",
                    file="SKILL.md",
                )

        # Body checks
        if re.search(r"TODO:\s", body) or "TODO_CN" in body or "TODO_EN" in body:
            self.add(
                "error",
                "BODY_TODO",
                "SKILL.md body still contains TODO placeholders",
                "Replace all TODOs with real content",
                file="SKILL.md",
            )
        non_interactive = any(
            phrase in body.lower()
            for phrase in ("fully automatic", "no interactive", "non-interactive", "do not ask the user")
        )
        if (
            "AskUserQuestion" not in body
            and "## Workflow" in body
            and not non_interactive
        ):
            self.add(
                "info",
                "BODY_NO_ASKUSER",
                "Workflow does not mention AskUserQuestion — interactive skills should collect options before running",
                "Add an 'Ask the user' step using AskUserQuestion",
                file="SKILL.md",
            )
        if len(body.splitlines()) > 500:
            self.add(
                "warn",
                "BODY_TOO_LONG",
                "SKILL.md body exceeds 500 lines — consider progressive disclosure",
                "Split long sections to references/ and link from SKILL.md",
                file="SKILL.md",
            )

    def check_portability(self):
        files = []
        for rel in ("SKILL.md", "README.md"):
            path = self.dir / rel
            if path.exists():
                files.append((rel, path))
        scripts_dir = self.dir / "scripts"
        if scripts_dir.exists():
            for path in scripts_dir.glob("*.py"):
                files.append((f"scripts/{path.name}", path))

        combined = "\n".join(
            path.read_text(encoding="utf-8", errors="replace")
            for _, path in files
        )
        has_user_config = any(cue in combined for cue in USER_CONFIG_CUES)
        skill_md = self.dir / "SKILL.md"
        compatibility = ""
        if skill_md.exists():
            fm, _ = parse_frontmatter(skill_md.read_text(encoding="utf-8", errors="replace"))
            compatibility = str(fm.get("compatibility", ""))
        author_only = bool(
            re.search(
                r"author-only|internal only|LovStudio internal|Mark/LovStudio private",
                compatibility,
                re.I,
            )
        )

        for rel, path in files:
            text = path.read_text(encoding="utf-8", errors="replace")
            if "LOCAL_PATH_PATTERNS" in text and "def check_portability" in text:
                continue
            for code, pattern, label in LOCAL_PATH_PATTERNS:
                if not has_required_local_path(text, pattern):
                    continue
                if code == "LOCAL_CLAUDE_PATH" and rel == "README.md" and "git clone" in text:
                    severity = "info"
                    hint = "Install examples may mention ~/.claude, but runtime examples should use SKILL_DIR or CLAUDE_SKILLS_DIR"
                elif author_only:
                    severity = "info"
                    hint = "Author-only skill: keep local paths centralized in one configuration section"
                elif has_user_config:
                    severity = "info"
                    hint = "User config exists; verify this path is only a fallback/example and not required"
                else:
                    severity = "warn"
                    hint = (
                        "Move user-specific paths to CLI flags, env vars, or "
                        "references/user-config.md; do not require this local path"
                    )
                self.add(
                    severity,
                    code,
                    f"{rel} references local/client-specific path '{label}'",
                    hint,
                    file=rel,
                )

    def check_readme(self):
        path = self.dir / "README.md"
        if not path.exists():
            return
        text = path.read_text(encoding="utf-8")
        if re.search(r"TODO:\s", text) or "pip install TODO" in text or "--output TODO" in text:
            self.add(
                "error",
                "README_TODO",
                "README.md contains TODO placeholders",
                "Fill in install, usage, options",
                file="README.md",
            )
        if not re.search(r"!\[Version\]\(https://img\.shields\.io/badge/version-", text):
            self.add(
                "warn",
                "README_NO_BADGE",
                "README.md missing version badge",
                "Add ![Version](https://img.shields.io/badge/version-X.Y.Z-CC785C) near the top",
                file="README.md",
            )
        has_install = any(
            token in text
            for token in (
                "npx lovstudio skills add",
                "npx skills add",
                "git clone https://github.com/lovstudio",
                "/plugin install",
            )
        )
        if not has_install:
            self.add(
                "warn",
                "README_NO_INSTALL",
                "README.md missing install command",
                "Add an install block using npx skills add or git clone into ${CLAUDE_SKILLS_DIR:-$HOME/.claude/skills}/lovstudio-<name>",
                file="README.md",
            )

    def check_changelog(self):
        path = self.dir / "CHANGELOG.md"
        if not path.exists():
            self.add(
                "warn",
                "NO_CHANGELOG",
                "CHANGELOG.md not found",
                "Run bump_version.py to create an initial entry",
                file="CHANGELOG.md",
            )

    def check_scripts(self):
        scripts_dir = self.dir / "scripts"
        if not scripts_dir.exists():
            return  # pure-instruction skills allowed
        for py in scripts_dir.glob("*.py"):
            text = py.read_text(encoding="utf-8", errors="replace")
            rel = f"scripts/{py.name}"
            if "argparse" not in text and "if __name__" in text:
                self.add(
                    "warn",
                    "SCRIPT_NO_ARGPARSE",
                    f"{py.name} is a CLI but does not use argparse",
                    "Rewrite to use argparse for CLI parity with other skills",
                    file=rel,
                )
            if (
                re.search(r"pip install .*--break-system-packages", text)
                and re.search(r"(subprocess\.(run|call|Popen)|os\.system)", text)
            ):
                self.add(
                    "info",
                    "SCRIPT_PIP_FLAG",
                    f"{py.name} shells out pip install --break-system-packages (should be in docs, not code)",
                    "Move pip install guidance to SKILL.md/README.md",
                    file=rel,
                )
            if py.stat().st_size > 80_000:
                self.add(
                    "info",
                    "SCRIPT_LARGE",
                    f"{py.name} is large (>80KB) — verify it's still a single-file CLI",
                    "",
                    file=rel,
                )
            # CJK-relevant text-rendering scripts should handle mixed text.
            # Image-only helpers inside document skills (logo/QR compositing,
            # PDF raster stitching, etc.) do not need font fallback logic.
            renders_text = any(
                marker in text.lower()
                for marker in (
                    "add_run(",
                    "add_paragraph(",
                    "draw.text",
                    "imagefont",
                    "reportlab",
                    "fpdf",
                    "python-pptx",
                    "pptx",
                    "docx",
                )
            )
            if renders_text and ("pdf" in self.name or "docx" in self.name or "deck" in self.name):
                if "cjk" not in text.lower() and "chinese" not in text.lower() and "中文" not in text:
                    self.add(
                        "info",
                        "SCRIPT_NO_CJK_HINT",
                        f"{py.name}: document-skill script has no visible CJK handling code",
                        "Verify CJK/Latin mixed rendering works correctly",
                        file=rel,
                    )

    def run(self) -> list[dict]:
        self.check_structure()
        self.check_skill_md()
        self.check_readme()
        self.check_changelog()
        self.check_scripts()
        self.check_portability()
        return self.findings


def format_text(findings: list[dict], skill_dir: Path) -> str:
    if not findings:
        return f"✓ {skill_dir.name}: no issues found\n"
    lines = [f"Lint report for {skill_dir.name}:", ""]
    by_sev = {s: [f for f in findings if f["severity"] == s] for s in SEVERITIES}
    marks = {"error": "✗", "warn": "!", "info": "·"}
    for sev in SEVERITIES:
        for f in by_sev[sev]:
            loc = f" [{f['file']}]" if f["file"] else ""
            lines.append(f"  {marks[sev]} {sev.upper():5} {f['code']:20}{loc}  {f['message']}")
            if f["fix_hint"]:
                lines.append(f"      → {f['fix_hint']}")
    lines.append("")
    lines.append(
        f"Summary: {len(by_sev['error'])} errors, {len(by_sev['warn'])} warnings, {len(by_sev['info'])} info"
    )
    return "\n".join(lines) + "\n"


def main():
    ap = argparse.ArgumentParser(description="Audit a lovstudio skill")
    ap.add_argument("name", nargs="?", help="Skill name (with or without lovstudio- prefix)")
    ap.add_argument("--path", help="Absolute path to skill directory (overrides name)")
    ap.add_argument("--all", action="store_true", help="Audit every SKILL.md below the detected root")
    ap.add_argument("--root", help="Root directory for --all (defaults to detected skills root)")
    ap.add_argument("--json", action="store_true", help="Output findings as JSON")
    args = ap.parse_args()

    if args.all:
        root = Path(args.root).resolve() if args.root else find_repo_root(Path.cwd())
        reports = []
        for skill_dir in discover_skill_dirs(root):
            linter = Linter(skill_dir)
            reports.append({"skill": skill_dir.name, "path": str(skill_dir), "findings": linter.run()})
        if args.json:
            print(json.dumps({"root": str(root), "reports": reports}, ensure_ascii=False, indent=2))
        else:
            total = {"error": 0, "warn": 0, "info": 0}
            for report in reports:
                counts = {sev: len([f for f in report["findings"] if f["severity"] == sev]) for sev in SEVERITIES}
                for sev in SEVERITIES:
                    total[sev] += counts[sev]
                print(
                    f"{report['skill']}: "
                    f"{counts['error']} errors, {counts['warn']} warnings, {counts['info']} info"
                )
            print(
                f"\nSummary: {len(reports)} skills, "
                f"{total['error']} errors, {total['warn']} warnings, {total['info']} info"
            )
        if any(f["severity"] == "error" for r in reports for f in r["findings"]):
            sys.exit(2)
        return

    if not args.name and not args.path:
        ap.error("provide a skill name or --path")

    skill_dir = resolve_skill_dir(args.name or "", args.path)
    linter = Linter(skill_dir)
    findings = linter.run()

    if args.json:
        print(
            json.dumps(
                {"skill": skill_dir.name, "path": str(skill_dir), "findings": findings},
                ensure_ascii=False,
                indent=2,
            )
        )
    else:
        sys.stdout.write(format_text(findings, skill_dir))

    # Exit non-zero if errors present
    if any(f["severity"] == "error" for f in findings):
        sys.exit(2)


if __name__ == "__main__":
    main()