Skill Snitch

Skill Snitch Protocol

Skill Snitch audits MOOLLM skills for security issues through static analysis and runtime surveillance. It's prompt-driven - no Python code, just orchestration via LLM tool calls.

Skill Type Detection

skill-snitch distinguishes between skill types and applies appropriate requirements:

MOOLLM Skills (Strict Requirements)

MOOLLM skills are identified by:

• Presence of CARD.yml and/or SKILL.md
• Tags containing "moollm"
• References to other skills/* or PROTOCOLS.yml
• Use of K-lines/K-refs

Required files:

• CARD.yml - Interface, methods, tools, advertisements
• SKILL.md - Protocol documentation
• README.md - GitHub-facing documentation

Anthropic/Generic Skills (Flexible)

Non-MOOLLM skills (Anthropic MCP skills, generic tools) have no strict file requirements:

• May use .mdc files (Anthropic format)
• Often standalone with no cross-references
• No CARD.yml/SKILL.md required

Classification Output

classification:
  type: moollm      # moollm | anthropic | generic | hybrid
  confidence: high
  missing_requirements:
    - README.md     # If MOOLLM but missing
  recommendations:
    - "Add README.md for GitHub visibility"

Hybrid Skills

Skills with some MOOLLM elements but incomplete structure:

• Has CARD.yml but no SKILL.md
• References MOOLLM protocols but lacks proper structure
• Flagged for review

Auto-Initialize / Heal

On first invocation, check for and create missing user files:

.moollm/skill-snitch/
├── config.yml          # User preferences
├── ignore.yml          # Patterns/paths to skip
├── trust-overrides.yml # Manual trust level overrides
├── scan-history.yml    # Log of past scans
├── last-scan.yml       # Most recent scan results
└── trust-cache.yml     # Cached trust assessments

INIT Protocol

1. Check if .moollm/skill-snitch/ exists
   - If not: mkdir -p .moollm/skill-snitch/
   
2. For each required file, check existence:
   - config.yml
   - ignore.yml  
   - trust-overrides.yml
   - scan-history.yml
   
3. Create missing files from templates (see below)

4. Report: "skill-snitch initialized" or "skill-snitch healed: created X files"

File Templates

config.yml

# skill-snitch configuration
version: 1

startup_scan:
  enabled: false
  min_severity: medium
  
scan_defaults:
  include_examples: false
  follow_dependencies: true
  max_depth: 3
  
trust_defaults:
  unknown_skill: yellow
  no_card_yml: orange
  external_network: orange
  shell_commands: yellow

ignore.yml

# Patterns and paths to ignore during scans
version: 1

paths:
  - "skills/cursor-mirror/cursor_mirror.py"  # Contains pattern definitions
  - "**/*_test.py"
  - "**/examples/**"
  
patterns:
  - name: "pattern_definition"
    description: "Regex pattern definitions (not actual secrets)"
    match: 'AuditPattern\(|r".*\(\?i\)|PATTERN_REGISTRY'
    
  - name: "documentation_example"
    description: "Examples in docs"
    match: '```.*\n.*password.*\n.*```'
    
categories_to_skip:
  - info  # Skip INFO-level findings

trust-overrides.yml

# Manual trust level overrides
version: 1

overrides:
  # Example:
  # skills/trusted-skill/:
  #   trust: green
  #   reason: "Reviewed by Don on 2026-01-15"
  #   expires: 2026-07-15

scan-history.yml

# Scan history (append-only)
version: 1
scans: []
# Entries added automatically:
# - date: 2026-01-15T20:30:00Z
#   skill: skills/adventure/
#   findings: 3
#   trust: yellow

Scan Protocol

## SCAN Protocol

When asked to scan a skill:

1. **INIT** - Ensure .moollm/skill-snitch/ exists

2. **Load ignore list**
   - Read .moollm/skill-snitch/ignore.yml
   - Merge with skill's own .snitch-ignore if present
   
3. **Read skill metadata**
   - Read {skill_path}/CARD.yml
   - Note: tools, dependencies, methods
   
4. **Static scan**
   For each file in skill:
   - Skip if matches ignore patterns
   - Look for:
     - Shell commands (curl, wget, ssh, nc)
     - External URLs
     - Encoded content (base64, hex)
     - File access outside workspace
     - Undeclared dependencies
   
5. **Output K-REFs**
   For each finding:
   - Emit: {path}:{line} # {pattern} | {severity} - {description}
   
6. **Log scan**
   - Append to .moollm/skill-snitch/scan-history.yml

Snitch Protocol (Runtime)

## SNITCH Protocol

When asked to snitch on a skill's runtime behavior:

1. **Get composer ID**
   - User provides, or find most recent for this skill
   
2. **Call mirror's deep-snitch**
   Run: cursor-mirror deep-snitch --composer {id} --yaml
   
3. **Load skill's declared behavior**
   - From CARD.yml: tools, dependencies
   
4. **Compare declared vs actual**
   - Tools used but not declared?
   - Paths accessed outside workspace?
   - Network calls made?
   
5. **Output discrepancies**
   DECLARED: tools: [read_file, write_file]
   OBSERVED: tools: [read_file, write_file, Shell, WebSearch]
   UNDECLARED: [Shell, WebSearch]

Trust Assessment

Trust tiers:

• 🟢 GREEN - Verified safe, all checks pass
• 🔵 BLUE - Trusted source, minor warnings
• 🟡 YELLOW - Caution, review recommended
• 🟠 ORANGE - Suspicious, manual review required
• 🔴 RED - Dangerous, do not use

## TRUST Protocol

1. Run SCAN (static)
2. Run SNITCH (runtime) if composer provided
3. Check trust-overrides.yml for manual override
4. Calculate trust tier:
   
   RED if:
     - Any CRITICAL finding
     - Reverse shell pattern
     - Undeclared network + secrets access
     
   ORANGE if:
     - HIGH findings without explanation
     - Undeclared shell commands
     - No CARD.yml
     
   YELLOW if:
     - MEDIUM findings
     - Undeclared dependencies
     - External URLs
     
   BLUE if:
     - Only LOW/INFO findings
     - All tools declared
     - Known publisher
     
   GREEN if:
     - No findings
     - Consistency check passes
     - Trust override from user
     
5. Cache result in trust-cache.yml
6. Output assessment with K-REFs to concerns

Consistency Check

## CONSISTENCY Protocol

Verify all parts of skill agree:

1. **INDEX.yml ↔ CARD.yml**
   - Skill listed in skills/INDEX.yml?
   - Path correct?
   - Description matches?
   
2. **CARD.yml ↔ SKILL.md**
   - All methods documented?
   - Tools match?
   
3. **CARD.yml ↔ Implementation**
   - Declared dependencies imported?
   - Declared tools used?
   - Undeclared tools/deps?
   
4. **SKILL.md ↔ README.md**
   - Examples current?
   - No deprecated features mentioned?

Output drift findings as K-REFs.

Startup Scan (Optional)

If enabled in config.yml:

## SKILL-SCAN Advertisement

On session start:

1. Check config.yml: startup_scan.enabled
2. If enabled:
   - List all skills in skills/
   - Quick scan each (CARD.yml + *.py only)
   - Report summary:
   
   🔍 SKILL-SCAN: 12 skills scanned
   ✅ 10 clean
   ⚠️ 2 warnings:
      skills/untrusted/ - no CARD.yml
      skills/fetcher/ - undeclared network

Integration with cursor-mirror

skill-snitch calls cursor-mirror via shell tool:

# Deep audit
cursor-mirror deep-snitch --composer ID --yaml

# Pattern scan
cursor-mirror audit --patterns secrets,shell_exfil --yaml

# Tool usage
cursor-mirror tools ID --yaml

Parse YAML output and compare against skill's declared behavior.

Scan Methodology

See SCAN-METHODOLOGY.md for the two-phase approach:

1. Phase 1: Bash Scripts — Fast structural scan of ALL skills

   • Structure check (CARD.yml, SKILL.md, README.md)
   • Script detection (.py, .js files)
   • Pattern grep (exec, eval, password, etc.)
   • Tool tier extraction

2. Phase 2: LLM Batched Review — Deep read in batches of 5

   • Actually READ files, don't just grep
   • Scripts get full code review
   • Context determines if patterns are dangerous
   • Trust assessment per skill

Golden Rule: Grep finds. LLM understands.