Your AI Agent Ships Features in Seconds. It Has Zero Architecture Judgment.


Last month I asked an agent to add a payments endpoint to a service. It did. The code ran, the tests passed, and it handled the happy path cleanly.


Two weeks later production started dropping requests under load. The endpoint opened a fresh database connection on every call. No retry, no timeout, no idempotency key. The agent had built exactly what I asked for, and none of what the system needed.


That gap is the whole problem. Agents are brilliant at writing code that works and blind to whether the code should exist, where it belongs, or what it quietly breaks.

A coding agent frantically stacking a collapsing tower of code on the left, and the same agent as a calm architect beside a solid structure on the right

The image above is the exact difference between "build it" and "architect it." I built a pack of skills to push agents from the left side to the right.

Why agents keep shipping the wrong thing


An agent optimizes for the prompt in front of it. Tell it to add a feature and it adds a feature. It has no instinct for trade-offs, no memory of your last incident, and no framework for choosing between two reasonable designs.


The failures are boring and predictable:

  • A new table for every new field instead of a schema that actually fits.
  • Secrets logged "for debugging" and pushed straight to the repo.
  • A service split along the wrong boundary, so every change touches five repos.
  • A cache added before anyone measured the bottleneck.

None of these are bugs. They are judgement calls, and judgement is the one thing the model does not bring into the session.

What I built instead of another chatbot


I did not want a tool that writes more code. I wanted to change what the agent considers before it writes any.


So I built a pack of 11 system-design skills that load into a coding agent the way a senior engineer's instincts would. Each skill is not a description of architecture. It is a set of behavioral instructions: a decision tree, a list of anti-patterns to refuse, and architecture prompts that force the agent to reason out loud.


The agent reads the skill, then designs. The skill never generates the solution. It shapes how the agent gets there.

A skill in practice


Take the database skill. The moment the agent reaches for a datastore, the skill walks it through a decision tree:

  • Read-heavy or write-heavy? That alone rules out half the options.
  • Do you need joins across aggregates, or is this key-value access?
  • What is the consistency requirement, and what breaks if it is eventually consistent?
  • Will this table hit a row-count wall in a year, or stay small forever?

Then it lists the anti-patterns: the N+1 query, the "NoSQL because it is modern" decision with no foreign keys, the UUID primary key on a hot table. The agent has to justify its choice against those before it writes a single migration.


That is the whole mechanism. A question list a good architect asks, encoded so the model asks it of itself.

The 11 skills


The pack covers the full arc, from first principles to production:

Foundations

  • Architecture principles: the non-negotiables (separation of concerns, least surprise, fail loud)
  • Architecture decision framework: how to pick between options and record why

Design

  • Database intelligence
  • API and domain architecture
  • Scalability and distributed systems

AI-specific

  • AI system architecture
  • Context engineering

Cross-cutting

  • Security by design
  • Codebase architecture
  • Production engineering

Meta

  • Architecture review: a scorecard the agent runs before calling the work done

Every skill follows the same shape. Decision tree first, anti-patterns second, architecture prompts third. Install the whole pack, or a single skill when a task only needs that one chapter.

The trade-off I had to make


I almost shipped this as one giant skill. One file, easier to install, done.


It was the wrong call. A single 5,000-token skill would load on every task and drown the agent in rules it did not need, just to add a button to a form. The Agent Skills format caps a file at roughly 5,000 tokens on purpose. So I split the pack into 11 focused skills, each small enough to load only when its trigger matches the task.


The cost is install weight. You get 11 folders instead of one. The agent only reads the one it needs, which is the point, but the bare install is heavier than I would like.


I am still deciding whether to add a thin router skill that installs nothing but an index, then lazy-installs each chapter on demand. It is cleaner on disk and keeps the first impression light. It also means the agent has to run the installer at runtime, which not every setup allows. If your agents can self-install, the router is better. If they cannot, the full pack is the safe default.

How to install it


The pack is open source under MIT. Install the whole thing:

npx skills add imadnan4/architect-skills

Or grab a single skill:

npx skills add imadnan4/architect-skills@database-intelligence

Once loaded, the agent picks the right skill from its description the next time a task touches that area. You do not trigger it by hand.


Source: github.com/imadnan4/architect-skills

FAQ


Does this replace an architect? No. It encodes the questions a good architect asks so the agent stops skipping them. The human still owns the decision.


Will it slow my agent down? Only when the task needs it. Each skill loads on its trigger, so a pure frontend tweak never pulls in the distributed-systems chapter.


Can I edit the skills? Yes. They are plain Markdown in the repo. Change the decision tree, add your own anti-patterns, commit.


Which agents support this? Any agent that reads the Agent Skills format, the skills/<name>/SKILL.md convention. That covers most current coding agents.

The part that actually changed my workflow


I still review the payments endpoint. I always will.


But now the agent shows up having already refused the connection-per-request design, already picked a key, already asked itself about idempotency. The review got shorter because the first draft got smarter.


That is the whole point of the pack. Not more code from the agent. Better first drafts, so the human spends time on the decision instead of the cleanup.


Built it, shipped it, and stopped re-reviewing the same mistakes. If your agent keeps shipping the wrong thing, it is one command away.