context-optimizer

Analyze skill content for optimal placement (Skill vs Passive Context vs Hybrid), compress markdown to pipe-delimited format (60-80% token reduction), and validate compliance against the decision framework. Passive context wins for what the model cannot know (post-cutoff APIs, repo gotchas); pre-trained knowledge belongs in progressive disclosure. Use when you ask "compress this skill", "Skill vs Passive Context placement", "reduce tokens". Do NOT use for gathering knowledge before a task (use context-gather).

Jump to install

Repository: rjmurillo/ai-agents
Last source activity: August 8, 2026 at 21:50
Detected SKILL.md language: English
Stars: 41
Forks: 13

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

A direct command skips the review prompt. Inspect the source before running it.

npx skills add https://github.com/rjmurillo/ai-agents --skill context-optimizer

The command stays on one line. Scroll horizontally to inspect it before copying.

Prefer a local copy? Download the files currently available to SkillsMP.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

File Explorer

14 files

SKILL.md

Source instructions · Read-only preview

Back to search Back to installation

spec

Define what to build. Transform a problem into testable requirements with acceptance criteria.

2026-08-09

session-end

Validate and complete session logs before commit. Auto-populates session end evidence (commit SHA, lint results, memory updates) and runs validation. Use when finishing a session, before committing, or when session validation fails. Do NOT use to create a new session log (use session-init) or to repair a session protocol failure reported by CI (use session-log-fixer).

2026-08-09

session-init

Create protocol-compliant JSON session logs with verification-based enforcement. Autonomous operation with auto-incremented session numbers and objective derivation from git state. Use when starting any new session. Use when you say "start a session", "create the session log". Do NOT use for mid-session protocol checks (use session), or to complete and validate a log at the end of a session (use session-end).

2026-08-09

View all from this repository

Script	Purpose	Exit Codes
`analyze_skill_placement.py`	Classify content as Skill/PassiveContext/Hybrid	0=success, 1=error
`compress_markdown_content.py`	Compress markdown with token reduction metrics	0=success, 1=error, 2=config, 3=external
`test_skill_passive_compliance.py`	Validate compliance with decision framework	0=pass, 1=violations
`extract_and_index.py`	Extract sections into detail files with pipe-delimited index	0=success, 1=error, 2=config, 3=external
`path_validation.py`	Shared CWE-22 repo-root-anchored path validation	N/A (library module)

uv pip install -e ".[dev]"   # includes tiktoken
pip install tiktoken           # or install directly

Content	Model already knows it	Where it goes
A post-cutoff framework API	No	Passive context
This repo's dash ban, its gates	No	Passive context
SOLID, Clean Code, refactoring	Yes	Progressive disclosure, or nowhere
Deep book material	Partly	Progressive disclosure

Tool Details: Skill/Passive Content Analyzer

Script: scripts/analyze_skill_placement.py

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

The script reports shape, not admission. It cannot tell whether the model already knows the content, and that is the question the Decision Framework above turns on. Use it for size and duplication; the Decision Framework decides what earns an always-on slot.

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

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:

Classification	Criteria	Confidence
Skill	skillScore > passiveScore + 3	70-90%
PassiveContext	passiveScore > skillScore + 3	70-90%
Hybrid	abs(skillScore - passiveScore) <= 3	50-70%

Tool Details: Content Compression Utility

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:

Level	Reduction	Techniques
Light	40-50%	Headers, tables, whitespace
Medium	50-60%	+ redundant words, tighter whitespace
Aggressive	60-80%	+ H3 compression, lists, abbreviations

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

Tool Details: Extract-and-Index Utility

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.

Tool Details: Compliance Validator

Script: scripts/test_skill_passive_compliance.py

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

6 Compliance Checks:

Skills contain actions (verbs, tool execution, scripts)
Passive context is knowledge-only (no action patterns)
CLAUDE.md under 200 lines (Anthropic recommendation)
@imported files exist and are readable
Skills have frontmatter (name and description)
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:

Violation	Fix
CLAUDE.md too long	Split into separate files, add @imports
Missing @import file	Create file or remove @import directive
Skill missing frontmatter	Add `---` block with `name:` and `description:`
Skill has no actions	Add scripts or move to passive context
Passive has actions	Extract executable content to a skill
Duplicate content	Remove redundant content from skill or passive

Classification Examples

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, tables and lists, no commands

{"classification": "PassiveContext", "confidence": 80, "reasoning": "High reference content ratio (0.85)"}

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"]
  }
}

Testing

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:

Component	Tests	Key Areas
Compliance Validator	19/20 (95%)	Line count, @imports, frontmatter, duplicates, exit codes
Analyzer	Full	Tool calls, action verbs, classification logic, confidence scoring
Extract-and-Index	36	Slug generation, parsing, index format, 60%+ reduction targets
Compressor	Full	All levels, code block preservation, 40-80% reduction targets

name	context-optimizer
version	1.2.0
description	Analyze skill content for optimal placement (Skill vs Passive Context vs Hybrid), compress markdown to pipe-delimited format (60-80% token reduction), and validate compliance against the decision framework. Passive context wins for what the model cannot know (post-cutoff APIs, repo gotchas); pre-trained knowledge belongs in progressive disclosure. Use when you ask "compress this skill", "Skill vs Passive Context placement", "reduce tokens". Do NOT use for gathering knowledge before a task (use context-gather).
license	MIT
user-invocable	true
allowed-tools	["view","bash","glob"]

name	context-optimizer
version	1.2.0
description	Analyze skill content for optimal placement (Skill vs Passive Context vs Hybrid), compress markdown to pipe-delimited format (60-80% token reduction), and validate compliance against the decision framework. Passive context wins for what the model cannot know (post-cutoff APIs, repo gotchas); pre-trained knowledge belongs in progressive disclosure. Use when you ask "compress this skill", "Skill vs Passive Context placement", "reduce tokens". Do NOT use for gathering knowledge before a task (use context-gather).
license	MIT
user-invocable	true
allowed-tools	["view","bash","glob"]

Configuration	Pass Rate
Baseline (no docs)	53%
Skill (default)	53%
Skill + explicit instructions	79%
AGENTS.md passive context	100%

context-optimizer

Install options

Review the source files