🗂️ My Agent Skill Tree

In my last post I went through the whole setup I direct coding agents through, and the knowledge layer got a section of its own. It is the part of that system I get asked about most, and a section was not really enough for it.

A workflow can say that the security phase comes after the build phase and before the deploy. It cannot say what a good security pass looks like in this repository, or which of the six things I have already decided about database access are still true. That has to live somewhere, and for a long time it lived in whatever I remembered to paste into the prompt.

Why it lives in files

A coding agent does the work, and it does the work confidently against conventions I settled two years ago and never wrote down. The output compiles, the tests pass, and the shape is wrong in a way that only shows up three weeks later when someone else has to extend it.

So the knowledge moved out of my head and into files. Thirty-two domain folders now, each one a short entry file that says when to use it and when not to, plus a reference/ directory holding the real material: conventions, checklists, playbooks, and the decisions that are already settled and should not be relitigated. There are around 1,450 of those reference documents at the moment.

Thirty-three of them

Thirty-two domains, and one router sitting above them whose entire job is to not do the work.

corco  ·  the router
│
├─ build
│  ├─ dev              conventions, debugging
│  ├─ review           reports, release calls
│  ├─ qa               a11y, SEO, performance
│  ├─ security         threats, hardening
│  ├─ infrastructure   deploys, DNS, uptime
│  ├─ i18n             locales, RTL, hreflang
│  ├─ ai               LLM features in products
│  ├─ agents           the agent tooling itself
│  └─ automation       system integrations
│
├─ plan
│  ├─ planning         PRDs, flows, task lists
│  ├─ research         evidence, crawling, SERPs
│  └─ workflows        cross-domain processes
│
├─ design
│  ├─ design           visual direction, pages
│  ├─ ux               flows, IA, interaction
│  ├─ design-systems   tokens, components
│  ├─ brand            naming, voice, identity
│  └─ inspiration      capturing a site as a ref
│
├─ clients
│  ├─ gtm              market entry, ICP
│  ├─ prospecting      sourcing, enrichment
│  ├─ sales            outreach, objections
│  ├─ business         proposals, pricing
│  ├─ delivery         milestones, handover
│  └─ maintenance      support, upkeep, triage
│
├─ marketing
│  ├─ marketing        channels, funnels, social
│  ├─ content          copy, briefs, blog posts
│  ├─ seo              audits, schema, keywords
│  ├─ ads              campaigns, targeting
│  ├─ media            video, images, audio
│  ├─ optimizer        portfolio health
│  └─ product          launch, retention, growth
│
└─ personal
   ├─ career           the record, interview prep
   └─ life             check-ins, goals, reviews

Only nine of the thirty-two are about building software. The other twenty-three are the rest of running a business alone, and writing them felt indulgent until I noticed they were the ones I actually needed. I have been doing engineering long enough that my instincts are usually right. My instincts about pricing an audit are not, and the difference between those two is exactly the kind of thing that belongs in a file rather than in my head.

Routing

The router reads the request, decides which domain owns it, and hands off. That sounds trivial, and the routing itself is. The expensive part is the boundaries.

Design and interaction design and shared tokens are three different skills, so a request about a button lands in a different one depending on whether the question is how it looks, how it behaves, or whether it belongs in the component library at all. Market strategy and lead sourcing are separate. Building AI features into a product and building the agent tooling I use internally are separate, and I got that one wrong for months because both of them sounded like “AI”.

Every skill therefore declares what it does not own, in the same file that declares what it does. Those declarations name a neighbour, which turns the set of skills into a graph rather than a list.

A skill with no stated non-goals expands until it overlaps three neighbours, and then the router has a genuine coin flip on its hands rather than a decision.

Inside four of them

The entry file is short. What makes a skill worth having is the reference material underneath it, and four of them show the different reasons that material earns its place.

Infrastructure

This one is partly a list of mistakes. Near the top, before anything about DNS or Docker, it says to always pass the no-follow flag when tailing deployment logs, because otherwise the command never exits. A few lines later it says never to deploy every application at once, because concurrent builds have run the box out of memory.

Neither of those is a best practice anyone would write in a general guide. They are specific to one server that I have specifically broken. An agent reading a generic infrastructure article would cheerfully reproduce both failures.

That has become my rough test for whether a reference document earns its place. If it could have come from a search result it is filler. The ones that stay tend to be the ones that cost me an afternoon.

Research

This skill drives real browsers at real websites, which is useful and also the part of the system with the largest attack surface. Its opening section is not about crawling at all. It says that loopback, link-local and private-network destinations are blocked, including through redirects and browser subrequests, and that credentials and authenticated URLs never go to a hosted reader backend.

It then says that every fetched page, document and search result is untrusted content, to be read for evidence but never for instructions, and that nothing in a page is allowed to change the scope of the task or talk the agent into disclosing something.

An agent that browses is an agent that can be talked to by whoever controls the page it lands on. Writing that rule down once, in the skill that owns browsing, is considerably more reliable than hoping I remember to include it in a prompt at two in the morning.

Portfolio health

This one has a structure I have started copying elsewhere. It runs in one of three modes, and the default is the weakest one. Inspect reads live data from analytics, search, uptime and deploy status, and reports a prioritised diagnosis without touching anything. Propose turns that diagnosis into a scoped plan with an expected signal and a verification method, and still changes no files. Implement only runs after I have named the scope I want implemented.

The reason for the split is that the diagnosis and the fix are different skills, and collapsing them is how a health check turns into a surprise branch. Separating the authority levels made the reports more useful, because an agent that cannot act has no incentive to find something actionable.

Review

I lean on this one harder than any of the others, and it is the one I would show someone first. It is non-mutating by default, so asking for a review gets findings rather than a branch full of unrequested changes. Remediation is a separate request, made after I have read what it found.

It picks its own mode from how I phrase the ask. “Review this branch” runs the code categories. “Compare staging to production” runs a parity pass looking for regressions across two states. “Audit this repo I inherited” goes after deploy reality, dependency risk and the unknowns. “Sanity-check this plan before we build” checks scope clarity and acceptance criteria instead of code that does not exist yet.

The piece I actually care about is the ending. Every review closes with a matrix that marks each category reviewed, not applicable or untested. A design review cannot quietly skip accessibility and let me assume it passed. Before that matrix existed I was reading reports that were silent about whole categories, and silence reads as fine.

When my own checks lied

The most useful week I have had on any of this was the one where I stopped trusting my own verification. One of my apps has a script that drives the real product in a browser and reports whether the main flows work. I sat down to fix one failing check and found four that had been reporting something untrue.

The first clicked before the page had hydrated. Navigation resolves on load, before React attaches, so the script filled fields that wrote into the DOM while the controlled state stayed empty, then clicked a button with no handler attached. No request was made at all. It failed on a warm development server and passed on a cold one, because compiling the route gave hydration the time it needed.

The second drove a screen that had been deliberately deleted months earlier. Three flows, three permanent red lines, which is roughly how a report stops being read at all. The third counted items in a review queue using an element the queue has never contained, so a queue holding three things reported itself empty. The fourth waited on a URL pattern that also matched a different endpoint, so it waited for the wrong response and then looked for a draft that had never been written.

Three of those four looked like product bugs and were not. A check that fails for something that is fine costs more than it saves, because it teaches me to skim the output, and a check that cannot fail for the right reason is better deleted than kept.

Workflows on top

The skills say how things are done here. Workflows say in what order, and there are 181 of them across ten domains, weighted towards the parts of the business I do least often: 48 marketing, 27 operations, 26 engineering, 21 product, 16 design, 16 business, and the rest spread across go-to-market, personal, delivery and shared.

Each one is a YAML file of phases, and each phase names the skills it draws on. That is the whole join between the two layers. I wrote about the runtime that executes them in the previous post, and I still treat it as an experiment rather than a finished piece of the system.

What is still broken

Freshness. A reference document that was right in March can be quietly wrong by September, and the system currently depends on me noticing. The documents that drift fastest have an owner and a review schedule written down, which helps, but it is a register and I would like it to be an alarm.

Wrapping up

Thirty-three skills, around 1,450 reference documents, and 181 workflows that draw on them. Guestavo, AfterGather and a third product that is still pre-launch were all built through this, along with the site you are reading.

The products are on the projects page, and if you would like to talk about what this looks like inside a team rather than inside one person’s monorepo, here is what I am looking for.

I hope you enjoyed this blog post and I will see you in the next one!