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/diagnostic-review.md

Failure Diagnosis and Fix Review

Apply to observed failures and regressions. For an unimplemented architecture, use the same questions as a paper scenario check: a risk forecast, not reproduction. This procedure refines the audit; it does not authorize agent changes or external actions. Perform available safe reads yourself; express unavailable tests as a concrete plan with expected outcomes.

1. Record the case and knowledge boundary

Build a brief card: task/acceptance criterion → expected result → actual result → input/material state → versions/recent changes → available events/artifacts → impact. Identify provenance: user report, inspected code, trace, executed check. Do not call a retold trace your own observation.

A brief retelling or prompt fragment does not prove the full instruction, skill, or another component lacks a domain method. Do not make its incompleteness a separate Important finding without confirming the real execution path. It is a hypothesis to check; record a demonstrated output/validator defect independently.

Record known failure count and total examined cases; do not extrapolate available traces to others. Separately check that “successful” cases really meet the domain criterion. No trace means cause unknown; it does not yet prove system-wide absence of logging.

Build a short chain from externally observable data: input → selected method and actually loaded context → tool request/response → transformations → saved output → check → user response. Find the first observable discrepancy. Error origin may be earlier; downstream emptiness and the validator that missed it may be separate defects. Do not require hidden model chain of thought.

Minimize the example while preserving failure conditions: context length, event order, tenant/rights, versions, concurrency, retry/resume, external-service state. Failure disappearing after shortening is trigger evidence, not proof of poor task definition. Do not dismiss a single critical failure as noise; two repetitions do not prove cause. Plan probabilistic repeats proportionately to risk and available budget.

2. Select the layer and competing explanations

The table gives search directions, not ready-made diagnoses. A symptom can span layers; the model may also be a cause or interaction participant.

Layer	Discriminating check
Goal and domain method	Do user requirement, acceptance criterion, and actually selected procedure agree? Does it cover the needed capability?
Instructions and context	What was available, found, selected, truncated, and actually sent to the model? Compare before/after assembly, including version/access scope
State and continuation	Which checkpoint was read, what restored, did decisions/version/rights change; what happens after crash/redelivery?
Tools and environment	Do parameters match the task, access/data match expectations, raw response match adapter output; are emptiness, pagination, and domain errors inside HTTP 200 handled?
Model and orchestration	With correct input, is the output contract violated; do routing, stopping, retries, and quality change in controlled comparison?
Validation and success reporting	Is the domain output/external effect checked, does the real path traverse control, can it reject a plausible wrong answer?
Observability	Can versions, events, and output be linked to one run without secrets; where exactly does evidence break?
Metric and incentives	Does useful output improve or only score/self-assessment; are there hidden errors, rework, failures on independent cases?
Measurement system	How many tasks executed/evaluated; were difficult cases lost through runner, judge/parser, or reducer; do dataset/grader versions match?
Delegation and integration	Did the recipient see goal, constraints, versions, and total remaining budget; does received artifact match integrated output, preserving grounds/conflicts?
Accumulation and cost	What grows between sessions: loaded context, stale rules, rework, history/caches; does measurement confirm the growth source?

For a significant unclear cause, usually choose 2–4 plausible hypotheses, not every table row. Format: hypothesis → evidence for/against → remaining unknown → minimal discriminating check → outcome supporting or weakening it. A demonstrated defect needs no artificial alternatives. Choose the next read/test by explanatory discrimination, risk, and cost, not a familiar stack.

For context loss, check cold start or resume: from actually available and loaded materials, the agent reconstructs goal/user, work/validation method, current progress/next step, current decisions, and completion criterion. Adapt specifics to the domain: linter commands matter for a coding agent, not every agent. Compare source → addressability/access → loader selection → assembled context → observed answer. A file's existence does not prove loading; a wrong answer does not prove the file absent. The fix may be in reading path, freshness, or model.

3. Check the check itself

Use validation-loop.md for completion/checker contracts; execution-continuity.md for consistent snapshots/handoff. Select additional discriminating cases by observed symptom:

Symptom	Comparison and permissible conclusion
All stages done, no benefit	Requirement fulfillment, initial value hypothesis, baseline, measurement window. Bad framing, absent effect, and insufficient data are different outcomes
Human exhausted or agent waits forever	Labeled necessary/unnecessary requests, completeness of decision materials, human availability, input flow. Distinguish agent behavior from queue overload
Complete document package gives false success	Output/check versions and content, effect state, missing/error/unknown handling. Manifest completeness does not prove relevant evidence
Long session degrades	Fresh session, accumulated history, compaction, handoff, and crash separately; ensure minimization retained the trigger
Progress files exist, continuation is wrong	Authoritative records → checkpoint identity/integrity → loader → actually supplied context → next step. Distinguish partial writes, bad loading, and bad decisions
Controller denies after writing	Verdict timing relative to effect, reachable pre-action controls, controller unavailability handling; do not credit an observer with prevention
Rights change after recovery	Exact action, current principal/tenant/resource/parameters/approval; a new session does not inherit permission from a summary
Disabled agent keeps acting	Trigger source: endpoint/cron/queue/retry/worker; effect start versus disable timing. Distinguish a late receipt for an old action from a new prohibited action
Archival makes continuation slow/wrong	Rehydration latency, migration IDs/versions/integrity, current ACL/deletions, fast recovery kit. Do not confuse unavailable archive with model error
Process restarted, promised recovery absent	Claimed RTO/RPO scope/start point, detection/queue/load/reconciliation time, actual durable-progress loss; checkpoint interval is not RPO measurement
Restarts spend money or exceed total limit	task/session/horizon linkage, reservations/late costs at window boundaries, concurrent admission, restart bounds, breaker state
Chat is fast, background tasks never finish	Load/priority configuration, tenant quotas, queue age, deadline, starvation, safe preemption; separate resource waiting from a stuck agent
Batch decision lost or overauthorizes	Event ID, exact version/action list, changed items, expiry/redelivery; human waiting must not occupy a worker or grant authority automatically

For a fix review, reproduce the affected transition and a permitted control case. Correcting “done” reporting does not close the wrong-result cause; successfully stopping new tasks does not prove the fate of sent operations.

Storage, supervisor, budget, asynchronous-decision, and scheduling contracts are in sections 5–9 of execution-continuity.md. No separate service is not a finding when another component demonstrably performs the function. Diagnose mechanisms using actual configurations/traces; “environment matters more than model” does not exclude a model or interaction defect.

Trace requirement → checked result → source of truth → real validator/gate → negative-result handling → user status/response. Distinguish: no check; check not run; run on another path; unable to distinguish right/wrong; result ignored; stale artifact checked. A CI file, hook, or lint command proves neither execution nor substantive coverage.

For quality claims, apply evaluation-design.md: mandatory admission, valid alternative trajectories, measurement failures, coverage, comparability. A rising score with falling coverage does not prove agent improvement. For execution controls, check timing and covered paths under section 3 of architecture-contract.md: a check may run correctly but too late; a checkpoint may save state while permitting a repeated external action. Diagnosis names the violated obligation and mechanism, not just a missing component.

For a material criterion, provide a correct example and a plausible wrong one: wrong period, empty data, another tenant, nonexistent link, incomplete output with done=true. The check must distinguish them on independent grounds. A negative control must traverse the same gate/path under investigation; running a separate linter against an artificial error does not prove the production gate works. Intentional defects belong only in an authorized isolated copy/fixture; otherwise propose the test without executing it.

Model self-assessment and HTTP 200 do not certify outcomes. Programmatic postconditions check formalizable properties; a human may assess meaning/domain usefulness against an explicit rubric and source data. An LLM judge likewise needs validation on labeled good/bad cases and false-accept/reject measurement. A separate judge, E2E, or one overall score does not replace every evidence type. Check whether the agent can substitute criteria, test data, or final status to obtain green checks.

4. Design comparison and minimal correction

First separate cause localization from containing already demonstrated harm. Preventing false success is needed even while the reason for empty analytics remains unknown. It does not close data-loss cause. Correct the established mechanism; new memory, graph, judge agent, or model needs a testable benefit hypothesis and comparison with a simpler option.

For comparison, fix baseline version, tasks, state/data/tool responses, criteria, settings, and limits. Change one factor; when model and context assembler change together, compare all four combinations where possible to expose interaction. Stubbed tool responses localize downstream behavior but do not test correct request construction or live integration. Record that limit. Without the old baseline, do not confidently attribute regression to a component.

Disabling a component is a supporting hypothesis experiment. No change may mean redundancy, nonuse, or a weak sample; deterioration shows contribution under those conditions, not automatically the system's main bottleneck. Do not disable real ACLs, approvals, cost limits, or other mandatory controls for diagnosis. Do not propose removing them based on a few ordinary successful tasks; an accepted contract and relevant-boundary checks are needed.

Compare domain correctness, false success/refusal, user effort, time, and completed-task cost. Retain previously successful regression cases and independent cases outside tuning. Do not impose a universal run count or mandatory model replacement as the final step: evidence, impact, and check cost determine order.

5. Change review and completion

For each significant correction, check: does it close the established causal link → on every affected path including bypass/resume → without weakening mandatory controls → what proves closure → which result requires rollback. Separate cause removal, consequence containment, and additional observability. Label owners and numerical thresholds proposed until agreed.

The report must enable action now: a confirmed defect/minimal correction or the next discriminating check with expected outcomes. Statuses: confirmed / refuted under checked conditions / hypothesis / check unavailable. For fix reviews distinguish designed / implemented according to code / behavior-verified; an experiment plan is not its result. Do not promise the whole regression resolved when only false success reporting was closed.

Stop when significant findings have evidence, a closure plan, or a precise gap with the minimum next check. Do not visit every layer for completeness or keep experimenting without a new discriminating question. Limit follow-up review to prior findings and changed paths; broader reconsideration requires new material evidence, not leftover checklist items.

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