Guide · Agent skill
How to use the Agent Architecture Audit agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Agent Architecture Audit is an agent skill for diagnosing applications built on LLMs or autonomous agent loops. It is for developers whose agent works in a playground but breaks inside their own wrapper, or whose agent has got worse after a recent change. After this guide you will know what the skill does, how to install it, how to ask for it in plain language, and what it needs before it can run.
Agent Architecture Auditaffaan-m/ECC · MIT Download the skill Quick start
- 1Download the skill ZIP. Get the ZIP for agent-architecture-audit from our page.
- 2Unzip into a skills folder. Unzip it into ~/.claude/skills/ for a personal install, or into your project's .claude/skills/ folder for a single project.
- 3Or upload it in the Claude apps. If you use the Claude apps, open Settings, then Capabilities, then Skills, and upload the skill.
- 4Install ripgrep. Make sure the rg command-line tool is available, because the audit's search commands rely on it.
- 5Describe the problem. Ask in plain language, naming the agent and the symptom, such as a regression after a prompt or memory change.
- 6Review the ranked findings. Check each finding's evidence references and confidence score, then work through the ordered fix plan.
What is an agent skill and what does this one make the agent do?
An agent skill is a folder containing a SKILL.md file that tells an AI coding agent how to handle a particular kind of task. When the skill is active, the agent follows its workflow instead of improvising.
This skill teaches the agent to act as a diagnostic auditor. It walks through a 12-layer model of an agent stack, from the system prompt and session history through tool selection, tool execution, output formatting, platform rendering, hidden retry loops and persistence. It then searches your codebase with grep-style patterns for risky designs and reports what it finds.
- Wrapper regressions: the base model is fine but your wrapper layer makes answers worse.
- Memory pollution: old topics or corrections leak into new conversations.
- Tool discipline failures: a prompt says to use a tool, but code does not enforce it, so the model skips it or claims a call it never made.
- Hidden repair loops: fallback or retry steps make a second LLM call that changes the answer silently.
- Rendering corruption: the internal answer is correct but the UI, API or CLI alters it on the way out.
How do you install the Agent Architecture Audit skill?
Download the ZIP for this skill from our page and unzip it. You can install it in one of two places. For a personal install that applies to all your projects, unzip it into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder.
If you use the Claude apps rather than a local setup, you can upload the skill instead. Open Settings, then Capabilities, then Skills, and upload the skill there.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside your project folder
- Claude apps: Settings → Capabilities → Skills
How do you trigger the skill with a natural request?
You do not need a special command. Describe the problem in ordinary words and mention the agent or the symptom. The skill is meant to be used when you are about to release an agent or LLM feature, when you add a prompt layer, tool definition or memory system, or when users report that the agent has got worse or that its tools are unreliable.
Good requests name the system and the symptom, and say when it started if you know. The source also asks for the scope to be defined: which system it is, how users reach it, which models it uses, what is being reported, the time window, and which layers are relevant.
- "Audit my agent before we release. It has tool calls, long-term memory and a multi-step workflow."
- "The agent got worse after we added a new system prompt layer last week. Audit the wrapper."
- "The same model works in the playground but breaks in our app. Find the wrapper regression."
- "Users say the agent keeps bringing up old topics. Check memory pollution in the codebase."
What does an audit look like and what does the output contain?
The audit collects evidence from source code such as the agent loop, tool router, memory intake and prompt assembly. It also reads logs, configuration such as prompt templates and tool schemas, and memory files. The skill uses rg (ripgrep) to search for anti-patterns, for example tool calls that are not validated or LLM calls outside the main loop. Here is one of the search patterns from the skill:
The findings are presented in severity order: critical, high, medium or low. Each finding lists the symptom, the mechanism, the source layer, the root cause, evidence as file:line or log:line references, and a confidence score from 0.0 to 1.0. The report ends with an ordered fix plan that puts enforcing rules in code ahead of editing prompt text.
- Findings ranked by severity, most important first
- Architecture diagnosis: which layer breaks what, and why
- Prioritised fix plan, code first rather than prompt first
rg "tool_call|toolCall|tool_use" --type py --type tsWhat do you need before running it, and what are the safety notes?
The audit depends on reading real files, so it needs access to the target agent codebase, its logs and its configuration files. Ripgrep (the rg command-line tool) must be available because the skill's search commands use it. The skill is allowed to use Read, Write, Edit, Bash, Grep and Glob.
Safety: according to the skill's metadata, it runs scripts, and it does not use the network. The skill's own notes also say it is not a security scanner. For vulnerability scanning it points you to security-review instead, so do not treat a clean audit as a security sign-off.
- Access to the agent codebase, logs and configuration
- ripgrep (rg) installed
- Runs scripts: yes
- Uses network: no
- Not a security audit: use security-review for that
What tips help you get useful results?
Give the skill the real symptom and a time window, not a guess at the cause. The skill itself warns against blaming the model before ruling out the wrapper layer, and against blaming memory without showing the path by which the contamination happened.
Check the findings' evidence references yourself. Each finding points to file:line or log:line, so you can confirm it before changing anything. For runtime problems such as loops, timeouts or state errors, the skill recommends agent-introspection-debugging instead.
- Start with the symptom and when it began.
- Ask for evidence references and confidence scores so you can verify each finding.
- For loops, timeouts or state errors, use agent-introspection-debugging.
- For benchmarking agent performance, the skill points to agent-eval.
What people use it for
- Pre-release review of an agent application that uses tool calls, memory and multi-step workflows.
- Investigating a regression after a new system prompt layer or wrapper was added.
- Finding why an agent that works in a playground fails inside your own app.
- Checking whether memory is leaking old topics or ignoring user corrections.
- Finding hidden fallback or retry steps that make a second LLM call.
Frequently asked questions
Is the Agent Architecture Audit skill free?
The skill's listing states the licence as MIT. The skill is provided as a ZIP download from our page, and you install it into your own Claude skills folder or upload it to the Claude apps.
What do I need to run the agent architecture audit?
You need access to the target agent codebase, its logs and its configuration files, plus the rg (ripgrep) command-line tool. The skill is allowed to use Read, Write, Edit, Bash, Grep and Glob.
Where do I install the agent-architecture-audit skill?
Unzip the downloaded ZIP into ~/.claude/skills/ for a personal install, or into .claude/skills/ inside a project for that project only. In the Claude apps, use Settings, then Capabilities, then Skills to upload it.
Can this skill find security vulnerabilities?
No. The skill does not perform a security audit. For that it points to security-review, so use that skill for vulnerability scanning.
How is this different from agent-introspection-debugging?
This skill audits architecture: wrapper regressions, memory pollution, tool discipline and hidden repair loops. The skill says runtime failures such as loops, timeouts and state errors belong to agent-introspection-debugging.
Why does the audit say to fix code before prompts?
The skill's default fix order puts enforcing tool requirements in code first, because prompt text alone does not stop a model from skipping a tool. Prompt edits come after the code-level fixes.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you are building an agent or LLM feature that behaves well in testing but breaks in your wrapper, or if you want a structured review before a production release. Pick something else if you need general debugging of runtime failures, a security scan, or benchmarks, or if you do not have access to the codebase, logs and configuration.
Download the skill