skillguard-lint 0.1.0__py3-none-any.whl

skillguard/__init__.py

@@ -0,0 +1,23 @@
+"""SkillGuard: The Security Scanner, Linter, and Quality Gate for AI Agent Skills.
+
+Static analysis for SKILL.md files, catching safety risks, prompt injections,
+token bloat, routing collisions, and structural anti-patterns before runtime.
+"""
+
+__version__ = "0.1.0"
+__author__ = "Eslam Elzamkan"
+__license__ = "Apache-2.0"
+
+from .rules import Diagnostic, Rule, Severity
+from .scanner import SkillScanner
+from .library import LibraryAuditor
+
+__all__ = [
+    "Diagnostic",
+    "Rule",
+    "Severity",
+    "SkillScanner",
+    "LibraryAuditor",
+    "__version__",
+]
+

skillguard/cli.py

@@ -0,0 +1,214 @@
+"""Command-line interface for SkillGuard."""
+
+import argparse
+import sys
+from pathlib import Path
+from typing import List, Set
+
+from . import __version__
+from .formatter import format_github, format_json, format_terminal
+from .library import LibraryAuditor
+from .rules import Diagnostic, Severity, RULES
+from .scaffold import create_skill_scaffold
+from .scanner import SkillScanner
+
+
+def parse_ignore_list(ignore_str: str) -> Set[str]:
+    if not ignore_str:
+        return set()
+    return {code.strip().upper() for code in ignore_str.split(",") if code.strip()}
+
+
+def cmd_check(args) -> int:
+    target_path = Path(args.path)
+    if not target_path.exists():
+        print(f"Error: Path '{target_path}' does not exist.", file=sys.stderr)
+        return 1
+
+    ignored = parse_ignore_list(args.ignore)
+    scanner = SkillScanner(ignored_rules=ignored)
+
+    diagnostics: List[Diagnostic] = []
+    diagnostics.extend(scanner.scan_path(target_path))
+
+    # Also audit library-level checks if target is a directory and not disabled
+    if target_path.is_dir() and not getattr(args, "no_library", False):
+        auditor = LibraryAuditor(target_path, use_semantic=getattr(args, "semantic", False))
+        lib_diags = [d for d in auditor.audit_library() if d.rule.code not in ignored]
+        diagnostics.extend(lib_diags)
+
+    # Output formatting
+    if args.format == "json":
+        print(format_json(diagnostics))
+    elif args.format == "github":
+        print(format_github(diagnostics))
+    else:
+        print(format_terminal(diagnostics, verbose=args.verbose))
+
+    has_errors = any(d.severity == Severity.ERROR for d in diagnostics)
+    return 1 if has_errors else 0
+
+
+def cmd_audit(args) -> int:
+    """Security-focused audit (SF1xx, SF2xx only)."""
+    target_path = Path(args.path)
+    if not target_path.exists():
+        print(f"Error: Path '{target_path}' does not exist.", file=sys.stderr)
+        return 1
+
+    ignored = parse_ignore_list(args.ignore)
+    scanner = SkillScanner(ignored_rules=ignored)
+
+    all_diags = scanner.scan_path(target_path)
+    # Filter to security & portability rules only
+    sec_diags = [d for d in all_diags if d.rule.code.startswith(("SF1", "SF2"))]
+
+    if args.format == "json":
+        print(format_json(sec_diags))
+    elif args.format == "github":
+        print(format_github(sec_diags))
+    else:
+        print(format_terminal(sec_diags, verbose=args.verbose))
+
+    has_errors = any(d.severity == Severity.ERROR for d in sec_diags)
+    return 1 if has_errors else 0
+
+
+def cmd_dedupe(args) -> int:
+    """Multi-skill library collision and token bloat check."""
+    target_path = Path(args.path)
+    if not target_path.is_dir():
+        print(f"Error: Target '{target_path}' must be a directory containing skills.", file=sys.stderr)
+        return 1
+
+    ignored = parse_ignore_list(args.ignore)
+    auditor = LibraryAuditor(target_path, use_semantic=getattr(args, "semantic", False))
+    diagnostics = [d for d in auditor.audit_library() if d.rule.code not in ignored]
+
+    if args.format == "json":
+        print(format_json(diagnostics))
+    elif args.format == "github":
+        print(format_github(diagnostics))
+    else:
+        print(format_terminal(diagnostics, verbose=args.verbose))
+
+    has_errors = any(d.severity == Severity.ERROR for d in diagnostics)
+    return 1 if has_errors else 0
+
+
+def cmd_init(args) -> int:
+    try:
+        path = create_skill_scaffold(args.name, Path(args.dir), description=args.description or "")
+        print(f"✓ Created new production-ready skill scaffold at:\n  {path.resolve()}")
+        return 0
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+
+
+def cmd_rules(args) -> int:
+    """List all available diagnostic rules."""
+    print(f"\nSkillGuard Diagnostic Rules (v{__version__}):\n")
+    print(f"{'Code':<8} {'Category':<12} {'Severity':<10} {'Name':<32} {'Summary'}")
+    print("-" * 90)
+    for code, rule in sorted(RULES.items()):
+        print(f"{rule.code:<8} {rule.category:<12} {rule.severity.value:<10} {rule.name:<32} {rule.summary}")
+    print("\nRun `skillguard check <path>` (or `skg check <path>`) to validate skills.\n")
+    return 0
+
+
+def cmd_stats(args) -> int:
+    """Calculate token and size statistics for skills."""
+    target_path = Path(args.path)
+    auditor = LibraryAuditor(target_path)
+    skills = auditor.find_all_skills()
+
+    if not skills:
+        print("No skills found.")
+        return 0
+
+    print(f"\nSkill Library Statistics ({len(skills)} skills found):\n")
+    print(f"{'Skill Name':<30} {'Words':<10} {'Est. Tokens':<15} {'Status'}")
+    print("-" * 65)
+
+    total_words = 0
+    for sdir in skills:
+        skill_md = sdir / "SKILL.md"
+        text = skill_md.read_text(encoding="utf-8", errors="replace")
+        words = len(text.split())
+        total_words += words
+        est_tokens = int(words * 1.33)
+        status = "Optimal" if 40 <= words <= 1600 else "Too Long" if words > 1600 else "Too Short"
+        print(f"{sdir.name:<30} {words:<10} ~{est_tokens:<14} {status}")
+
+    total_tokens = int(total_words * 1.33)
+    print("-" * 65)
+    print(f"{'Total Library Footprint':<30} {total_words:<10} ~{total_tokens:<14}\n")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="skillguard",
+        description="SkillGuard: The Security Scanner, Linter, and Quality Gate for AI Agent Skills.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # check
+    p_check = subparsers.add_parser("check", help="Lint and security-scan skills")
+    p_check.add_argument("path", nargs="?", default=".", help="Path to SKILL.md or skills directory (default: current dir)")
+    p_check.add_argument("--format", choices=["terminal", "json", "github"], default="terminal", help="Output format")
+    p_check.add_argument("--verbose", "-v", action="store_true", help="Show remediation guidance")
+    p_check.add_argument("--ignore", default="", help="Comma-separated rule codes to ignore (e.g. SF008,SF201)")
+    p_check.add_argument("--no-library", action="store_true", help="Skip multi-skill library checks")
+    p_check.add_argument("--semantic", action="store_true", help="Use dense vector embeddings for collision check (requires sentence-transformers)")
+    p_check.set_defaults(func=cmd_check)
+
+    # audit
+    p_audit = subparsers.add_parser("audit", help="Security and safety audit (destructive ops, data exfil, injection)")
+    p_audit.add_argument("path", nargs="?", default=".", help="Path to SKILL.md or skills directory")
+    p_audit.add_argument("--format", choices=["terminal", "json", "github"], default="terminal", help="Output format")
+    p_audit.add_argument("--verbose", "-v", action="store_true", help="Show remediation guidance")
+    p_audit.add_argument("--ignore", default="", help="Comma-separated rule codes to ignore")
+    p_audit.set_defaults(func=cmd_audit)
+
+    # dedupe
+    p_dedupe = subparsers.add_parser("dedupe", help="Analyze routing collisions, trigger overlap, and library caps")
+    p_dedupe.add_argument("path", nargs="?", default=".", help="Path to skills directory")
+    p_dedupe.add_argument("--format", choices=["terminal", "json", "github"], default="terminal", help="Output format")
+    p_dedupe.add_argument("--verbose", "-v", action="store_true", help="Show remediation guidance")
+    p_dedupe.add_argument("--ignore", default="", help="Comma-separated rule codes to ignore")
+    p_dedupe.add_argument("--semantic", action="store_true", help="Use dense vector embeddings for collision check (requires sentence-transformers)")
+    p_dedupe.set_defaults(func=cmd_dedupe)
+
+    # init
+    p_init = subparsers.add_parser("init", help="Scaffold a new production-ready skill pack")
+    p_init.add_argument("name", help="Skill name (e.g. git-conflict-resolver)")
+    p_init.add_argument("--dir", default=".", help="Target directory to create skill in (default: current dir)")
+    p_init.add_argument("--description", default="", help="Skill description")
+    p_init.set_defaults(func=cmd_init)
+
+    # rules
+    p_rules = subparsers.add_parser("rules", help="List all diagnostic rules and codes")
+    p_rules.set_defaults(func=cmd_rules)
+
+    # stats
+    p_stats = subparsers.add_parser("stats", help="Token and word count statistics for skills")
+    p_stats.add_argument("path", nargs="?", default=".", help="Path to skills directory")
+    p_stats.set_defaults(func=cmd_stats)
+
+    return parser
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+    exit_code = args.func(args)
+    sys.exit(exit_code)
+
+
+if __name__ == "__main__":
+    main()
+

skillguard/formatter.py

@@ -0,0 +1,117 @@
+"""Formatters for diagnostic output: Terminal (ANSI), JSON, and GitHub Actions."""
+
+import json
+import sys
+from typing import List
+
+from .rules import Diagnostic, Severity
+
+# ANSI color codes
+RESET = "\033[0m"
+BOLD = "\033[1m"
+DIM = "\033[2m"
+RED = "\033[31m"
+YELLOW = "\033[33m"
+CYAN = "\033[36m"
+GREEN = "\033[32m"
+MAGENTA = "\033[35m"
+
+
+def supports_color() -> bool:
+    """Check if stdout supports ANSI color escape sequences."""
+    return sys.stdout.isatty()
+
+
+def format_terminal(diagnostics: List[Diagnostic], verbose: bool = False) -> str:
+    use_color = supports_color()
+    lines = []
+
+    # Sort diagnostics by file, then line, then severity
+    sorted_diags = sorted(
+        diagnostics,
+        key=lambda d: (
+            d.file_path,
+            d.line or 0,
+            0 if d.severity == Severity.ERROR else 1,
+        ),
+    )
+
+    current_file = None
+    for d in sorted_diags:
+        if d.file_path != current_file:
+            current_file = d.file_path
+            header = f"\n{BOLD}{current_file}{RESET}" if use_color else f"\n{current_file}"
+            lines.append(header)
+
+        # Severity badge
+        if d.severity == Severity.ERROR:
+            badge = f"{RED}{BOLD}error{RESET}" if use_color else "error"
+        elif d.severity == Severity.WARNING:
+            badge = f"{YELLOW}{BOLD}warning{RESET}" if use_color else "warning"
+        else:
+            badge = f"{CYAN}{BOLD}info{RESET}" if use_color else "info"
+
+        line_str = f":{d.line}" if d.line else ""
+        col_str = f":{d.column}" if d.column else ""
+        loc = f"{DIM}{line_str}{col_str}{RESET}" if use_color else f"{line_str}{col_str}"
+        code = f"{MAGENTA}[{d.rule.code}]{RESET}" if use_color else f"[{d.rule.code}]"
+
+        msg = d.formatted_message
+        lines.append(f"  {loc:8} {badge:16} {code:8} {msg}")
+
+        if d.snippet:
+            snip = f"    {DIM}> {d.snippet}{RESET}" if use_color else f"    > {d.snippet}"
+            lines.append(snip)
+
+        if verbose and d.rule.remediation:
+            hint = f"    {CYAN}Fix: {d.rule.remediation}{RESET}" if use_color else f"    Fix: {d.rule.remediation}"
+            lines.append(hint)
+
+    # Summary
+    errors = sum(1 for d in diagnostics if d.severity == Severity.ERROR)
+    warnings = sum(1 for d in diagnostics if d.severity == Severity.WARNING)
+
+    summary_parts = []
+    if errors:
+        summary_parts.append(f"{RED}{BOLD}{errors} error{'s' if errors != 1 else ''}{RESET}" if use_color else f"{errors} errors")
+    if warnings:
+        summary_parts.append(f"{YELLOW}{BOLD}{warnings} warning{'s' if warnings != 1 else ''}{RESET}" if use_color else f"{warnings} warnings")
+
+    if not diagnostics:
+        return f"\n{GREEN}{BOLD}✓ All skill checks passed! Zero safety or quality defects detected.{RESET}\n" if use_color else "\n✓ All skill checks passed! Zero safety or quality defects detected.\n"
+
+    status = ", ".join(summary_parts)
+    return "\n".join(lines) + f"\n\nFound {status}.\n"
+
+
+def format_json(diagnostics: List[Diagnostic]) -> str:
+    data = []
+    for d in diagnostics:
+        data.append({
+            "file": d.file_path,
+            "line": d.line,
+            "column": d.column,
+            "rule_code": d.rule.code,
+            "rule_name": d.rule.name,
+            "category": d.rule.category,
+            "severity": d.severity.value,
+            "message": d.formatted_message,
+            "snippet": d.snippet,
+            "remediation": d.rule.remediation,
+        })
+    return json.dumps(data, indent=2)
+
+
+def format_github(diagnostics: List[Diagnostic]) -> str:
+    """GitHub Actions workflow commands for inline PR annotations."""
+    lines = []
+    for d in diagnostics:
+        cmd = "error" if d.severity == Severity.ERROR else "warning"
+        loc = f"file={d.file_path}"
+        if d.line:
+            loc += f",line={d.line}"
+        if d.column:
+            loc += f",col={d.column}"
+        lines.append(f"::{cmd} {loc}::[{d.rule.code}] {d.formatted_message}")
+    return "\n".join(lines)
+

skillguard/library.py

@@ -0,0 +1,157 @@
+"""Library auditor: cross-skill analysis, collision detection, and token budgeting."""
+
+import re
+from collections import defaultdict
+from pathlib import Path
+from typing import Dict, List, Set, Tuple
+
+from .rules import Diagnostic, Rule, RULES
+
+STOPWORDS = {
+    "use", "when", "the", "a", "an", "for", "to", "of", "and", "or",
+    "not", "this", "is", "with", "on", "in", "it", "at", "by", "from",
+    "that", "as", "be", "do", "you", "agent", "skill"
+}
+
+LIBRARY_CAP = 8
+COLLISION_JACCARD_THRESHOLD = 0.55
+
+
+class LibraryAuditor:
+    """Performs library-wide analysis across a collection of skills.
+
+    Engine:
+      - Default: Fast, zero-dependency Lexical & Trigger Overlap Analysis
+                 (Jaccard similarity on keyword tokens and n-grams).
+      - Optional: Dense vector semantic analysis if `use_semantic=True`
+                 and `sentence-transformers` is installed.
+    """
+
+    def __init__(self, root_dir: Path, use_semantic: bool = False):
+        self.root_dir = Path(root_dir)
+        self.use_semantic = use_semantic
+
+    def find_all_skills(self) -> List[Path]:
+        """Find all skill directories containing a SKILL.md under root_dir."""
+        skill_dirs = []
+        if (self.root_dir / "SKILL.md").exists():
+            return [self.root_dir]
+        for p in sorted(self.root_dir.rglob("SKILL.md")):
+            # Ignore hidden or internal folders like .skillguard, .skill-forge, or _versions
+            if not any(part.startswith(".") or part.startswith("_") for part in p.parts):
+                skill_dirs.append(p.parent)
+        return skill_dirs
+
+    def tokenize_description(self, description: str) -> Set[str]:
+        words = re.findall(r"[a-z]{3,}", description.lower())
+        return {w for w in words if w not in STOPWORDS}
+
+    def audit_library(self) -> List[Diagnostic]:
+        diagnostics: List[Diagnostic] = []
+        skills = self.find_all_skills()
+
+        # SF302: Library size check (> 8 skills)
+        if len(skills) > LIBRARY_CAP:
+            diagnostics.append(
+                Diagnostic(
+                    rule=RULES["SF302"],
+                    file_path=str(self.root_dir),
+                    message=f"Library contains {len(skills)} skills (recommended cap: {LIBRARY_CAP}). Over-accumulation dilutes agent lift.",
+                )
+            )
+
+        # Collect descriptions and metadata
+        descriptions: Dict[str, str] = {}
+        names: List[str] = []
+        domains: Dict[str, List[str]] = defaultdict(list)
+
+        for sdir in skills:
+            skill_md = sdir / "SKILL.md"
+            text = skill_md.read_text(encoding="utf-8", errors="replace")
+            desc_match = re.search(r"description:\s*(.+)", text)
+            name_match = re.search(r"name:\s*(.+)", text)
+
+            skill_name = name_match.group(1).strip() if name_match else sdir.name
+            desc_text = desc_match.group(1).strip() if desc_match else ""
+
+            descriptions[skill_name] = desc_text
+            names.append(skill_name)
+
+            # Guess domain from folder or name prefix
+            domain = sdir.parent.name if sdir.parent != self.root_dir else skill_name.split("-")[0]
+            domains[domain].append(skill_name)
+
+        # SF301: Description collisions / routing interference
+        if self.use_semantic:
+            try:
+                from sentence_transformers import SentenceTransformer, util
+                model = SentenceTransformer("all-MiniLM-L6-v2")
+                desc_texts = [descriptions[n] for n in names]
+                embeddings = model.encode(desc_texts, convert_to_tensor=True)
+                cosine_scores = util.cos_sim(embeddings, embeddings)
+
+                for i, a in enumerate(names):
+                    for j in range(i + 1, len(names)):
+                        b = names[j]
+                        score = float(cosine_scores[i][j])
+                        if score >= 0.75:
+                            diagnostics.append(
+                                Diagnostic(
+                                    rule=RULES["SF301"],
+                                    file_path=str(self.root_dir),
+                                    message=(
+                                        f"High semantic vector similarity ({round(score * 100)}%) between `{a}` and `{b}`. "
+                                        f"Overlapping intent causes routing confusion."
+                                    ),
+                                )
+                            )
+            except ImportError:
+                diagnostics.append(
+                    Diagnostic(
+                        rule=RULES["SF301"],
+                        file_path=str(self.root_dir),
+                        message="Notice: 'sentence-transformers' not installed for dense semantic analysis. Falling back to pure-Python lexical trigger overlap. Install with: pip install skillguard[semantic]",
+                    )
+                )
+                self.use_semantic = False
+
+        if not self.use_semantic:
+            # Default: Pure-Python Lexical & Trigger Overlap Analysis (Jaccard similarity)
+            for i, a in enumerate(names):
+                tokens_a = self.tokenize_description(descriptions[a])
+                if not tokens_a:
+                    continue
+                for b in names[i + 1:]:
+                    tokens_b = self.tokenize_description(descriptions[b])
+                    if not tokens_b:
+                        continue
+                    intersection = tokens_a & tokens_b
+                    union = tokens_a | tokens_b
+                    jaccard = len(intersection) / len(union) if union else 0.0
+
+                    if jaccard >= COLLISION_JACCARD_THRESHOLD:
+                        shared_keywords = ", ".join(sorted(intersection)[:5])
+                        diagnostics.append(
+                            Diagnostic(
+                                rule=RULES["SF301"],
+                                file_path=str(self.root_dir),
+                                message=(
+                                    f"High lexical trigger overlap ({round(jaccard * 100)}%) between `{a}` and `{b}`. "
+                                    f"Shared trigger tokens: [{shared_keywords}]. Causes routing confusion."
+                                ),
+                            )
+                        )
+
+        # SF303: Domain duplicate skills
+        for domain, d_skills in domains.items():
+            if len(d_skills) > 1 and domain not in ("skills", "tasks", "src"):
+                diagnostics.append(
+                    Diagnostic(
+                        rule=RULES["SF303"],
+                        file_path=str(self.root_dir),
+                        message=f"Multiple skills found in domain '{domain}': {', '.join(d_skills)}. Consider consolidating into one skill.",
+                    )
+                )
+
+        return diagnostics
+