Skip to main content
skill CX Codex

agent-architecture-analysis — Claude Code skill: 12-Factor agent audit

agent-architecture-analysis audits an LLM agent codebase against the 12-Factor Agents rubric, then scores each factor and points at the files behind the score.

Apache-2.0 220 installs ★ 89 updated 2026-09-15

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add existential-birds/beagle --skill agent-architecture-analysis -a claude-code
Open on GitHub

What agent-architecture-analysis does

Point the skill at a codebase_path and it walks the project through the 12-Factor Agents methodology: 13 factors, from schema-validated tool calls to stateless reducers and context fetched ahead of time. The run is ordered. Pattern search first, then reading the files it turned up, then a gap analysis and fixes with code samples.

The rubric sits in references/factors.md — the principle, the search patterns to run, the Strong/Partial/Weak thresholds, the anti-patterns. Output is a summary table plus a per-factor write-up with file:line citations. No evidence, no score: a factor whose targeted search comes back empty defaults to Weak.

codebase_path is required; docs_path is optional and takes earlier analyses. The code path is not negotiable — without it there is nothing to read, so start from the repo root.

What it helps with

  • check how an agent emits tool calls and whether schemas are validated
  • find prompts hardcoded in source instead of versioned templates
  • tell whether a run can pause and resume later
  • turn audit findings into a ranked list of fixes
  • compare two agent frameworks against one rubric

Example prompts for the agent

  • Analyze the agent architecture under ./src, start with factors 1–5
  • Run a 12-factor audit on this repo and give me the summary table
  • How compliant is this LLM app? Cite files and line ranges

How to install agent-architecture-analysis

1Skills CLI (Vercel)

npx skills add existential-birds/beagle --skill agent-architecture-analysis -a claude-code

2Manually: put the files in place

~/.claude/skills/agent-architecture-analysis/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/agent-architecture-analysis/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about agent-architecture-analysis

How do I install agent-architecture-analysis in Claude Code?

Run npx skills add existential-birds/beagle --skill agent-architecture-analysis -a claude-code. The skill file lands at ~/.claude/skills/agent-architecture-analysis/SKILL.md.

What does agent-architecture-analysis do?

It reviews an agent codebase against the 13 factors of 12-Factor Agents and rates each one Strong, Partial or Weak. Every rating comes with a code citation and a line reference.

Does it work on any language or framework?

It reads the codebase by search patterns and file paths rather than by stack, so the analysis follows whatever files sit under codebase_path. Prompts, tool schemas and control flow are what it looks for.

Source text

SKILL.md · Apache-2.0
---
name: agent-architecture-analysis
description: "Use when auditing an agent codebase against the 12-Factor Agents methodology, reviewing LLM-powered system architecture, or assessing agentic app compliance. Triggers on \"analyze agent architecture\", \"12-factor audit\", \"how compliant is this agent\", or \"evaluate this LLM app\". Also applies when comparing frameworks or planning agent improvements. Not for quick checklists \u2014 this performs deep per-factor codebase analysis with file-level evidence."
---

# 12-Factor Agents Compliance Analysis

> Reference: [12-Factor Agents](https://github.com/humanlayer/12-factor-agents)

## Input Parameters

| Parameter | Description | Required |
|-----------|-------------|----------|
| `docs_path` | Path to documentation directory (for existing analyses) | Optional |
| `codebase_path` | Root path of the codebase to analyze | Required |

## Analysis Framework

The full per-factor rubric — principle, search patterns, file patterns, compliance criteria (Strong/Partial/Weak), and anti-patterns for each of the 13 factors — lives in [references/factors.md](references/factors.md). During the [Analysis Workflow](#analysis-workflow), read the relevant factor sections there for the search patterns to run and the criteria to score against.

| # | Factor | Focus |
|---|--------|-------|
| 1 | Natural Language to Tool Calls | Schema-validated structured outputs from LLM |
| 2 | Own Your Prompts | Prompts as first-class, versioned, templated code |
| 3 | Own Your Context Window | Custom formatting of history/state/tool results |
| 4 | Tools Are Structured Outputs | Validated JSON triggers deterministic code |
| 5 | Unify Execution State | Single state object merging execution + business state |
| 6 | Launch/Pause/Resume | APIs to launch, pause anywhere, resume |
| 7 | Contact Humans with Tools | Human contact as a structured tool call |
| 8 | Own Your Control Flow | Custom routing/retries, not framework defaults |
| 9 | Compact Errors into Context | Errors fed back for self-healing + escalation |
| 10 | Small, Focused Agents | Narrow responsibility, 3-10 steps each |
| 11 | Trigger from Anywhere | CLI/REST/WebSocket/chat/webhook entry points |
| 12 | Stateless Reducer | Pure `(state, input) -> (state, output)` agents |
| 13 | Pre-fetch Context | Fetch likely-needed data upfront |

See [references/factors.md](references/factors.md) for the complete rubric for every factor above.

---

## Output Format

**Gate order:** Do not assign Strong / Partial / Weak or treat recommendations as observed facts until **Hard gates** (after [Analysis Workflow](#analysis-workflow)) are satisfied for the factors in scope.

### Executive Summary Table

```markdown
| Factor | Status | Notes |
|--------|--------|-------|
| 1. Natural Language -> Tool Calls | **Strong/Partial/Weak** | [Key finding] |
| 2. Own Your Prompts | **Strong/Partial/Weak** | [Key finding] |
| ... | ... | ... |
| 13. Pre-fetch Context | **Strong/Partial/Weak** | [Key finding] |

**Overall**: X Strong, Y Partial, Z Weak
```

### Per-Factor Analysis

For each factor, provide:

1. **Current Implementation**
   - Evidence with file:line references
   - Code snippets showing patterns

2. **Compliance Level**
   - Strong/Partial/Weak with justification

3. **Gaps**
   - What's missing vs. 12-Factor ideal

4. **Recommendations**
   - Actionable improvements with code examples

---

## Analysis Workflow

1. **Initial Scan**
   - Run search patterns for all factors
   - Identify key files for each factor
   - Note any existing compliance documentation

2. **Deep Dive** (per factor)
   - Read identified files
   - Evaluate against compliance criteria
   - Document evidence with file paths

3. **Gap Analysis**
   - Compare current vs. 12-Factor ideal
   - Identify anti-patterns present
   - Prioritize by impact

4. **Recommendations**
   - Provide actionable improvements
   - Include before/after code examples
   - Reference roadmap if exists

5. **Summary**
   - Compile executive summary table
   - Highlight strengths and critical gaps
   - Suggest priority order for improvements

---

## Hard gates (evidence before scores)

Run these in order. Do not skip ahead: each **Pass** is an objective condition you can check (paths on disk, citations present), not internal certainty.

1. **Scan gate** — After the initial scan (workflow step 1), **Pass:** for every factor (1–13) you have either (a) ≥1 repo-relative path or glob hit to inspect, or (b) a one-line note with rationale (e.g. search command/output, or “no matches — codebase may omit this concern”). Empty hand-waving (“looks fine”) fails this gate.
2. **Evidence gate (per factor)** — Before writing Strong / Partial / Weak for that factor, **Pass:** “Current Implementation” includes ≥1 citation with **file path** plus **line range or short quoted snippet** from `codebase_path`, or an explicit **no evidence located** statement after targeted reads. If evidence is missing after search, default that factor to **Weak** unless the criterion is clearly N/A (say why).
3. **Synthesis gate** — Executive summary table and per-factor analysis sections, **Pass:** only after gates 1–2 are satisfied for the factors in scope. Recommendations may name new files or patterns only as proposals; they must not be presented as observed facts without matching citations from step 2.

---

## Quick Reference: Compliance Scoring

| Score | Meaning | Action |
|-------|---------|--------|
| **Strong** | Fully implements principle | Maintain, minor optimizations |
| **Partial** | Some implementation, significant gaps | Planned improvements |
| **Weak** | Minimal or no implementation | High priority for roadmap |

## When to Use This Skill

- Evaluating new LLM-powered systems
- Reviewing agent architecture decisions
- Auditing production agentic applications
- Planning improvements to existing agents
- Comparing frameworks or implementations

© existential-birds · Apache-2.0 · existential-birds/beagle

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set68

The whole set →
review-verification-protocol review-verification-protocol — a skill that enforces verification before any code review finding enters the report: read the source freshly, search for context, distinguish bugs from style. Cuts false positives. CX Codex +1 252installs pytest-code-review pytest-code-review reviews pytest test files for async patterns, fixture scopes, parametrization, and mock targets. Catches unawaited coroutines and broken patch paths before CI runs. CX Codex +1 239installs sqlalchemy-code-review sqlalchemy-code-review reviews SQLAlchemy code for session, relationship, query, and migration issues. Use it when checking SQLAlchemy 2.0 or Alembic changes. CX Codex +1 228installs pydantic-ai-common-pitfalls pydantic-ai-common-pitfalls walks through the mistakes that break PydanticAI agents and gives a fixed order for debugging: tool decorators, deps, output schemas, streaming. CX Codex +1 221installs pydantic-ai-agent-creation The pydantic-ai-agent-creation skill guides PydanticAI agent setup with typed dependencies, validated outputs, and model configuration. Use it when building agents or chat systems. CX Codex +1 219installs ai-elements A skill for Claude Code, Codex, Cursor, Copilot, Gemini CLI and OpenCode: helps build chat interfaces, job queues, tool execution displays and approval workflows. Triggers on ai-elements, Queue, Tool, Confirmation, Message, PromptInput. CX Codex +1 211installs go-code-review go-code-review — a Go review skill that reads go.mod first, then checks errors, goroutines, interfaces and cleanup, ranking each finding by severity. CX Codex +1 206installs shadcn-code-review shadcn-code-review audits React components built with shadcn/ui, Radix primitives, and Tailwind CSS. Catches CVA mistakes, broken asChild slots, and missing accessibility states. CX Codex +1 206installs

Project sponsors

Companies that keep this analytics open