How to use the agent-architecture skill: design or audit AI agents

What does the agent-architecture skill make the assistant do?

The skill has two modes. In design mode, the assistant interviews you about requirements, then recommends an architecture: which components are needed, how the flow runs, where rules must be enforced in code rather than left to the model, and how to verify the design. In audit mode, it reviews an agent that already exists and diagnoses architectural flaws such as mistakes, degradation over time, or tasks reported as finished when they are not.

The skill deliberately does not write the agent's code. It delivers architectural decisions, assumptions and open questions. By default, completed work includes a PDF report and a visualization of the results.

• Design: requirements discovery, then a recommended architecture.
• Audit: reconstructs the actual paths of an existing agent, verifies them, and reports findings.
• Diagnosis: for agents that make mistakes, degrade, or falsely report done, it works through the case, hypotheses, discriminating checks, and a closure criterion.
• It favours the simplest design that fits the task, and it considers ordinary automation without an LLM, a single model call, or a predefined workflow before any agent loop.

Install the agent-architecture skill

Download the skill as a ZIP from the page you are reading. Then choose one of two routes.

For a personal install, unzip it into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder. The unzipped folder should contain SKILL.md at its top level along with the references folder.

In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/
• Project: .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

How do you trigger the skill with a natural request?

You do not need a special command. Describe what you want in plain language. For a new agent, say what the agent should handle and that you want the architecture worked out before anything is built. For an existing agent, say that you want it reviewed, or that it makes mistakes, has got worse, or reports tasks as done when they are not.

The assistant will then show you a route and ask questions one decision at a time. It does not require a fixed number of answers, and it will deliver a first sketch early, no later than the third answer when context allows.

• Design example: "I want an agent that triages support emails. Help me decide on the architecture before I build it."
• Audit example: "Review my existing research agent. Sometimes it reports a task as finished when the output is incomplete."
• Stop signal: phrases such as "enough questions" or "let's go with this for now" tell it to deliver the architecture from what it already knows.

What do you get as output?

A finished design or audit includes the goal and boundaries, main capabilities, recommended components, the main flow and any external actions, key constraints, assumptions, and open decisions. Every item is labelled by status, such as source-confirmed, user requirement, proposal, assumption, open question, or not applicable, so you can see which points came from you and which came from the assistant.

Because the skill does not implement anything, the output is a set of decisions and verification methods that you or your team carry into the build.

• Requirements and their sources
• Chosen architecture type and reasons
• Where rules are enforced in code before an external effect
• Verification and completion criteria
• Open questions and owners

What does the skill need and what are the safety notes?

The skill needs a runtime that supports SKILL.md-compatible skills. Because the PDF report and visualization are part of the default output, you may need a runtime that can generate PDFs. The skill does not run scripts and does not use the network.

Its safety rules are about the agent you are reviewing. During an audit it reads specifications and code to reconstruct the architecture, but it does not run an application that has external effects. An audit or design also does not authorise writing code, changing agent settings, publishing, or starting external actions. If you later ask for implementation, the skill hands the accepted architecture to a suitable process rather than building it itself.

• Runs scripts: no
• Uses network: no
• Does not run live applications with external effects during an audit
• Does not write code or change agent settings

Tips for getting a useful result

Bring the material you already have: existing specifications, local instructions, architectural decisions, and any agent code. The skill reads these first and only asks about gaps. Tell it what failure would cost you, because the ideal architecture depends on requirements, cost of failure, and team resources, not on the number of components.

Expect it to push back on complexity. If a single model call or plain automation can do the job, it will say so. Answer its questions about real exceptions and human work, since these change the design.

• Share existing specs and code before describing them from memory.
• State what a wrong result would cost.
• Name who will own and check the agent.
• Ask for a sketch only if you want an early look; otherwise ask for the full package.