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/execution-continuity.md

Long-Running Tasks: State, Recovery, and Resources

Read for long-running, background, cross-session work, pauses, and recovery; in review, when such guarantees are claimed. Budget and scheduler sections also apply to competing sessions. Sections 1–4 cover checkpoint, handoff, resume, and testing; 5–9 cover storage, supervisor/RTO/RPO, budgets/breakers, asynchronous decisions, and scheduling. A one-off answer with no persistent state does not need this loop. Filenames below are examples, not a mandatory backend or OS.

1. Checkpoint Policy

Define what is saved → source of truth/writer → trigger → durable-write timing → consistency → permissible progress loss → recovery/failure → check.

Combine periodic time/step checkpoints with significant events: stage completion, accepted decision, human wait, worker handoff. Choose intervals by permissible work loss and save cost; fixed N/M values and context-window percentages are not universal. Asynchronous, on-exit, and before-continuation writes provide different guarantees. If storage is unavailable, specify whether this particular operation may continue.

A checkpoint links the goal and its version, tasks/dependencies, accepted decisions, method/input versions, artifact/evidence links, spending and open budget reservations, operation information, and the next permissible step. Authorization and external-effect status remain in the trusted runtime/owning system, not a compressed summary.

Several files or tables do not automatically form a consistent snapshot. Choose a transaction, versioned manifest/commit marker, or native checkpointer guarantee. The reader checks snapshot identity and completeness; a partially saved set cannot declare a stage complete. Returning to the previous complete snapshot does not undo later external effects: reconcile the operation log and budget first. For concurrent workers, define the write owner and protection against stale writers.

2. Session Handoff Protocol

Handoff must let the next session continue without reading the entire conversation or repeating a general interview.

Function	Sufficient content	Example representation
Environment restoration	Dependency/configuration versions, authorized preparation, tool/data availability checks	init.sh, PowerShell, image, or native bootstrap
Human-readable progress	Goal, accepted decisions and reasons, completed work, blockers/unknowns, next step	progress.md or a database-record view
Machine-readable tasks	Stable IDs, dependencies, state, completion criteria, result and related-operation links	feature-list.json, tasks table, native graph state
Verification package	Versioned pointer to outputs, checks, effects, and decisions	Evidence Bundle manifest under validation-loop.md

Do not duplicate authoritative state in independent inconsistent copies: the human view can derive from the same records. The package stores no secrets; bootstrap obtains them through an authorized environment and grants no new rights. An addressable file, actually loaded context, and correct continuation are separately verifiable states.

3. Resumption

Check snapshot integrity, user/tenant ownership, and current goal: cancellation, task changes, or agent disable may have happened after the checkpoint.
Restore compatible environment, method, and data versions or apply an explicitly authorized migration; do not silently substitute methods. Check required context availability/freshness.
Reconcile unfinished and ambiguous operations against authoritative state. A stable operation ID helps only with a known downstream deduplication/reconciliation contract. For unknown outcomes, retain uncertainty, choose permissible reconciliation or escalation, and do not blindly repeat effects.
Restore total spent/reserved budget and deadline. A new session or worker does not reset limits.
Before the next effect, recheck the exact action, current rights, approval, and agent lifecycle. Complete a permissible step and link the new checkpoint to evidence.

Populated transition and failure

Synthetic checkpoint C7: goal H1, input S3, method v2, report R4 is a draft, next task Q5 checks numbers; of a $5 budget, $2 spent and $0.50 reserved. A new session reads C7, verifies S3 freshness and task state, obtains available evidence, and continues Q5 accounting for $2.50 committed budget. It does not ask the goal again or declare a verified result before Q5.

Failure: after authorized publication op7, the response is lost; progress was saved for C8 but the task list stayed at C7. This set does not confirm completion. Recovery uses the latest consistent snapshot plus the op7 log; readback can establish publication and link its receipt to the result. If reconciliation is unavailable, state is “effect unknown,” and republishing is not automatically permitted. Expired approval does not prevent authorized reconciliation of an already started action, but authorizes no new write.

4. Continuation testing

For material transitions, design or safely perform stops before/after durable recording, after a sent effect, and during a partial snapshot. Start a new session using only the designated recovery mechanism. Check preservation of goal, constraints, method, versions, remaining tasks/budget; absence of duplicate effects and stale authority; correct next step and understandable user status.

The long-horizon matrix in evaluation-design.md distinguishes accumulated history, compaction, handoff, and crash/resume. A test design is not an executed runtime check. A local downstream fixture does not prove the real external API's guarantee.

5. Lifecycle-based storage

For large volumes or long retention, compare one durable backend with logical tiers: hot—low-latency active state; warm—recently completed/paused tasks; cold—archive based on cost and applicable rules. Three tiers are not mandatory; a task without storage needs none. A storage tier is not a trust level, and compressed model context does not replace a primary artifact.

Define object/source of truth → tier → transition event/time → owner → access/retention → retrieval latency/cost → check. Automatic migration uses stable IDs/versions and a verifiable manifest: copy and verify integrity → atomically switch address → remove previous copy under policy. Reads during migration must not mix versions; failure leaves the latest intact available version. Archive restoration (rehydration) has a waiting status, timeout, and missing/corrupt-object outcome. Transparency to the agent means preserving read contract and identity, not promising instant access.

ACL/tenant, encryption/key management, deletion deadlines, and applicable deletion holds apply to all tiers, replicas, and caches. Archive/backup restoration must not reinstate revoked rights or deleted data; specify checks of current policy and deletion records. Do not import universal legal retention periods. Rehydration cost/time count toward budget and recovery; a minimum kit for required RTO may remain in fast storage while other artifacts are archived.

6. Supervisor and recovery objectives

For automatic continuation, assign failure detection/recovery ownership to the existing runtime/orchestrator or proposed supervisor logic. A separate process or LLM is not mandatory. Contract: failure/lease-expiry signal → acquire recovery ownership with fencing → verified checkpoint and operation log → recovery under section 3 → health verification → requeue or stop. A late worker must not regain ownership. An already initiated external effect requires separate reconciliation even with functioning fencing.

Define RTO as target time from an explicitly chosen failure event to safe resumption of useful work; RPO as permissible loss of a specific state/progress class. Separate targets from measured values. Identify failure domain (worker, store, region), detection, recovery queue, bootstrap, rehydration, reconciliation, and verification: fast process restart does not prove RTO. Checkpoint interval alone does not prove RPO without durable-write/replication timing. Authorization, effect, and cost logs may need stronger durability than intermediate synthesis.

Automatic restart has attempt and total-time limits, backoff, error classification, and an exhausted-budget outcome. Corrupt/incompatible state, missing current rights, and unknown effects are not cured by endless restart. Describe supervisor/dependency failures and owner handoff; recovery does not bypass admission or receive a fresh budget.

Conflicting-requirements example: cold reads take 40 minutes, target RTO is 10 minutes, checkpoints every 15 minutes with a 3-minute progress RPO. The current design does not substantiate these targets. Options: fast recovery kit, more frequent durable recording/logging, or agreed objective changes; cost and measurements determine the choice. Design a real cold-resume and worker/store-loss test within the stated scope; measure lost progress and time to a safe useful step. A thought calculation merely exposes the conflict.

7. Budgets and circuit breakers

Under the general limits contract in architecture-contract.md, link task (whole assignment), session/run (attempt/interactive segment), and horizon (aggregate tenant/user quota per window). Specify currency/resource, ledger owner, window boundaries/type, accounting time, spent/reserved, atomic admission, reservation release, and exhaustion outcome. Levels are nested, not summed into extra available budget: a call passes all applicable limits. Handoff/restart/a new day does not reset the task limit; late costs and window-boundary operations are counted once under explicit policy. Delegates, retries, review/guardian, recovery, and retrieval count toward corresponding costs. Apply storage/CPU/network quotas for actual load.

Example: task limit $8, spent $5, reserved $1; tenant daily limit $60, spent $58, reserved $1. Task remaining $2, tenant remaining $1. Two workers cannot independently reserve $1 each from the same remainder; session remainder expands neither parent limit. A reservation with unknown spend is not released merely on timeout. At a day boundary, the reservation/charge window policy must preserve both limits without double-counting.

Distinguish exhausted budget, lack of progress, and a circuit breaker for a degraded dependency. For a breaker define signal/error-latency window, scope (tool/provider/tenant), closed/open/half-open transitions, cooldown, bounded recovery probe, and closure criterion. Automatic external-write probes are impermissible without ordinary authorization and safe retry contract; a read/health probe does not prove the write path healthy. Open pauses affected operations, records progress, and shows reason/next step; unaffected authorized actions may continue. Model switching/fallback requires compatible rights, data policy, quality checks, and total budget. Mandatory checks are not disabled for degradation.

8. Asynchronous human participation

Use the decision map from design.md: for background tasks define owner/backup recipient within authority, channel/availability windows, decision deadline, nonduplicate reminders, cancellation, timeout, and visible waiting status. The card includes goal, exact finite set of versions/actions, changes, grounds, risks, and decision options; a summary aids review but does not replace material evidence access. Batch approval binds every action/version; excluded or changed items do not inherit permission. Section 3's recheck applies before execution.

Do not occupy a compute worker waiting for a person. Persist state and resume on a decision event, protected from duplicate delivery and expiry. Silence is not agreement. At deadline: partial output, reschedule/cancel, or authorized escalation; human availability does not guarantee meeting a deadline. Measure queue/labor under evaluation-design.md. Interactive clarification and a background queue may share one UI but have explicit different deadlines/states. Guardian is risk-dependent, not mandatory; test it across task duration and accumulated context, and include cost in the total cap.

9. Scheduler and competing tasks

For multiple tasks/tenants, define admission/execution policy: interactive/background class, business criticality and assignment source, deadline/slack, quotas/concurrency, estimated cost/duration, preemption admissibility, tie-breaking, and starvation protection. The model does not raise its own priority. Interactivity is a policy factor, not unconditional precedence over critical background work. Choose FIFO, separate queues, weighted fairness, or reserved capacity by load; a separate service is unnecessary.

Define a bounded queue/backpressure, task-owner lease/fencing, shared budget, safe pause point, and cancellation consequences. Preempt at a safe checkpoint boundary; a sent operation is not considered canceled. Predicted deadline/budget violation triggers a concrete decision: defer/reject, narrow output under agreed policy, or escalate. Do not promise completion without capacity or derive authority from urgency.

Test mixed load: interactive surge, critical background task near deadline, noisy tenant, long indivisible operation, duplicate delivery, and worker loss. Measure queue/age, waiting/completion by class, missed deadlines, starvation, useful progress, and costs while preserving constraints. A queue or priority setting alone proves none of these. A one-off assistant without competition may need no scheduler.

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