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://mp-staging.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/design.md

Step-by-Step Design

1. Understand the task

Read supplied documents and available context. First record:

who uses the system, what work they do today, and what should improve;
known constraints, accepted decisions, and the business-rule owner;
what already exists, what data is available, and where the source of truth is;
unknowns that change safety, boundaries, cost, or execution approach.

If almost no request detail exists, start with one real case: “Who comes to the agent, with what, and what result do they consider successfully completed work?” Do not start by choosing a database, model, or tool list.

2. Conduct an adaptive interview

Follow discovery-protocol.md: visible stages, one substantive question, a coverage map, and separate readiness statuses. The following table is a reference for choosing the next material gap, not a queue of mandatory questions. Begin with the desired change and latest real case; an early design does not end investigation. A topic may be “not applicable” with a reason.

Topic	What to discover and helpful questions	Decision depending on the answer
User and value	Who is the user, customer, and rule owner? How is the task solved now? Where are losses? What changes after adoption?	Whether AI is needed at all, product boundaries, baseline
Scenarios and output	Work through real ordinary, difficult, and prohibited cases. What is the input? What is a good output? Who accepts it?	Output contract and acceptance scenarios
Errors and priorities	Which errors are unpleasant versus unacceptable? In conflict, what matters more: accuracy, completeness, speed, cost, autonomy?	Quality criteria, escalation, control level
Domain and boundaries	Terms, entities, lifecycle, rules, legitimate exceptions. Which neighboring tasks are excluded? Who changes rules?	Domain invariants, owners, dependencies
Authority	Read, propose, save a draft, or execute? On whose behalf? Which actions need a human, and what exactly do they confirm?	Action matrix and authorization policy
Human participation	Who is available, when, how quickly? How to cancel, correct, reject, continue? What happens overnight or on approval expiry?	Real rather than nominal escalation
Context and knowledge	Which data is mandatory for a decision? Where is it, who owns it, how often does it change? Which sources take precedence and how are conflicts handled?	Direct API, search, RAG, context assembly
Examples and data rights	Are authorized examples of inputs, answers, and wrong answers available? Labels, de-identification, languages, formats, volume, access restrictions?	Testable hypotheses, corpus, evaluation set
Memory	What must be remembered within a task, across sessions, across users? Who may write, correct, delete? How to distinguish opinion from fact?	Need and lifecycle of each memory type
Tools	Which systems/operations are actually needed? API contracts, owners, errors, limits, permissible retries, effect verification?	Adapter and tool boundaries
Load and interaction	Chat, event, schedule, batch? Peak concurrency, task duration, streaming, waits, redelivery?	Sync/async, queue, state, backpressure
Nonfunctional requirements	Target latency/availability, budget per accepted task and period, quotas, expected growth? What can be simplified?	Limits, capacity, economics
Confidentiality and trust	Whose data, which tenants, who can see what? External documents, files, personal data, allowed providers/regions, retention/deletion?	Trust boundaries, isolation, secrets, leaks
Operations	Who supports, investigates, rolls back? Team skills and existing stack? How to change model, rules, tools, sources?	Solution size, observability, release
First-scope feasibility	Pilot deadline, people actually available to build/support, permissible spending? Clarify separately by impact; route “unknown” to an owner	Pilot scope, available dependencies, resource-validation plan, handoff blockers

After an answer, first determine whether to deliver or update the design under SKILL.md. If interviewing is still needed, briefly state what is now known and which decision the next question unlocks. Do not require technical terminology from the user: learn desired behavior and translate it into architecture. Do not transfer internal mechanism selection to the customer when the architect can make a justified proposal.

3. Form testable requirements

This and subsequent sections describe the architect's work on the deliverable. Do not make the user fill them in for you. Clarify material gaps using discovery-protocol.md; independently develop technical proposals and verify available sources.

Separate mandatory from desirable. A small agent needs a few end-to-end criteria; a complex project needs a compact set with measurable outcomes.

Develop the acceptance contract using evaluation-design.md, including mandatory gates and measurement coverage.

Populate a value card: problem → baseline → expected change → measurement → observation period → owner → reconsideration condition. Value may be nonfinancial. Link it to domain capabilities; correctly completed work, demonstrated benefit, and insufficient evidence to evaluate benefit are different outcomes. State what would falsify the hypothesis and which decision follows under the accepted policy; unconfirmed benefit does not require automatic rollback. Do not turn the card into another questionnaire or mandatory PRFAQ.

Example: the agent prepared a correct report, MAU grew 10%, but prices and acquisition channels also changed. The calculation is confirmed; the experiment's causal contribution is not established. A suitable comparison method and observation period are needed; a negative or inconclusive research result can be a useful task outcome.

For significant human decisions, map: decision → owner → evidence/options → exact confirmation → wait deadline → no-response behavior. Estimate queue volume and available human time. If the agent prepares 100 items and the owner has 30 minutes, propose prioritization, incoming-flow limits, or permissible batch review of specific versions; faster generation does not imply a faster whole process. Evaluate necessary and unnecessary escalation quality under evaluation-design.md.

Decompose “99% quality”: success definition, denominator, allowable errors, categories/languages, automation proportion, labeler, dataset, and measurement period. Accuracy on answered requests alone can hide widespread refusal. Model confidence self-assessment does not replace a calibrated criterion.

Separate:

domain rules checked against authoritative state, with explicit exceptions;
heuristics and quality judgments requiring examples, measurements, and error tolerance;
unconfirmed targets that remain proposals.

Do not portray a proposed metric, budget, or SLA as a user requirement. When information is insufficient, explain what can be designed conditionally and what cannot be considered implementation-ready.

4. Compare architectural options

Read architecture-selection.md and populate a task-proportionate selection card: baseline, plausible alternatives, benefit/cost, validation, reconsideration condition. Develop delegation and long-running interaction contracts only when present.

Specific branches:

Knowledge: request data, direct API, full-text search, RAG; behavioral fine-tuning does not replace fresh authoritative facts. A vector database is not an admission requirement.
Memory: task state and conversation history are not long-term knowledge. “Unnecessary” is valid for each type.
MCP: useful as an integration boundary for appropriate clients/systems; a few stable functions may need only ordinary calls. The protocol grants no authority itself.
Service topology: separate a process/service for an actual responsibility, isolation, or scaling boundary. Agent count does not determine microservice count.
Model: first capability, data, format, cost, latency, and fallback requirements. Then a shortlist with current sources and a comparison plan using identical scenarios and surrounding runtime.

5. Design domain capabilities

Read capability-design.md. Convert main user scenarios into a capability map, responsibility allocation, and specifications of needed skills. Describe the work method, context-selection rules, and output examples. This is the architect's work from gathered requirements, not another customer questionnaire.

For the chosen platform, separate confirmed existing mechanisms from configuration, new skills/integrations, and unverified capabilities. If the method requires domain expertise, propose it with explicit status and domain-owner validation; do not replace missing knowledge with a confident prompt.

6. Describe and check the design

Use architecture-contract.md to populate and validate the design. An early sketch permits open details; a completed package must meet that contract's substantive readiness criteria. Show one populated ordinary scenario from input to output and one material failure: intermediate data, capability selection, capability output, control, and user outcome. Without real data, use an explicitly synthetic example; do not call a tabletop walkthrough an executed run. Ensure components, diagrams, and contracts describe one system.

Check traceability both ways: each requirement has a decision and acceptance method; each component has a need or mandatory control. Remove unused proposed components and retain accepted tradeoffs.

At the end, separately state knowledge, agreement, and handoff status under discovery-protocol.md. Do not automatically proceed to code or promise future-system quality before measurement.

Format the completed result under result-delivery.md: architecture PDF, rendered diagram of the proposed agent, editable text, and diagram source. This is part of design delivery; no separate export request is needed.

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-08

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