Analyze Agent Context & Configuration for Agent Performance Insights

Examine the repository's existing agent configuration and context files to assess how well they support coding agents.

Scope: Focus on agent context and configuration files — not application source code.

Before You Start

Read the shared reference files:

• Read the APEX taxonomy for the insight categories
• Read the insight report schema for the exact report structure

Resolving reference paths: The links above use relative paths (../../references/...) that work when this skill is read from its tile directory. If those paths do not resolve (e.g. when activated via a .claude/skills/ symlink), find the shared references at .tessl/tiles/*/agent-insight-experiment/references/ relative to the repository root.

Your report prefix is CTX (e.g., CTX-001, CTX-002).

Sensitive Value Handling (REQUIRED)

Several files in scope (.mcp.json, .cursor/mcp.json, .claude/settings.json, .claude/settings.local.json, tessl doctor output) routinely contain secrets: API keys, bearer tokens, OAuth tokens, database URLs with embedded passwords, webhook URLs, and env-var credentials. You must not reproduce these values in your report, tool output, quoted evidence, summaries, or any other channel.

Apply the following rules to every value you read from these files before including any of it in your output:

• MCP server env blocks: treat every value as sensitive. Reference keys by name only (e.g. env contains GITHUB_TOKEN). Never quote the value.
• Command and args in MCP or hook configs: only quote the binary / script path and non-secret flags. Redact any positional value that follows a flag matching /token|key|secret|password|bearer|auth|credential/i, any KEY=value segment where KEY matches that pattern, any JWT-shaped string (three dot-separated base64 segments), and any opaque string longer than ~20 characters that looks like random base64/hex. Replace the value with [REDACTED].
• Connection strings / URLs: if a URL contains user:password@ or a query-string token, rewrite as scheme://host/path?token=[REDACTED] (or similar) before quoting.
• tessl doctor output: capture only the structural summary (agent detection lines, tile names, version numbers, CLI version, token budget). If any section echoes a token, path with credentials, or auth header, redact before storing.
• When quoting context files as evidence: quote the instructional / descriptive lines. Do not quote any line that contains a value matching the redaction patterns above — paraphrase instead (e.g. "server github is configured with a GITHUB_TOKEN env var").
• When unsure, redact. A false-positive [REDACTED] is fine; a leaked credential is not.

These rules apply to every step below, including Step 0 (CLI output), Step 6 (MCP inspection), and the evidence you attach to findings in the final report.

What Counts as Agent Context

Inventory ALL of the following if they exist:

Cursor Configuration

• .cursor/rules/*.md or .cursor/rules/*.mdc — Rule files
• .cursorrules — Legacy root-level rules file
• .cursor/settings.json — Cursor-specific project settings
• Any .mdc files in the repo

Claude Code Configuration

• CLAUDE.md — Root-level Claude Code context
• AGENTS.md — Agent instructions (used by multiple tools)
• .claude/settings.json — Claude Code project settings
• .claude/commands/ — Custom slash commands
• **/CLAUDE.md — Directory-specific Claude context files

Cross-Tool Context

• AGENTS.md — Recognized by multiple tools
• .github/copilot-instructions.md — GitHub Copilot context
• CONTRIBUTING.md — Contributing guidelines (human-oriented but agents read these)
• README.md files — Project documentation (agents use these for orientation)

MCP Configuration

• .mcp.json (root) — Cross-tool MCP config (read by both Cursor and Claude Code)
• .cursor/mcp.json — Cursor-specific MCP server configuration
• .claude/settings.local.json — Claude Code MCP server enablement (enableAllProjectMcpServers or enabledMcpjsonServers fields)

Note: There is no .claude/mcp.json convention. Claude Code reads MCP servers from .mcp.json at the project root and enables them via .claude/settings.local.json.

Tessl Configuration

• tessl.json — Tessl plugin dependencies
• .tessl/ — Tessl installation directory
• Installed plugins and their skills/rules

Analysis Strategy

Step 0: Tessl CLI Check

Before file-based discovery, check if the Tessl CLI is available:

tessl doctor 2>&1

If the command succeeds, capture the structural output after redacting any secret values per the Sensitive Value Handling rules above. It provides authoritative data for:

• Agent Detection: Which agents are detected and configured vs needing setup (e.g. "Claude Code detected and configured", "Codex detected (needs Tessl setup)")
• Tile Sync State: Which tiles are synced, missing, or outdated — with version comparison
• Context Cost: Token budget breakdown per installed tile
• CLI Version: Whether the CLI is up to date

Store this output — it complements the file-based MCP inventory with richer agent detection and tile sync data. If tessl is not installed, note this and proceed with file-based detection only. If a tessl.json exists but tessl is not installed, that itself is a significant TCG-2 finding.

Step 1: Complete Inventory

Find every agent context file in the repository:

# Search for known context file patterns
find . -maxdepth 5 \( \
  -name "AGENTS.md" -o \
  -name "CLAUDE.md" -o \
  -name ".cursorrules" -o \
  -name "*.mdc" -o \
  -name "copilot-instructions.md" -o \
  -name "CONTRIBUTING.md" -o \
  -name "tessl.json" -o \
  -name ".mcp.json" -o \
  -path "*/.cursor/rules/*" -o \
  -path "*/.cursor/mcp.json" -o \
  -path "*/.cursor/settings.json" -o \
  -path "*/.claude/*" \
\) -type f 2>/dev/null

Record what exists and what's missing. The absence of context files is itself a significant finding.

Checkpoint: If zero context files are found, skip to Step 5 (Coverage Gap Analysis) and flag TCG-1 as the primary finding — the complete absence of agent context is itself the most important insight.

Step 2: Quality Assessment

For each context file, assess: clarity (would an agent understand?), specificity (actionable or vague?), completeness (covers key aspects?), currency (references current patterns?), structure (organized or wall of text?).

Step 3: Conflict Detection

Cross-reference context files against each other:

• Do .cursor/rules/ files and CLAUDE.md give conflicting guidance on the same topic?
• Does AGENTS.md contradict any .cursor/rules/ files?
• Are there multiple context files covering the same topic with different instructions?
• Do directory-specific context files conflict with root-level ones?

Conflicts are high-impact findings — they directly confuse agents.

Step 4: Cross-Tool Consistency

Compare what different tools receive:

• Cursor users get: .cursor/rules/, .cursorrules, MCP servers from .cursor/mcp.json and .mcp.json
• Claude Code users get: CLAUDE.md, .claude/settings.json, .claude/commands/, MCP servers from .mcp.json (enabled via .claude/settings.local.json)
• Both get: AGENTS.md, CONTRIBUTING.md, README.md, MCP servers defined in .mcp.json

If tessl doctor was run in Step 0, its Agent Detection section tells you which agents have Tessl's MCP server specifically. But always inspect the MCP config files too — repos often configure additional MCP servers beyond Tessl (e.g. database tools, GitHub, Figma, custom servers). Check whether those additional servers are available to all tools or only some.

Are there important instructions that only exist in one tool's configuration? This means some team members get guidance that others miss.

Step 5: Coverage Gap Analysis

Assess whether context files cover expected topics: build/test instructions, coding conventions, architecture overview, internal library usage, common pitfalls, PR expectations, deployment context. Missing areas are high-value TCG-1 (missing context files) or KCG-6 (missing onboarding context) findings. Also watch for TCG-6 (unowned content) — context files with no clear maintainer drift out of date; and SCX-9 (redundant conventions) — content that restates standard language/framework rules or linter-enforced behaviour and bloats the agent's context budget without changing its output.

Step 6: MCP and Tool Configuration

Always inspect the MCP config files — they reveal the full landscape of MCP servers available to agents, not just Tessl:

• Read .mcp.json (root) and .cursor/mcp.json to inventory all configured servers
• Read .claude/settings.local.json for enableAllProjectMcpServers or enabledMcpjsonServers to see which servers Claude Code has enabled
• The absence of .claude/mcp.json does NOT mean Claude Code lacks MCP — that file is not a real convention

For each server, assess: is it relevant and useful? Is configuration complete or half-set-up? Are servers available to one tool but not another (e.g. only in .cursor/mcp.json but not in .mcp.json)?

When describing a server in findings, reference it by its server name and binary only. Never include raw env values, args that follow secret-looking flags, or URL credentials. Follow the Sensitive Value Handling rules.

Additionally, if tessl doctor output is available (from Step 0), use its Agent Detection section for Tessl-specific MCP status:

• "detected and configured" → Tessl MCP is working for that agent
• "detected (needs Tessl setup)" → real finding (TCG-2), the agent is installed but lacks Tessl MCP access

Step 7: Tessl Plugin Analysis

If tessl doctor output is available (from Step 0), use its Manifest Status table:

• Flag tiles with status "Missing" (in manifest but not downloaded) — these provide no value until synced
• Flag version mismatches between manifest and installed versions
• Note context cost data — unusually high front-loaded token costs may indicate bloated always-on rules
• If tessl is not installed but tessl.json exists, that's a significant TCG-2 finding: the project declares plugin dependencies but the tooling to use them is absent

Additionally, whether or not doctor output is available:

• Read tessl.json to understand what plugins are declared
• Check if plugin rules/skills complement or conflict with local context files
• Assess whether there are helpful plugins not yet installed

What to Look For

Agent context analysis is especially good at revealing:

• TCG-1 (Missing context files): The most direct finding — are context files present and good?
• TCG-5 (Cross tool inconsistency): Different tools getting different guidance
• TCG-6 (Unowned content): Context files with no clear owner, likely to drift stale
• CAS-1 (Contradictory context files): Direct conflicts between context files
• TCG-2 (Missing tool integrations): MCP or tool configurations that should exist
• TCG-3 (Missing skills and rules): Opportunities for skills that would help
• KCG-5 (Stale documentation): Context that references outdated patterns
• KCG-6 (Missing onboarding context): Missing setup/build/deploy guidance
• SCX-9 (Redundant conventions): Context restating language/linter-enforced rules that doesn't change agent output

Output

Produce a JSON report conforming to the insight report schema. Save to the path provided by the orchestrator (or .tessl-insights-poc/reports/agent-context.json standalone).

Set scope.metrics to include:

• context_files_found: total agent context files discovered
• rules_analyzed: number of rule files read
• skills_inventoried: number of installed skills/plugins found
• tools_detected: which agent tools have configuration present (Cursor, Claude Code, etc.)

Validation before saving:

• Verify all required metadata fields
• Confirm at least 8 insights (or fewer if the inventory is genuinely small, with justification)
• Quote specific passages from context files as evidence — but apply the Sensitive Value Handling rules to every quoted line. Before writing the report to disk, scan your own output for anything matching the redaction patterns (JWT-shaped strings, KEY=value pairs with secret-looking keys, long opaque tokens, user:password@ URLs) and replace with [REDACTED].

Mark data_source_exclusive: true for insights about context file quality, conflicts, and cross-tool consistency.