@event4u/agent-config 1.9.1

package/scripts/audit_skill_descriptions.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""
+Audit skill descriptions for triggering quality.
+
+Flags descriptions that are:
+  - too short (< 150 chars) or too long (> 200 chars, the linter limit)
+  - missing an explicit trigger verb prefix ("use when", "use if", "creates", ...)
+  - containing hedge terms ("may help", "can be useful", "covers various", ...)
+
+Context:
+  `archive/road-to-anthropic-alignment.md` Phase 2.2 — "pushy description" pattern from
+  anthropics/skills/skills/skill-creator (roadmap archived 2026-04-21).
+
+Usage:
+  python3 scripts/audit_skill_descriptions.py               # human table
+  python3 scripts/audit_skill_descriptions.py --json        # machine-readable
+  python3 scripts/audit_skill_descriptions.py --root DIR    # audit another tree
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import List
+
+DEFAULT_ROOT = Path(".agent-src.uncompressed/skills")
+MIN_LENGTH = 150
+# Mirrors scripts/skill_linter.py `description_too_long` threshold.
+MAX_LENGTH = 200
+
+FRONTMATTER_RE = re.compile(r"^---\n(.*?)\n---", re.DOTALL)
+DESCRIPTION_RE = re.compile(r'^description:\s*"?(.*?)"?\s*$', re.MULTILINE)
+
+TRIGGER_PREFIX_RE = re.compile(
+    r"^\s*("
+    r"use\s+(when|if|for)\b|only\s+when\b|"
+    r"creates?\b|reviews?\b|writes?\b|handles?\b|generates?\b|runs?\b|"
+    r"builds?\b|fetches?\b|validates?\b|audits?\b|analyzes?\b|detects?\b|"
+    r"plans?\b|deploys?\b|configures?\b|scaffolds?\b|fixes?\b|refactors?\b|"
+    r"optimizes?\b|renders?\b|syncs?\b|explores?\b|installs?\b|updates?\b|"
+    r"manages?\b|orchestrates?\b|prepares?\b|finds?\b|executes?\b|reads?\b|"
+    r"checks?\b|tracks?\b"
+    r")",
+    re.IGNORECASE,
+)
+
+HEDGE_PHRASES = (
+    "may help",
+    "can be useful",
+    "covers various",
+    "might be",
+    "generally",
+    "as needed",
+    "when appropriate",
+)
+
+
+@dataclass
+class Finding:
+    skill: str
+    path: str
+    description: str
+    length: int
+    flags: List[str] = field(default_factory=list)
+
+    @property
+    def score(self) -> int:
+        # Higher score = worse. Used for sorting.
+        penalty = 0
+        if "no-trigger-prefix" in self.flags:
+            penalty += 30
+        if "too-short" in self.flags:
+            penalty += 20
+        if "very-short" in self.flags:
+            penalty += 10
+        penalty += sum(10 for f in self.flags if f.startswith("hedge:"))
+        return penalty
+
+
+def extract_description(text: str) -> str:
+    m = FRONTMATTER_RE.search(text)
+    if not m:
+        return ""
+    d = DESCRIPTION_RE.search(m.group(1))
+    return d.group(1).strip() if d else ""
+
+
+def audit_description(description: str) -> List[str]:
+    flags: List[str] = []
+    if not description:
+        flags.append("missing")
+        return flags
+    length = len(description)
+    if length < 80:
+        flags.append("very-short")
+    elif length < MIN_LENGTH:
+        flags.append("too-short")
+    if length > MAX_LENGTH:
+        flags.append("too-long")
+    if not TRIGGER_PREFIX_RE.match(description):
+        flags.append("no-trigger-prefix")
+    lowered = description.lower()
+    for phrase in HEDGE_PHRASES:
+        if phrase in lowered:
+            flags.append(f"hedge:{phrase}")
+    return flags
+
+
+def collect_findings(root: Path) -> List[Finding]:
+    findings: List[Finding] = []
+    for skill_md in sorted(root.glob("*/SKILL.md")):
+        text = skill_md.read_text(encoding="utf-8")
+        description = extract_description(text)
+        flags = audit_description(description)
+        findings.append(
+            Finding(
+                skill=skill_md.parent.name,
+                path=str(skill_md),
+                description=description,
+                length=len(description),
+                flags=flags,
+            )
+        )
+    return findings
+
+
+def render_text(findings: List[Finding], worst_only: bool) -> str:
+    flagged = [f for f in findings if f.flags]
+    flagged.sort(key=lambda f: (-f.score, f.skill))
+    lines = [f"Audited {len(findings)} skills, {len(flagged)} flagged.\n"]
+    if not flagged:
+        lines.append("✅  All descriptions look reasonable.")
+        return "\n".join(lines)
+    lines.append(f"{'SCORE':>5}  {'LEN':>4}  {'SKILL':<40}  FLAGS")
+    lines.append("-" * 90)
+    shown = flagged[:15] if worst_only else flagged
+    for f in shown:
+        lines.append(
+            f"{f.score:>5}  {f.length:>4}  {f.skill:<40}  {', '.join(f.flags)}"
+        )
+    if worst_only and len(flagged) > 15:
+        lines.append(f"\n... {len(flagged) - 15} more (use --full to show all)")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--root", type=Path, default=DEFAULT_ROOT)
+    parser.add_argument("--json", action="store_true", help="emit JSON")
+    parser.add_argument("--full", action="store_true", help="show all flagged, not just top 15")
+    args = parser.parse_args()
+    if not args.root.exists():
+        print(f"error: {args.root} does not exist", file=sys.stderr)
+        return 2
+    findings = collect_findings(args.root)
+    if args.json:
+        print(json.dumps([asdict(f) for f in findings], indent=2))
+    else:
+        print(render_text(findings, worst_only=not args.full))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/check_compression.py

@@ -0,0 +1,221 @@
+#!/usr/bin/env python3
+"""
+Compression quality checker for agent-config packages.
+
+Compares .agent-src.uncompressed/ source files with their .agent-src/ compressed versions.
+Checks that compression preserved structural integrity:
+- All headings from source present in compressed
+- All code blocks preserved exactly
+- YAML frontmatter identical
+- Word count reduction within healthy range (10-60%)
+
+Exit codes: 0 = clean, 1 = issues found, 3 = internal error
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import dataclass, asdict
+from pathlib import Path
+from typing import List, Literal
+
+Severity = Literal["error", "warning", "info"]
+
+SOURCE_DIR = Path(".agent-src.uncompressed")
+TARGET_DIR = Path(".agent-src")
+
+
+@dataclass
+class Issue:
+    file: str
+    check: str
+    severity: Severity
+    message: str
+
+
+def extract_headings(text: str) -> list[str]:
+    """Extract all markdown headings (outside code blocks)."""
+    headings = []
+    in_code = False
+    for line in text.splitlines():
+        if line.strip().startswith("```"):
+            in_code = not in_code
+            continue
+        if not in_code and re.match(r"^#{1,6}\s+.+$", line):
+            headings.append(line)
+    return headings
+
+
+def extract_code_blocks(text: str) -> list[str]:
+    """Extract content of fenced code blocks."""
+    return re.findall(r"```[^\n]*\n(.*?)```", text, re.DOTALL)
+
+
+def extract_frontmatter(text: str) -> str:
+    """Extract YAML frontmatter."""
+    m = re.match(r"^---\n(.*?\n)---", text, re.DOTALL)
+    return m.group(1).strip() if m else ""
+
+
+def check_pair(rel_path: str, source: str, compressed: str) -> List[Issue]:
+    """Compare source and compressed versions of a file."""
+    issues: List[Issue] = []
+
+    # Frontmatter check
+    src_fm = extract_frontmatter(source)
+    cmp_fm = extract_frontmatter(compressed)
+    if src_fm and src_fm != cmp_fm:
+        issues.append(Issue(rel_path, "frontmatter_mismatch", "error",
+                            "YAML frontmatter differs between source and compressed"))
+
+    # Heading preservation — check H1 and H2 headings (H3+ may be merged during compression)
+    src_headings = extract_headings(source)
+    cmp_headings = extract_headings(compressed)
+    for h in src_headings:
+        # Only check H1 and H2 (## level) — H3+ subheadings may be merged
+        if h.startswith("# ") or (h.startswith("## ") and not h.startswith("### ")):
+            if h not in cmp_headings:
+                issues.append(Issue(rel_path, "missing_heading", "warning",
+                                    f"H1/H2 heading lost during compression: {h}"))
+    # Also flag if comment lines inside code blocks are being treated as headings
+    # Filter out false positives from code blocks
+
+    # Code block preservation
+    src_blocks = extract_code_blocks(source)
+    cmp_blocks = extract_code_blocks(compressed)
+    if len(src_blocks) > len(cmp_blocks):
+        issues.append(Issue(rel_path, "lost_code_blocks", "error",
+                            f"Code blocks lost: source has {len(src_blocks)}, compressed has {len(cmp_blocks)}"))
+    for i, block in enumerate(src_blocks):
+        if i < len(cmp_blocks) and block.strip() != cmp_blocks[i].strip():
+            # Only flag if content actually changed (not just whitespace)
+            if block.replace(" ", "").replace("\n", "") != cmp_blocks[i].replace(" ", "").replace("\n", ""):
+                issues.append(Issue(rel_path, "modified_code_block", "error",
+                                    f"Code block {i+1} content changed during compression"))
+
+    # Word count ratio
+    src_words = len(source.split())
+    cmp_words = len(compressed.split())
+    if src_words > 0:
+        reduction = (1 - cmp_words / src_words) * 100
+        if reduction > 60:
+            issues.append(Issue(rel_path, "excessive_reduction", "warning",
+                                f"Compression reduced {reduction:.0f}% — possible content loss "
+                                f"({src_words} → {cmp_words} words)"))
+        elif reduction < 5 and src_words > 100:
+            issues.append(Issue(rel_path, "minimal_reduction", "info",
+                                f"Compression only reduced {reduction:.0f}% "
+                                f"({src_words} → {cmp_words} words)"))
+
+    return issues
+
+
+def scan_all(root: Path) -> List[Issue]:
+    """Scan all .md file pairs for compression quality issues."""
+    issues: List[Issue] = []
+    source_dir = root / SOURCE_DIR
+    target_dir = root / TARGET_DIR
+
+    if not source_dir.exists() or not target_dir.exists():
+        return issues
+
+    for source_file in sorted(source_dir.rglob("*.md")):
+        rel = source_file.relative_to(source_dir)
+        target_file = target_dir / rel
+
+        if not target_file.exists():
+            continue  # sync-check handles missing files
+
+        # Skip commands — they are copied verbatim, not compressed
+        rel_str = str(rel)
+        if rel_str.startswith("commands/"):
+            continue
+
+        source_text = source_file.read_text(encoding="utf-8")
+        target_text = target_file.read_text(encoding="utf-8")
+        issues.extend(check_pair(rel_str, source_text, target_text))
+
+    return issues
+
+
+def format_text(issues: List[Issue]) -> str:
+    if not issues:
+        return "✅  Compression quality check passed."
+    icons = {"error": "🔴", "warning": "🟡", "info": "ℹ️"}
+    lines = [f"Found {len(issues)} compression quality issue(s):\n"]
+    for i in issues:
+        lines.append(f"  {icons[i.severity]} [{i.check}] {i.file}: {i.message}")
+    errors = sum(1 for i in issues if i.severity == "error")
+    if errors:
+        lines.append(f"\n❌  {errors} error(s) must be fixed.")
+    return "\n".join(lines)
+
+
+def scan_summary(root: Path) -> str:
+    """Generate per-category compression summary stats."""
+    source_dir = root / SOURCE_DIR
+    target_dir = root / TARGET_DIR
+    if not source_dir.exists() or not target_dir.exists():
+        return "No source/target directories found."
+
+    categories: dict[str, list[tuple[int, int]]] = {}
+    for source_file in sorted(source_dir.rglob("*.md")):
+        rel = source_file.relative_to(source_dir)
+        target_file = target_dir / rel
+        if not target_file.exists() or str(rel).startswith("commands/"):
+            continue
+        src_words = len(source_file.read_text(encoding="utf-8").split())
+        cmp_words = len(target_file.read_text(encoding="utf-8").split())
+        parts = str(rel).split("/")
+        cat = parts[0] if len(parts) > 1 else "root"
+        categories.setdefault(cat, []).append((src_words, cmp_words))
+
+    lines = ["Category         | Files | Avg Source | Avg Compressed | Avg Reduction",
+             "---              | ---   | ---        | ---            | ---"]
+    total_src = total_cmp = total_files = 0
+    for cat in sorted(categories):
+        pairs = categories[cat]
+        n = len(pairs)
+        avg_src = sum(s for s, _ in pairs) // n
+        avg_cmp = sum(c for _, c in pairs) // n
+        reduction = (1 - avg_cmp / avg_src) * 100 if avg_src > 0 else 0
+        lines.append(f"{cat:<17}| {n:>5} | {avg_src:>10} | {avg_cmp:>14} | {reduction:>5.0f}%")
+        total_src += sum(s for s, _ in pairs)
+        total_cmp += sum(c for _, c in pairs)
+        total_files += n
+    overall = (1 - total_cmp / total_src) * 100 if total_src > 0 else 0
+    lines.append(f"{'TOTAL':<17}| {total_files:>5} | {total_src // max(total_files, 1):>10} | {total_cmp // max(total_files, 1):>14} | {overall:>5.0f}%")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Check compression quality")
+    parser.add_argument("--format", choices=["text", "json"], default="text")
+    parser.add_argument("--summary", action="store_true", help="Show per-category compression stats")
+    parser.add_argument("--root", type=Path, default=Path("."))
+    args = parser.parse_args()
+
+    if args.summary:
+        print(scan_summary(args.root))
+        return 0
+
+    try:
+        issues = scan_all(args.root)
+    except Exception as e:
+        print(f"Internal error: {e}", file=sys.stderr)
+        return 3
+
+    if args.format == "json":
+        print(json.dumps([asdict(i) for i in issues], indent=2))
+    else:
+        print(format_text(issues))
+
+    errors = [i for i in issues if i.severity == "error"]
+    return 1 if errors else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())