context-optimizer

Script: scripts/analyze_skill_placement.py

Analyzes skill content and recommends Skill, Passive Context, or Hybrid placement.

Classification Logic:

• Tool Calls: Bash, Read, Write, Edit, gh, git, pwsh commands -> Skill
• Action Verbs: create, update, delete, execute, run -> Skill
• Reference Content: Tables, lists, code blocks -> Passive
• User Triggers: "when user", slash commands, explicit requests -> Skill
• Always-Needed: "always", "mandatory", "framework knowledge" -> Passive

Usage:

# Analyze a skill directory (from repo root)
python3 .claude/skills/context-optimizer/scripts/analyze_skill_placement.py -p .claude/skills/github

# Analyze a specific SKILL.md
python3 .claude/skills/context-optimizer/scripts/analyze_skill_placement.py -p .claude/skills/github/SKILL.md

# Get detailed metrics
python3 .claude/skills/context-optimizer/scripts/analyze_skill_placement.py -p .claude/skills/github -d

Output:

{
  "classification": "Hybrid",
  "confidence": 85,
  "reasoning": "High tool execution (12 calls); High reference content ratio (0.75)",
  "recommendations": {
    "Passive": ["Routing Rules", "Classification Framework"],
    "Skill": ["Get-UnaddressedComments.ps1", "Post-PRCommentReply.ps1"]
  }
}

Classification Thresholds:

Script: scripts/compress_markdown_content.py

Compress markdown to pipe-delimited format achieving 60-80% token reduction while maintaining 100% information density.

Compression Techniques:

• Convert tables to pipe-delimited: |key: value|key2: value2|
• Extract headings to index: [Section] |item1 |item2
• Strip redundant words (the, a, an, is, are)
• Collapse whitespace and abbreviate common terms
• Preserve code blocks

Usage:

# Basic compression (JSON output to stdout)
python3 scripts/compress_markdown_content.py -i README.md -l medium

# Save to file with aggressive compression
python3 scripts/compress_markdown_content.py -i CRITICAL-CONTEXT.md -l aggressive -o compressed.txt

# With verbose metrics
python3 scripts/compress_markdown_content.py -i input.md -l medium -v

Compression Levels:

Example (26 tokens -> 18 tokens, 31% reduction):

Before:

## Session Protocol

The session protocol has multiple phases:

1. Serena Activation - You must activate Serena

After:

[Session Protocol]
session protocol has multiple phases:
1. Serena Activation - activate Serena

Script: scripts/extract_and_index.py

Implements the Vercel extract-and-index pattern for 60-80% token reduction. Splits markdown by headings into detail files, generates a compact pipe-delimited index.

Usage:

# Extract sections and output JSON to stdout
python3 scripts/extract_and_index.py -i AGENTS.md -d .agents-details

# Write index to a file
python3 scripts/extract_and_index.py -i AGENTS.md -d .agents-details -o AGENTS-INDEX.md

# Custom reference path in index
python3 scripts/extract_and_index.py -i AGENTS.md -d .agents-details -r .agents-docs -o AGENTS-INDEX.md

Output Index Format (Vercel pattern):

[Architecture]
|Layered design with separation of concerns (see: .agents-details/architecture.md)
[Testing]
|80% coverage required for business logic (see: .agents-details/testing.md)

Works with CLAUDE.md @import mechanism. Reference via @AGENTS-INDEX.md.

Script: scripts/test_skill_passive_compliance.py

Validates content placement against the skill vs passive context decision framework.

6 Compliance Checks:

1. Skills contain actions (verbs, tool execution, scripts)
2. Passive context is knowledge-only (no action patterns)
3. CLAUDE.md under 200 lines (Anthropic recommendation)
4. @imported files exist and are readable
5. Skills have frontmatter (name and description)
6. No duplicate content between skills and passive context

Usage:

# Scan .claude directory (JSON output)
python3 scripts/test_skill_passive_compliance.py

# Scan specific directory with table output
python3 scripts/test_skill_passive_compliance.py --path .claude/skills/github --format table

Exit Codes: 0 = all passed, 1 = violations detected

Common Violations:

Clear Skill Classification

Input: GitHub skill with gh pr create, gh issue close commands

{"classification": "Skill", "confidence": 85, "reasoning": "High tool execution (8 calls); Many action verbs (12)"}

### Clear Passive Classification

**Input**: Memory hierarchy reference with tables and always-needed patterns

```json

{"classification": "PassiveContext", "confidence": 90, "reasoning": "High reference content ratio (0.85); Always-needed information (5 indicators)"}

Hybrid Classification

Input: PR comment responder with routing rules + script execution

{
  "classification": "Hybrid",
  "confidence": 65,
  "reasoning": "High reference content ratio (0.72); Some tool execution (4 calls)",
  "recommendations": {
    "Passive": ["Routing Rules", "Classification Framework"],
    "Skill": ["Get-UnaddressedComments.ps1", "Post-PRCommentReply.ps1"]
  }
}

python3 -m pytest tests/                                          # all tests
python3 -m pytest tests/test_skill_passive_compliance_test.py -v  # specific
python3 -m pytest tests/ --cov=scripts --cov-report=term-missing  # coverage

Coverage Summary:

• Language: Python 3.12+ per ADR-042 (PowerShell deprecated)
• Testing: pytest with comprehensive coverage
• Exit codes: ADR-035 standardization (0 = success, non-zero = failure)
• Type safety: Full type hints using dataclasses and typing module
• Cross-platform: pathlib for platform-independent path handling

Marketplace Value

• Automated optimization: Compress context without manual editing
• Quality gates: Enforce best practices in CI/CD
• Token savings: 60-80% reduction = lower API costs