agent-guardrails-analyze
Scan Claude Code chat session logs for recurring agent anti-patterns (hedging, stalling, skipping, false completions, preference-asking, dismissing) and produce a ranked report with frequency counts, example excerpts, and suggested guardrail rules. Use when user asks to "analyze sessions for anti-patterns", "find bad patterns in logs", "what anti-patterns am I seeing", "agent-guardrails analyze", or wants data-driven guardrail recommendations.
What this skill does
# Agent Guardrails Analyze
Scan Claude Code session logs to detect recurring anti-patterns in assistant responses. Produce a ranked frequency report with excerpts and ready-to-use guardrail rule suggestions.
## Known Anti-Pattern Categories
The canonical regex patterns live in the plugin's `rules/` directory — one `.md` file per category. **Always read the patterns from those files** rather than hardcoding them, so analysis stays in sync with installed/refined rules.
**Source of truth:** `${CLAUDE_PLUGIN_ROOT}/rules/no-*.md`
Read each rule file's YAML frontmatter to extract the `name`, `pattern`, and `message` fields. The six categories are:
| # | Category | Rule file |
|---|----------|-----------|
| 1 | Guessing | `no-guessing.md` |
| 2 | Stalling | `no-stalling.md` |
| 3 | Preference-Asking | `no-preference-asking.md` |
| 4 | False Completion | `no-false-completion.md` |
| 5 | Skipping | `no-skipping.md` |
| 6 | Dismissing | `no-dismissing.md` |
Scan for ALL of them plus any novel patterns discovered during analysis.
## Workflow
### Step 1: Locate Session Logs
Find recent Claude Code session logs:
```bash
find ~/.claude/projects/ -name "*.jsonl" -mtime -7 ! -path "*/subagents/*" 2>/dev/null | head -30
```
If the user specifies a project or time range, narrow the search accordingly.
### Step 2: Build and Run Analysis Script
Create a Python script at `/tmp/agent-guardrails-analyze.py` that:
1. Reads each JSONL file
2. Extracts assistant message text from `type: "assistant"` entries where `message.content[].type == "text"`
3. Tests each message against ALL six anti-pattern regexes loaded from the `rules/` files (see table above)
4. For each match, records:
- Category name
- The matched phrase
- A 200-character excerpt surrounding the match
- The session file path
5. Also scans for novel patterns not covered by the five categories:
- Apologies: "I apologize", "sorry about that", "my mistake"
- Over-explaining: paragraphs > 500 chars that contain no code blocks
- Repeating user input: assistant restating what user said before acting
6. Outputs a JSON report to stdout
**Script requirements:**
- Use only Python stdlib (json, re, os, glob, sys, collections)
- Process files in parallel where possible
- Skip subagent session files
- Handle malformed JSON lines gracefully (skip them)
- Accept command-line args: `--days N` (default 7), `--project PATH` (optional filter)
### Step 3: Present Results
Format the analysis as a ranked report, inline in the response:
```
## Agent Guardrails Analysis Report
**Sessions scanned:** {count}
**Time range:** {oldest} to {newest}
**Total anti-pattern matches:** {total}
### Rankings (by frequency)
| # | Category | Matches | % of Total |
|---|----------|---------|------------|
| 1 | Guessing | 47 | 38% |
| 2 | Stalling | 28 | 23% |
| 3 | Preference-Asking | 21 | 17% |
| ... | ... | ... | ... |
### Category Details
#### 1. Guessing (47 matches)
**Top phrases:**
- "this should work" (12x)
- "I think" (9x)
- "probably" (8x)
**Example excerpts:**
> "...I think this change will fix the issue. The error was probably caused by..."
> "...this should work now. Let me know if..."
**Recommended rule:** Install via /agent-guardrails:install
---
[Continue for each category...]
```
### Step 4: Suggest Next Steps
After presenting the report, state which categories have the highest frequency and recommend running `/agent-guardrails:install` to install rules for them. Do not ask the user which ones they want — recommend based on the data.
## Important Notes
- Always show the report inline — never hide results behind a file path
- Include actual excerpts from the logs so the user can see real examples
- If a category has zero matches, still list it with 0 to show it was checked
- If novel patterns are found that don't fit the five categories, report them in a "Novel Patterns" section
- The analysis script runs locally — no data leaves the machine
Related in AI Agents
skill-development
IncludedComprehensive meta-skill for creating, managing, validating, auditing, and distributing Claude Code skills and slash commands (unified in v2.1.3+). Provides skill templates, creation workflows, validation patterns, audit checklists, naming conventions, YAML frontmatter guidance, progressive disclosure examples, and best practices lookup. Use when creating new skills, validating existing skills, auditing skill quality, understanding skill architecture, needing skill templates, learning about YAML frontmatter requirements, progressive disclosure patterns, tool restrictions (allowed-tools), skill composition, skill naming conventions, troubleshooting skill activation issues, creating custom slash commands, configuring command frontmatter, using command arguments ($ARGUMENTS, $1, $2), bash execution in commands, file references in commands, command namespacing, plugin commands, MCP slash commands, Skill tool configuration, or deciding between skills vs slash commands. Delegates to docs-management skill for official documentation.
reprompter
IncludedTransform messy prompts into well-structured, effective prompts — single or multi-agent. Use when: "reprompt", "reprompt this", "clean up this prompt", "structure my prompt", rough text needing XML tags and best practices, "reprompter teams", "repromptception", "run with quality", "smart run", "smart agents", multi-agent tasks, audits, parallel work, anything going to agent teams. Don't use when: simple Q&A, pure chat, immediate execution-only tasks. See "Don't Use When" section for details. Outputs: Structured XML/Markdown prompt, quality score (before/after), optional team brief + per-agent sub-prompts, agent team output files. Success criteria: Single mode quality score ≥ 7/10; Repromptception per-agent prompt quality score 8+/10; all required sections present, actionable and specific.
adaptive-compaction
IncludedAdaptive add-on policy and recovery layer that decides WHEN to compact, prune, snapshot, or fork -- replacing fixed-percent auto-compaction across Claude Code, Codex, and MCP-capable hosts. Trigger on auto-compact timing or damage: "when should I compact", "is it safe to compact now or start a fresh session", "auto-compact fires too early/mid-task", "switching to an unrelated task but the window still has space", "context rot", "answers get worse the longer the session runs", "the agent forgot the plan or my decisions after it summarized", "add a layer on top that manages context without changing the agent", raising autoCompactWindow to give the policy room, or installing/tuning a cross-tool compaction policy or PreCompact hook -- even when "compaction" is never said but the problem is context-window pressure or post-summarization memory loss. Do NOT use to summarize a conversation, build RAG, write a summarization prompt (decides WHEN not HOW), or answer max-context-length trivia.
agent-skill-creator
IncludedCreate cross-platform agent skills from workflow descriptions. Activates when users ask to create an agent, automate a repetitive workflow, create a custom skill, or need advanced agent creation. Triggers on phrases like create agent for, automate workflow, create skill for, every day I have to, daily I need to, turn process into agent, need to automate, create a cross-platform skill, validate this skill, export this skill, migrate this skill. Supports single skills, multi-agent suites, transcript processing, template-based creation, interactive configuration, cross-platform export, and spec validation.
llm-wiki
IncludedUse when building or maintaining a persistent personal knowledge base (second brain) in Obsidian where an LLM incrementally ingests sources, updates entity/concept pages, maintains cross-references, and keeps a synthesis current. Triggers include "second brain", "Obsidian wiki", "personal knowledge management", "ingest this paper/article/book", "build a research wiki", "compound knowledge", "Memex", or whenever the user wants knowledge to accumulate across sessions instead of being re-derived by RAG on every query.
skill-master
IncludedAgent Skills authoring, evaluation, and optimization. Create, edit, validate, benchmark, and improve skills following the agentskills.io specification. Use when designing SKILL.md files, structuring skill folders (references, scripts, assets), ingesting external documentation into skills, running trigger evals, benchmarking skill quality, optimizing descriptions, or performing blind A/B comparisons. Keywords: agentskills.io, SKILL.md, skill authoring, eval, benchmark, trigger optimization.