Agent Architecture

GitHubOfficialCreated by Stanislav BankovskiiDistributed by GitHub

Skill
Research and analysis
Agent tooling
MIT
No issues found

From the author

Design AI agent architectures through requirements discovery, or audit and diagnose architectural flaws in existing agents. Architecture only; excludes implementation and general code review.

— the description by Stanislav Bankovskii

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a systematic approach to defining the architecture of AI agents or auditing existing ones. It focuses on requirements discovery, structural integrity, and operational reliability, ensuring that agent designs are justified by specific needs rather than unnecessary complexity. It delivers comprehensive architectural packages, including diagrams and validation plans, without performing implementation or code-level reviews.

What it does

Designs new agent architectures based on clear requirements discovery.
Audits existing agent architectures to identify flaws and verify paths.
Diagnoses performance issues or failures in agent logic.
Produces architectural reports including Mermaid or C4 diagrams.
Defines validation loops, state management, and execution contracts.
Evaluates the necessity of complex components like RAG, memory, or multi-agent systems.

When to use it

When you need to design an AI agent from scratch and want a justified, efficient architecture.
When an existing agent is failing, producing errors, or not meeting performance goals.
When you need to verify if your current agent design is robust and scalable.
When you need to document an agent's architecture for stakeholders or developers.

Advantages

Promotes architectural simplicity by requiring justification for every added component.
Provides evidence-based audits rather than subjective assessments.
Ensures clear boundaries between agent logic, tools, and external effects.
Delivers professional, ready-to-use architectural documentation and diagrams.
Focuses on verifiable outcomes and robust error handling.

Usage examples

“I need to design an agent that handles customer support tickets. Can you help me define the architecture?”: The agent will guide you through a discovery process to define requirements, select the appropriate topology, and deliver an architecture package including diagrams and validation rules.
“My current agent keeps getting stuck in a loop when searching for data. Can you audit it?”: The agent will reconstruct the current execution paths, identify the root cause of the loop, and propose a corrected architectural approach with diagnostic checks.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/github/agent-architecture/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip agent-architecture.zip -d .agents/skills

Documentation by Stanislav Bankovskii

AI Agent Architecture

Help the user obtain a justified architecture for their task or an evidence-based audit of an existing agent. Deliver architectural decisions and ways to verify them, without implementing the agent. By default, completed work includes a PDF report and a visualization of the results. An “ideal architecture” fits the requirements, cost of failure, and team resources; it does not maximize the number of components.

Choose a route

Request	Route	Read
New agent, requirements are not yet clear	Design: working cases → early design → requirements and decision coverage → delivery	design.md, architecture-contract.md
Architecture from an existing specification	Design: fill in what is known and clarify only gaps	The same files; do not restart the interview
Review an agent already written	Audit: reconstruct actual paths → verify → deliver findings	audit.md, and architecture-contract.md as criteria
Agent makes mistakes, has degraded, or falsely reports “done”	Diagnosis within the audit: case → hypotheses → discriminating checks → correction and closure criterion	audit.md and diagnostic-review.md
Review and redesign	Audit first; its demonstrated problems become design inputs	audit.md first, then design.md

In either mode, read source-map.md once: it explains the origins of the principles and the textbook's limitations. The original PDF is not needed for ordinary skill use. scenarios.md is needed only to test the skill itself.

When choosing or revisiting the execution approach, use architecture-selection.md; when designing acceptance or reviewing quality claims, use evaluation-design.md. Develop the validation loop and completion evidence using validation-loop.md; for long-running/background work, pauses, recovery, and competing sessions, use execution-continuity.md, including storage, RTO/RPO, budgets, the human decision queue, and scheduling. Develop delegation, mutable memory, execution isolation, and long-running/streaming interaction only when the task has these properties. A section's existence does not make its question mandatory: material gaps under discovery-protocol.md determine depth.

Shared decision rules

First read the available specification, local instructions, architectural decisions, and relevant materials. Use code to reconstruct architecture, not to make unsolicited fixes. Do not run an application with external effects for an audit.
Maintain a brief register: source-confirmed / user requirement / proposal / assumption / open question / not applicable. Identify where requirements came from. A user decision and an architect's hypothesis have different statuses.
Corporate contracts and accepted decisions apply only within their own project. The textbook is an engineering reference, not a source of authority or a replacement for local canon. Identify conflicts rather than resolving them silently.
First consider ordinary automation without an LLM, a single call, and a predefined workflow. Introduce an agent loop, RAG, persistent memory, MCP, or multiple agents only for a concrete need. For each added complexity, identify its benefit, cost, verification method, and simpler alternative.
Do not select a model or framework before understanding the task. For a concrete selection, check current official documentation and version constraints. A documented capability is not yet demonstrated quality on the user's data.
Separate probabilistic model decisions from programmatically enforced rules. Describe where permissions, parameters, budget, and action admissibility are checked before an external effect, including bypass paths and resumption.
For a timed-out external write, a readback that finds nothing does not by itself prove that no effect occurred. Permit a retry only under an established downstream idempotency contract or authoritative proof of non-execution; otherwise retain effect unknown and reconcile or escalate. Apply this rule in concrete flows and examples as well as in the risk section.
An audit or design does not authorize writing code, changing agent settings, publishing, or initiating external actions. On a subsequent explicit implementation request, hand the architecture to the appropriate process; this skill does not continue into implementation itself.

How to work

Before an interview or audit planning, read discovery-protocol.md. Show a clear route and maintain a coverage map. By default, devote each turn to one decision or working episode; do not hide several independent topics inside one question. Material gaps and evidence determine depth. There is no fixed total round limit.

Deliver the first useful design as soon as context is sufficient, otherwise no later than the third answer; the count does not reset on continuation. This limits the wait for an early result, not the completeness of the interview. If the task is too unclear, show a map of what is understood and conditional options. After the sketch, continue investigating material gaps under the protocol; two or three rounds alone do not justify declaring readiness.

The first design includes the goal and boundaries, main capabilities and their outputs, recommended components, main flow and external actions, key constraints, assumptions, and open decisions. It is a sketch for early feedback. The interview budget limits the wait for a sketch, not design depth: develop it into an architecture package from what is already known, without waiting for a separate instruction to elaborate. If context suffices, deliver the package immediately. If the user explicitly asks only for a sketch, respect and label that depth.

Phrases such as “that's enough,” “let's go with this for now,” “the rest later,” or “enough questions” end requirements gathering: deliver the architecture from accumulated context in the same answer. Do not require a separate “now design it” instruction or end at “interview complete.” If a design has already been delivered, show its current final version or a substantive update. An explicit request to stop all work (“don't continue,” “that's all for today, stop”) means stop, rather than deliver a new design.

If the user does not know an answer, propose a justified option and label its status. Represent unknowns as assumptions and open decisions. Unclear authority blocks the corresponding external action in the proposed architecture, but not delivery of the architecture itself. Silence and ending the interview do not approve proposals.

After a significant answer, update the working summary of requirements and decisions. Save it in an agreed document if artifact creation is within the request; otherwise maintain it in the conversation. On continuation, start with that summary and changed information.

After the first design, clarify specific branches and uncovered material requirements, including real exceptions, human work, and feasibility. Explain which decision the answer will change; propose internal mechanisms yourself. Do not confine gap discovery to components already drawn or restart a questionnaire. Finish when the declared scope has sufficient coverage; if further confirmation is unavailable, deliver a conditional package with owners and checks for gaps.

Complete design with the architecture package from architecture-contract.md: domain capabilities and methods, output contracts, the structure of instructions/skills/materials, allocation between the existing platform and additions, a populated end-to-end example, and checks. Read capability-design.md for this part; in an audit, use it to check required capabilities. Describe the agent's main work deeply enough that a developer does not have to invent its method again. A platform name and a list of stages do not accomplish that.

Always cover limits on iterations, time, tokens/money, and tool calls, stopping rules, and what the user receives on stopping. Mark unknown values as open or proposed rather than inventing an agreed limit. An architecture package with skill specifications remains a design: it does not imply skill installation, code implementation, or verification of a running agent.

Complete an audit with demonstrated problems, separately identifying unknowns and accepted tradeoffs. Do not claim production readiness from reading code. Architectural readiness for implementation and demonstrated operational quality are different outcomes.

Final artifacts

When completing design, audit, or diagnosis, read result-delivery.md and create a PDF of the results with a rendered Mermaid or C4 diagram as appropriate; retain editable text and diagram source. Do this as part of completion without a separate user request to “make the PDF now.” An early sketch and intermediate answers do not require repeated export. Explicit user constraints (“chat only,” “no files/PDF”) and a request to stop all work take precedence. Creating the report does not authorize implementing or changing the reviewed agent.

Package metadata

This package is distributed under the MIT license. Optional client metadata supports compatible Agent Skills clients; Copilot uses SKILL.md and the linked references.

Files

ATTRIBUTION.mdAdded by AutoGineer982 B
LICENSE.txt1.1 KiB
SKILL.md9.8 KiB
agents/openai.yaml309 B
references/architecture-contract.md20.3 KiB
references/architecture-selection.md7.3 KiB
references/audit.md9.5 KiB
references/capability-design.md6.1 KiB
references/design.md10.2 KiB
references/diagnostic-review.md13.0 KiB
references/discovery-protocol.md8.6 KiB
references/evaluation-design.md7.5 KiB
references/execution-continuity.md13.4 KiB
references/result-delivery.md7.4 KiB
references/scenarios.md24.7 KiB
references/source-map.md18.4 KiB
references/validation-loop.md6.8 KiB

references/source-map.md

Skill Foundations and Transfer Boundaries

Addition: work discovery and architecture handoff

Reviewed kotlyar/agent-architecture-builder, snapshot d3e5570cef4f01adc142aa478f3967b7bf165fec (MIT). Basis: SKILL.md and references/discovery-interview.md, architecture-decisions.md, control-interface-and-storage.md, delivery-package.md under skills/hermes-agent-builder. This is an idea source, not evidence of interview effectiveness or a particular runtime's readiness.

Adapted: moving from desired change to real episodes/functions; one substantive question; visible progress and sufficiency conditions; separate selection of method/tool/temporary worker/persistent boundary; independent justification of control interface/storage; verifiable implementation handoff. These are developed in discovery-protocol.md, architecture-selection.md, and result-delivery.md.

Not transferred: mandatory Hermes package/installer/ZIP, fixed frontend stack, prohibition of useful early designs before a complete interview, or universal profile/orchestrator admission formulas. This skill designs different agent classes, including stateless agents and simple workflows; an external service may own state. Decision factors, not platform restrictions, were adopted. New wording was synthesized; upstream code/templates were not copied.

Additional grounds are observations from a Jira/Pipeline role test: overloaded compound questions, implicit operator interface, missing brief owner page, consequences of proposed limits, and unverified pilot feasibility. They define regression scenarios, but one synthetic test does not prove universal quality.

Source

“Инженерия AI-агентов и ремесло разработчика” (“AI Agent Engineering and the Developer's Craft”), 2026, a textbook based on Dmitry Bereznitsky's channel. Supplied file: Учебник-AI-агенты-и-ремесло-разработчика_1.pdf (“Textbook—AI Agents and the Developer's Craft”), 287 PDF pages. SHA-256: 441f1c37a6b42bcae2bf10ce4c130a6f34271f930e67f6b90338437a4256fe73.

In this version, printed page n corresponds to PDF page n+1. The textbook is an editorial reworking of 32 videos with automatically obtained transcripts, not a normative standard or API reference (printed pp. 10–12; PDF 11–13). Video map: printed pp. 284–286; PDF 285–287. Do not assume the edition or specific figures current without verification.

The skill is self-contained: the following preserves synthesized principles and provenance, not a book copy. If original verification is needed, locate the supplied PDF; its absence does not prevent using the procedure but prevents confirming new quotations.

Origins of decisions

Textbook basis	Printed / PDF pages	Use
Ch. 1–4: LLMs, context, knowledge, model selection	15–40 / 16–41	Context as a limited resource; model/knowledge-access selection by task and measurement
Ch. 5: anatomy, pattern ladder, loop, tools	43–50 / 44–51	Start simple; separate workflow from dynamic model choice; explicit loop limits and pre-effect checks
Ch. 6: memory lifecycle and knowledge provenance	51–58 / 52–59	Separate memory types, source, and derived summary; account for conflicts, staleness, concurrency, poisoning
Ch. 7: constrain, inform, verify, correct; seven harness layers	59–66 / 60–67	Runtime, tools, context, lifecycle, observability, verification, governance as coverage map; constraints outside prompts
Ch. 8–9: tools, MCP, multiple agents	67–79 / 68–80	Domain tool contracts; justify protocol/coordination rather than mandatory multi-agent systems
Ch. 10: safety, failure, observability	80–92 / 81–93	Action policy, idempotency, operation-specific degradation, action outcomes, cost per task
Ch. 11–13: research, design, AI-work verification	95–116 / 96–117	Separate facts, architecture, implementation; architectural views “what / how / why / how to verify”
Ch. 14–18: architecture and domain	119–151 / 120–152	Responsibility/ownership boundaries, invariants, proportionate distribution/abstraction
Ch. 19–21: SOLID and code quality	153–171 / 154–172	Changeability/clarity as context; do not turn the skill into a style linter
Ch. 22–23: security and MCP	174–188 / 175–189	Untrusted tool descriptions/data, least privilege, observed real effects
Appendix B.1, B.3, B.5	266–269, 272–274, 277–279 / 267–270, 273–275, 278–280	Architecture, domain, operations, security coverage checks

Career, burnout, job-interview, and post-quantum migration chapters are not mandatory agent checks: they are outside the two declared modes. The adaptive interview gathers product needs, not the interlocutor's competency assessment.

What is this skill's original synthesis

Design/audit modes, interview sequence, provenance-bearing requirements register, R→D→E links, finding format, “defect / unknown / inapplicable” distinction, stopping criteria, and readiness statuses were developed for the user's request. The textbook supplies technical foundations but not a ready complete customer-needs discovery process.

Parameter/expiry-bound approval detail, design-readiness versus production-readiness, revoked ACL checks in indexes/caches, and post-crash behavior are engineering operationalizations, not the textbook author's verbatim requirements.

Caveats and corrections

Example numbers are not standards. 40–50% of the window, ten steps, tool counts, mandatory 20→3–5 reranking results, latency, and prices depend on model/task. Use as testable hypotheses if relevant at all. Numerical architectural limits need status and grounds.
No universal subsystem set exists. Four memory types are a taxonomy, not a requirement for four stores. RAG, reranker, graph, model router, ensemble guards, semantic-loop detector, MCP, and separate services need justification. Existing runtime or owning API may enforce controls.
Memory and canon. “Wiki is only a cache,” append-only, and a single writer are shared-memory architecture options. Do not apply automatically to every wiki, transactional database, or authored document. Version control prevents lost updates but does not resolve semantic conflicts itself. Recording a business effect and background recording of an optional memory are different operations.
Invariants. Define within domain/policy-version boundaries. A check may depend on authoritative state, time, and explicit exceptions without becoming probabilistic. Do not literally import “anything changeable or having exceptions must not live in code.”
Security. Printed p. 90 (PDF 91) incorrectly says Excessive Agency is outside OWASP Top 10. In the 2025 edition it is LLM06. A classifier does not prevent every injection or replace permission checks. A local/open-source MCP server does not prove safety.
Scores and cases. Book incident stories, attack rates, savings, and comparative percentages are not evidence of a specific implementation's quality/risk. Audits rely on reachable paths and project requirements.

Verified primary materials

Read on 2026-09-08; recheck changing APIs, versions, and policies for concrete designs. These refine principles without adding a mandatory stack.

Anthropic — Building effective agents: predefined workflow versus model-selected next steps, simple solutions, feedback, stopping conditions. The article itself notes changing tooling; its product list is not adopted as current skill recommendations.
OWASP — LLM06:2025 Excessive Agency: confirms the classification correction; authority controls belong outside LLM decisions and may live in the owning system/tool.
AWS Builders’ Library — Making retries safe with idempotent APIs: client intent identifier, server retry-processing guarantee, parameter binding, key retention. A client-side key alone does not remove effect ambiguity.

Addition: capability structure and Harness_ru

Analyzed on 2026-09-09: Harness_ru, revision 91750c0337f449bad1764d0e2b813ce9f8d8f2b1. This course mainly concerns coding agents; it is supplementary material, not a universal standard. Modules 4–5, 8–11, 13–14 contributed addressable instructions, continuation from external state, result confirmation, and feedback. Scripts/templates are not included in the skill.

Capability specifications, the “without new domain design” criterion, and sketch/package distinction are original synthesis for the user's request. Detail does not require more agents, services, or files. Primary materials read on 2026-09-09:

Anthropic — Equipping agents for the real world with Agent Skills: packaging procedural expertise and loading material on demand.
Agent Skills — Specification: package structure as a possible implementation format, not a separate-package requirement for every capability.
Anthropic — Effective context engineering: context selection, on-demand loading, preserving material state.
Anthropic — Effective harnesses for long-running agents: cross-session artifacts/verifiable progress; adapt software-development examples to domain.
Anthropic — Demystifying evals for AI agents: outcome/interaction checks, combined programmatic/model/human evaluation; successful scenarios remain regressions.

Not transferred: universal numerical thresholds, repository as the only possible source of truth, mandatory graphs/separate LLM evaluators, or static checks equated with agent quality. Independent evaluation is useful according to risk but gives no guarantee. Executing JSON commands through eval is not a recommended trust boundary. Do not remove permission checks or known critical regressions merely because a small sample passes without them.

Addition: diagnosis and review

The README's “How to fix an agent: diagnostic protocol” section and Harness_ru modules 1–2 were rechecked on 2026-09-09 at the same revision. Layered investigation, cold-start context-loading checks, check sensitivity, and component comparisons were adapted into diagnostic-review.md. Case cards, competing hypotheses, failure-condition preservation, cause/consequence separation, and fix review operationalize them for this skill.

Not accepted as rules: “one symptom—one layer,” two repeats as cause proof, mandatory file-based fixes, human evaluation as no checking, a single E2E as sufficient proof, or the model as an almost impossible cause. Module 2 already calls zero deterioration after disabling ambiguous; that more precise caveat is preserved. Repair durations and “model always last” are not normative. Source diagnostic scripts are neither run nor transferred; negative controls must check the actual project gate, not just a separate tool.

Addition: general architecture and measurement

Research on 2026-09-09/10 covered 21 repositories and 34 primary materials. Principles were transferred, not popularity rankings, a ready stack, or library settings. Sources below directly support changes A1–A10; card schemas/applicability boundaries are original synthesis. A pinned snapshot evidences that version's behavior; recheck current APIs and product defaults during design.

Addition	Primary basis	Transfer and limitation
A1: topology selection	Scaling Agent Systems, 12-Factor Agents	Task properties and aggregate-budget comparison; external benefit thresholds are not normative
A2: evaluation axes/gates	tau2 evaluation, AgentDojo task contracts	Separate outcomes/actions/constraints; AgentDojo security=True means attack success, so verify metric direction
A3: measurement reliability	Inspect scoring policy, tau2 grading changes, Anthropic evals	Omissions, denominator, versions, repeatability; reducer/NaN semantics are tool-specific
A4: tools as a selection interface	Writing effective tools	Domain semantics, distinguishability, completeness/output volume; no mandatory wrapper per endpoint
A5: exact execution guarantees	Agents SDK guardrails, LangGraph checkpointers, mini-swe-agent DefaultAgent	Control scope/timing, durability/replay, budget overshoot from started calls; SDK defaults are not norms
A6: delegation	MAST v3, Multiagent patterns	Handoff/integration contract; a failure taxonomy does not prove a specific failure's cause
A7: procedure evolution	Hermes, Letta Code	Separate experience recording from behavior admission; runtime self-change capability does not prove improvement
A8: isolation	smolagents secure execution	Code/tool/process isolation boundary; virtual filesystems/filters are not a full security boundary
A9: interaction	Pydantic deferred tools	Conversation/task/run, pause/continue; cancellation/correction/streaming contracts synthesized from product needs
A10: controlled improvement	GEPA adapter, GEPA paper	Component-targeted feedback, protected evaluation/comparison; no mandatory optimizer or authority to change criteria

Do not transfer code, universal bash, mandatory multiple agents, or publication of new procedures without authority. Library examples illustrate mechanisms; applicability, configuration, and quality need separate evidence.

Addition: AI-Disrupt PDLC—validation and continuation

User-supplied documents studied on 2026-09-10: whitepaper_full_ru.pdf (175 pages; SHA-256 5e1aeccece8567d2f0db14b5f6f2f6626086ccc86f8f1f0e159fdd039237d3ba) and whitepaper_short_ru.pdf (44 pages; SHA-256 374ae1fbc5875ba107d6fd4574ad90120608b5914257896045e5aa42653bc87d). The short version presents the same AI-Disrupt PDLC concept, not independent confirmation of the full one. Numbers below are PDF pages; full-version printed numbers are four lower. Key short-version tables were visually checked because Cyrillic extraction was incorrect.

Source section	PDF pages	Transfer
Outcome hypothesis and human decision map	full 36–44; short 14	Value card, substantive human participation, execution/effect distinction
Validation loop and Evidence Bundle	full 52–54	Seven functions, evidence linkage, verifiable completion contract in validation-loop.md
Compaction, checkpoint, handoff, long sessions	full 48–53, 84; short 21	execution-continuity.md and transition matrix; storage format selected by environment
4.2 “Environment matters more than model”: environment functions, isolation, long tasks, capacity	full 80–87 (printed 76–83)	Four functions and integration/enforcement separation; hot/warm/cold, supervisor/RTO/RPO, task/session/horizon, breaker, asynchronous decisions, scheduler. Migration, fairness, fencing, window-boundary, and test contracts are adaptations, not verbatim source guarantees
Contextual authority, ADLC, Guardian	full 96–105, 135; short 24, 31–32	Concrete-operation admission, controller verification, composite version, retirement
Validation pace and measurement distortion	full 53–55, 133–135	Review queue, human labor, score comparability; no fixed investment ratio

This is an enterprise software-development concept, not a universal agent standard. Contract schemas, adaptation to noncoding tasks, version-bound evidence, snapshot consistency, and late-event checks are this skill's engineering synthesis. Seven functions do not mean seven services; four handoff functions do not mandate init.sh/progress.md/feature-list.json on every OS.

Do not transfer section 4.2's harness code share, zero side effects, fixed RTO/RPO, three physical storage tiers, mandatory Kubernetes/Redis/explanation LLM, or unconditional interactive priority as guarantees. Environment design does not exclude model errors; accepted policy defines priority, and real paths establish recovery/safety. Moving to cold storage does not automatically satisfy applicable retention rules.

Not accepted as norms: arithmetic R0–R5 ladder; mandatory multiple agents/LLM reviewer; native APIs always more reliable than MCP; fixed evaluation-pass/compaction percentages and time budgets; automatic fine-tuning on drift; security guarantees from a hook/sandbox; legal retention/residency periods without applicability checks. Whitepaper business forecasts, risk probabilities, and relative improvements do not prove a particular agent's outcome.

Requirements and compatibility

Written for: GitHub Copilot

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

Stanislav Bankovskii

Publisher

GitHub (Official)

Distributed by

GitHub

Source

github/awesome-copilot · skills/agent-architecture · commit 797337f

Licence

MIT License (redistribution allowed)

ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-09

AutoGineer is not affiliated with or endorsed by Stanislav Bankovskii or GitHub.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download agent-architecture.zip