I Was Tired of Writing the Same Design Docs From Scratch, So I Built a Skill Library for It

Every time I started a new feature, I went through the same routine. Open a blank doc. Try to remember what sections a proper technical spec needs. Copy an old ADR template from a previous project and strip out the parts that don't apply. Realize halfway through that I forgot to think about rollback steps, or access control, or what happens when the thing fails at 3 AM.

None of this is hard work. It is just repetitive, and repetitive work is exactly the kind of thing that gets skipped when you are in a hurry. And skipping it is how you end up shipping a feature with no threat model, no rollback plan, and no one on the team quite sure why a decision was made six months later.

So I built engineering-docs. It is a set of 21 skills for coding agents that cover the full lifecycle of writing software, from the first fuzzy idea to the postmortem after something breaks in production.

The actual problem I was solving

I work across a few different projects at once, things like OwnPay, a self-hosted payment gateway, and a couple of security tools. Every one of them needs the same kind of documentation:

• A spec before you build.
• An architecture doc once the shape of the system is clear.
• A threat model before anything touches money or user data.
• A deployment plan before you push to production.
• A postmortem when something goes wrong, because something always eventually goes wrong.

I know how to write all of these. That was never the issue. The issue was doing it consistently, every single time, without cutting corners because I was tired or the deadline was close.

And when I started leaning on AI coding agents for more of my daily work, I noticed they had the exact same problem I did. Ask an agent to "design the database for this feature" and you will usually get a handful of CREATE TABLE statements with no thought given to indexing strategy, migration rollback, or why a particular normalization choice was made. Ask it to draft an API and you get endpoints with no error contract, no versioning strategy, nothing about rate limiting.

The agent is not being lazy. It just does not know that a real system architecture document has a specific shape, or that a good threat model follows STRIDE, or that a proper API design references the Richardson Maturity Model. That knowledge lives in the head of whoever taught it, and most of the time nobody taught it anything at all. It is just pattern matching on whatever half-finished specs happen to be common in its training data.

So the fix was not "write better prompts every time." The fix was to encode the actual structure of good engineering documentation into something the agent could load and follow automatically, the same way a junior engineer eventually internalizes the format after seeing enough good examples from a senior engineer.

What is actually inside

The repo has 21 skills, and they are grouped into five phases that roughly match how a real project moves from idea to production.

Discovery and planning

This is where you start when you only have a rough idea. There is a skill for building out user personas with actual jobs-to-be-done and success metrics, not the generic "Sarah, 32, busy professional" placeholder personas that show up in every template. There is also a project plan skill for milestones, a RACI matrix, and a work breakdown structure.

Specification and feasibility

Before anyone writes code, there is a skill that produces a proper Software Requirements Specification following ISO/IEC/IEEE 29148, using EARS syntax for the actual requirements. There is also a feasibility study skill, so you can sanity check whether an idea is realistic before committing resources to it.

Architecture and product design

This is the biggest group, and it is where most of the day-to-day value shows up for me.

• System architecture using the C4 model.
• Database design with real ERDs and a proper data dictionary down to indexes and cascade rules.
• API design aligned to OpenAPI 3.1, with RFC 7807 error handling instead of made-up error shapes.
• Architecture Decision Records, written the way ADRs are supposed to be written: immutable once accepted, with alternatives and trade-offs actually spelled out instead of just the final decision.

Risk and quality

• A threat model skill using STRIDE and OWASP, which is the part that catches the security gaps I would otherwise only notice during a security audit.
• A test strategy document.
• An implementation plan that orders the work by dependency instead of just listing tasks.

Deployment and operations

• Deployment plans with explicit go and no-go gates, not just "deploy on Friday and hope."
• SLO and error budget documents.
• Runbooks in the format Google's SRE teams use, connecting alerts to diagnosis to escalation.
• A disaster recovery plan with actual RTO and RPO targets.
• And a blameless postmortem skill using the Five Whys method, because the point of a postmortem is to fix the system, not to find someone to blame.

There is also an orchestrator skill called using-engineering-docs that sits on top of all of this. You describe a raw idea to it, and it interviews you with a handful of targeted questions, figures out which of the 21 skills actually apply, and sequences them in the right order. You do not have to remember which skill to reach for. It figures that out from the conversation.

Why it interviews you before writing anything

This part matters more than it sounds like it should. The skills do not just generate a document the moment you ask for one. They ask three to five clarifying questions first, the same way a good senior engineer would push back on a vague ticket before writing any code.

If you ask for a database design and you have not said anything about expected read and write volume, it asks. If you ask for an API design and have not mentioned whether this needs to support mobile clients with unreliable connections, it asks.

When there genuinely is a gap that cannot be resolved through a question, the doc gets an explicit marker for it instead of a made-up answer. Assumptions get flagged with 🔶 and open questions get flagged with 🔵, right in the document, so anyone reading it later knows exactly which parts were confirmed and which parts still need a decision.

I added that after noticing how often AI-generated docs read as confident and complete while actually being full of quiet, unstated assumptions. A document that pretends to have all the answers is more dangerous than one that honestly marks what it does not know yet.

Getting it running

If you want to try it, the fastest way is:

npx engineering-docs

It detects your environment and asks which agent harness you are using. Right now that covers Claude Code, Cursor and Windsurf, Kimi Code, Codex and GitHub Copilot, and Gemini through Antigravity. Each one gets its own manifest format, since Cursor expects .mdc rule files and Claude Code expects a plugin structure, but you do not need to know any of that going in.

For Claude Code specifically, you can also register it as a plugin marketplace directly:

/plugin marketplace add fattain-naime/engineering-docs
/plugin install engineering-docs@engineering-docs

There are also plain shell and PowerShell scripts in the repo if you would rather skip npx entirely and see exactly what gets copied where.

One small thing I was careful about: the install process never overwrites AGENTS.md, GEMINI.md, or CLAUDE.md if you already have one. If those files exist at the destination, the installer just skips them and logs that it did. I did not want a global install command quietly wiping out someone's existing agent configuration.

Why skills instead of one giant prompt

I could have written this as one long system prompt that tries to cover every kind of document. I tried that first, actually, and it did not work well. A single prompt trying to hold the format for an ADR, a database design doc, and an incident postmortem all at once either gets too vague to be useful or so long that the agent starts ignoring parts of it.

Splitting it into 21 separate, focused skills that auto-trigger based on what you are actually asking for keeps each one sharp. The database design skill only has to be good at database design. It does not need to also know the format for a disaster recovery plan. And because they are composable, the orchestrator skill can pull in exactly the ones a given project needs instead of forcing every project through the same fixed checklist.

What I would still like to add

The skills library is not finished, and I do not think it ever really will be in the sense of being "done." Software engineering practice keeps evolving, and a couple of areas I want to build out next are more depth on data pipeline and ETL design, and a skill specifically for migration planning when you are moving off legacy infrastructure, which is a problem I run into constantly with clients still running on old shared hosting setups.

If you try it and hit a gap, or you think a skill is missing something a real senior engineer would ask about, open an issue or a PR. The contributing guide covers how the YAML frontmatter and coaching blocks are structured, so adding a new skill is mostly a matter of following the existing pattern rather than reverse engineering it from scratch.

• Repository: github.com/fattain-naime/engineering-docs
• License: MIT

If you have ever shipped a feature and realized three weeks later that nobody actually wrote down why a decision was made, this might save you from doing that again.