agent-introspection-debugging-skill

What I do

Systematically diagnose why agents, skills, or subagents misbehave: configuration validation → permission audit → context/behavior analysis → specific fix recommendations.

Trigger phrases: "debug agent", "why is the agent not working", "agent introspection", "skill not triggering", "agent ignoring instructions", "fix agent behavior", "diagnose subagent".

Step 1: Symptom → Likely Cause

Symptom	Category	Likely Cause
Agent doesn't spawn	Config	Missing .md file, wrong name, permission issue
Spawns but does nothing	Permissions	Tools denied, no skill access, step limit too low
Wrong output	Behavior	Missing context, conflicting instructions, model limits
Ignores AGENTS.md	Routing	AGENTS.md not loaded, routing rules override
Skill doesn't trigger	Discovery	Name mismatch, trigger phrases missing, not installed
Can't use tools	Permissions	Tool not in permissions allowlist
Loops or repeats	Behavior	Missing termination condition, unclear success criteria
MCP tools not called	Discovery	Server not configured, tool unknown to agent

Step 2: Configuration Checklist

Agent (agents/<name>.md): file exists · description present and <50 words (always in Task context) · mode set · model valid · steps set (10-25) · permissions rules array present (v2 shape) · YAML parses · body is valid markdown.

Skill (skills/<name>/SKILL.md): directory name == frontmatter name exactly · description present · license + compatibility present · required sections present ("What I do", "When to use me", workflow) · YAML parses.

Step 3: Permission Audit

For each needed tool: allowed in permissions? Any deny overriding it? task delegation targets allowed? For each loaded skill: allowed via action: skill rule? Directory exists with valid SKILL.md? Name case-exact?

Issue	Symptom	Fix
Missing read allow	Can't read files	Add {action: read, effect: allow}
Missing glob allow	Can't find files	Add glob allow rule
Missing subagent targets	Can't spawn subagents	Allow the subagent names (action: subagent)
edit: deny but must edit	Reads, never modifies	Allow edit (scoped to task paths)
shell: deny on build agent	Can't run commands	Allow shell with caution
Skill name mismatch	Skill won't load	Match exact directory name

Step 4: Behavior Analysis

• Context loading: is AGENTS.md loaded? Right routing table entries? Agent .md used as system prompt?
• Skill discovery: do trigger phrases match how the user asks? Is the description selective enough?
• Task prompt quality: specific? Enough context (paths, requirements)? Return format stated? CodeGraph guidance included when .codegraph/ exists?
• Model selection: model appropriate for complexity? Available in current config?

Step 5: Diagnosis Report (output contract)

**Agent/Skill**: <name> · **Symptom**: <what's wrong> · **Root Cause**: <cause> · **Confidence**: h/m/l

### Evidence
1. <finding, e.g. "permissions denies edit but the task requires writes">

### Recommended Fix
<specific, actionable>

### Verification
<how to confirm the fix works>

Common Patterns (cause → fix)

• Generic output → Task prompt too vague: add file paths, stack, specific requirements
• Can't find files → read/glob denied: add allow rules
• Ignores skills → skill missing from permissions skill rules, or name mismatch (case-sensitive, -skill suffix)
• Loops forever → no return contract: add explicit completion criteria to the agent .md
• Never uses CodeGraph → no .codegraph/ or prompt doesn't mention it: codegraph init -i + prompt guidance
• Skill never triggers → trigger phrases absent from description/When-to-use: add them
• Irrelevant subagent output → constrain the Task prompt: specific paths, function names, output format
• MCP tools not called → server not in opencode.json or tool unknown: check config; follow the MCP Availability Guard

Debugging Efficiency

Config first (most common), permissions second (quick win), behavior last. One change at a time, re-test after each. Compare against a working agent/skill as reference. Persist fixes as learnings.

Integration

• civiltekk-context-optimization-skill — context bloat is a diagnosis outcome
• opencode-skills-maintainer-skill — post-fix format validation
• civiltekk-opencode-creation-skill — agent/skill authoring rules referenced when fixing
• continuous-learning-skill — store diagnosed anti-patterns

References

• civiltekk-opencode-creation-skill — agent and skill authoring best practices
• opencode-skills-maintainer-skill — skill format validation
• continuous-learning-skill — debugging-pattern storage

Removal note (2026-09-19, #409 trim per LEARNINGS #383 recipe): dropped the three worked debugging examples, Best Practices prose (compressed into "Debugging Efficiency"), verbose checklist markdown, and the metadata.audience/metadata.workflow checklist item (deliberate — the v2 frontmatter contract at the time reserved metadata sub-keys protocol/pattern; pre-#510 — the contract now defines protocol, pattern, os, harness). Also corrected legacy v1 permission-block references to the v2 permissions rules array (post-#380 shape). Kept verbatim: frontmatter, symptom table, permission-issue table, output contract, pattern list.