Agent Skills Are Becoming Architecture as Code

The previous article argued that agents should generate database migrations without owning production data. Agents can automate engineering work; irreversible decisions still need governance.

That raises a deeper question:

If coding agents implement large parts of an application, where does architectural knowledge live?

For a long time, the answer was documentation: diagrams, wiki pages, READMEs, ADRs, CI configuration, review checklists, and the memories of senior engineers.

Those sources remain useful. They are also fragmented, easy to overlook, and difficult for an agent to interpret consistently at the moment it needs to make a change.

Agent Skills, repository instructions, and focused project rules point to a different model: architecture becomes executable context.

Prompts do not scale

For a small task, a prompt can describe the expected pattern. A production repository carries more context than a prompt should hold:

folder and naming conventions;
dependency boundaries;
code-generation rules;
migration workflow;
testing strategy;
deployment process;
security constraints;
review requirements.

Eventually every request becomes “please remember…” followed by a miniature engineering handbook. The prompt becomes longer than the feature.

The problem is not that architecture is absent. It is that architecture is usually distributed.

README.md
Architecture.md
ADR/
CONTRIBUTING.md
CI configuration
Lint rules
Review checklist
Senior engineers

The final line is often the most important. Experienced engineers carry unwritten rules such as “do not expose persistence entities through a public API,” “do not put business logic in a widget,” or “review every destructive migration.”

Humans learn these patterns over time. Agents need them stated as procedure.

Agent Skills turn knowledge into usable procedure

Anthropic’s Agent Skills are organized directories of instructions, scripts, and resources that agents can discover and load for a relevant task. Rather than putting every rule into one permanent prompt, a project can offer composable knowledge for the work at hand.

That is substantially more useful than a general instruction such as:

Write clean, maintainable code.

A focused skill can say:

When a Flutter screen needs remote data:

1. Add a DTO at the infrastructure boundary.
2. Map it to a domain entity in the repository.
3. Keep networking inside the repository.
4. Deliver a ViewModel to presentation.
5. Never parse JSON in a widget.
6. Add the required unit and widget tests.

The first statement expresses a preference. The second describes a repeatable action.

This is architecture as code

Infrastructure made a similar transition.

Before: server setup → wiki → manual commands
Now:   Terraform → Git → review → deployment

Infrastructure became observable, versioned, and repeatable. Agent-facing architecture can follow the same pattern.

Instead of merely documenting that a repository pattern is recommended, a project can encode its boundaries, data-flow rules, validation commands, and tests. The agent can then reproduce that architecture across features instead of inventing a new structure for every prompt.

Serverpod 4 demonstrates the direction. Its project setup can include AGENTS.md, installed agent skills, editor-specific MCP configuration, generated code, and a development runtime that lets an agent build, run, and inspect the system. Serverpod’s 4.0 guide documents the installed skills and MCP servers; its project structure guide shows where those instructions and configurations live.

The technical stack is specific to Serverpod. The design lesson is not: “every product needs Serverpod.” It is: “the rules that make a project safe and coherent should live with the project.”

Consistency is the payoff

Without clear local rules, an agent can produce a plausible but different structure in each feature.

Feature A: repository → Cubit → DTO
Feature B: service → API → widget
Feature C: widget → direct HTTP call

Each implementation may work in isolation. The repository gradually drifts.

With focused skills, the same pattern can be applied repeatedly:

Feature A → repository → domain → presentation
Feature B → repository → domain → presentation
Feature C → repository → domain → presentation

That consistency reduces onboarding cost, narrows code review, and makes automated checks more useful.

The hidden danger is automated consistency

Skills amplify architecture. That is also their risk.

Imagine a rule that tells an agent to return database entities directly from every endpoint. An agent can apply that rule across hundreds of changes. The result will be coherent—and consistently wrong. It can leak internal fields, couple clients to persistence, and make future migrations harder.

Skills are not disposable documentation. They influence behavior at scale and deserve the same care as production code.

Skill change
      ↓
Pull request
      ↓
Architecture review
      ↓
Security review when relevant
      ↓
Merge and regression checks

The review should ask whether the rule has a clear scope, fits the current architecture, handles exceptions, and could introduce a security or data-boundary failure if repeated automatically.

Make architecture testable

Once architectural rules are explicit, parts of them can be validated in CI.

Widget imports repository directly        → fail
Generated file modified manually          → fail
Persistence entity used in public API     → warning or fail
Required migration test missing            → warning or fail

Not every architectural decision can or should become a lint rule. But checks make important constraints observable instead of relying only on reviewers remembering them.

This turns a vague question—“does the team follow clean architecture?”—into more concrete ones: “does this change violate a documented boundary?” and “does the validator catch it?”

Keep skills focused and composable

The most useful skills tend to have one responsibility. A repository might organize them around areas such as:

skills/
├── flutter-ui/
├── state-management/
├── serverpod-endpoints/
├── database-migrations/
├── offline-sync/
├── release-process/
└── ai-safety/

Each skill should cover a task-specific workflow, examples, scripts if necessary, and a clear verification step. A feature agent can then load the Flutter UI, endpoint, migration, and security skills it needs rather than consuming one enormous policy document.

High-value skills encode engineering decisions, not just personal formatting preferences:

domain models do not depend on Flutter;
database entities do not cross a public API boundary;
authorization runs before business logic;
secrets never reach client code;
migrations use an expand-and-contract plan when compatibility requires it;
high-impact changes require explicit approval.

Skills are also a security surface

Agent instructions, MCP configuration, tool descriptions, and reusable scripts can influence what an agent does. They must be treated as part of the system’s trust boundary.

The OWASP AI Agent Security Cheat Sheet recommends version-controlled adversarial tests and release gates after material changes to prompts, tools, policies, or retrieval. The OWASP Secure Coding with AI guidance also recommends auditing MCP servers, pinning or detecting tool-definition changes, and applying least privilege to a coding agent’s tools.

In practice, that means a skill should never quietly expand access to production credentials, payment systems, email, or unrestricted database operations. The architecture may be executable, but it must remain bounded.

The senior-engineer role changes, not disappears

Agent Skills do not eliminate the need for experienced engineers. They make a valuable part of that experience reusable.

The senior engineer of an AI-assisted team may spend less time repeating repository conventions and more time:

deciding which boundaries protect the product;
encoding those decisions as focused procedures;
reviewing how the rules evolve;
validating them against real failures;
defining the approval boundary for risky actions.

That is architecture work in its most leveraged form.

The important shift is not merely that agents can read architecture. It is that teams can structure architectural knowledge so humans and agents follow it consistently, review it openly, and verify it automatically.

Architecture is becoming a repository artifact. The teams that treat it that way will have a stronger foundation for both human and agentic engineering.