Agents don't know your company. They run on instructions, in a loop, as long as you let them. Everything that makes a company work, which customers matter, which shortcuts are forbidden, why the pricing is what it is, what the team tried last spring and dropped, lives in the heads of the people who were there. An agent with no access to that is a very fast new hire on their first day, every day.
Most teams I work with already use agents daily. The designer has one, the PM has one, the engineers have a few. What they don't have is a connection between those agents and the team. Each person's setup is private. The team never talks to it, and it never talks to the team. So every agent starts cold, and every person keeps re-explaining the company to their own tools.
The fix I keep coming back to is making the company queryable. Not only its product data, which many teams already have in a warehouse, but its judgment: the decisions people made, the rules they agreed on, and the way each of them works. When that sits where agents can read it, every person's agent starts warm, and the most senior people's way of working stops being locked in their heads.
Two halves of a queryable company
A company is queryable when an agent can answer two kinds of question without asking a person.
The first kind is about the product. How many people finished onboarding last week, which markets are growing, what the refund rate was after the price change. Most of this already lives somewhere an agent can reach: a data warehouse like BigQuery, product analytics, the app stores, the billing system. Connect them read-only, agree on what each metric means and how fresh it has to be, and this half is mostly done. For a warehouse like BigQuery that means a read-only role plus permission to run queries, and a cap on how much a single query may scan, because queries cost money.
The second kind is about the company's judgment. Why is the free trial seven days and not three? Which customers do we never email? What did we decide about the Android release after the last crash? Who owns the onboarding funnel, and what would they say about this change? None of that is in a warehouse. It's in meetings, threads, and people. And it's the half that makes an agent's answer right instead of plausible.
Agents are fast. Attention is the scarce part
Here's what I've seen change when a team sets this up. The agents don't get smarter. The model is the same one everyone else has. What changes is that the attention the team already spent stops being wasted.
A senior person spends real attention on a decision: they look at the data, argue it out, and land on "we never discount the annual plan in the first month". That attention is expensive and rare. In most companies it's spent once and then lives in one person's head and a meeting nobody recorded. Every agent after that, and every new hire, rediscovers it or breaks it.
Written down as a rule an agent reads, the same attention keeps paying out. Every run is told to read it before it acts, and the rules that must never break are also backed by permissions and review, not only by the text. That's why the MUSTs and MUST NOTs matter more than any prompt: they're the attention a team has already paid, piled up where agents can use it. They're also, I'd argue, the most honest description of a team's character you'll find anywhere. What a team refuses to do says more about it than its values page.
The teams I've helped set this up saw real productivity gains once they got used to it. Most of it came from people no longer spending their attention twice on the same question.
The company brain, as files
This sounds abstract until you see it on disk. In my own setup, and in the ones I've built with teams, the company's judgment lives in a handful of plain files that agents read, in a fixed order. Nothing here needs special software. It's a folder, kept honestly.
company-brain/
CLAUDE.md the map: short, read every session
rules/ MUSTs and MUST NOTs, one topic per file,
read only when the task touches that topic
facts-index.md where each fact lives (never the values)
decisions/ one entry per decision, with the why
skills/
growth-ads/
SKILL.md how the job is done
state/learnings.md corrections, one dated rule each
state/log.md what each run did
data-analyst/
SKILL.md
references/learnings/ terminology, schema, identity, baselines
support-replies/ ...
Three details carry most of the weight.
The map stays short. CLAUDE.md is read at the start of every session, so it holds only the rules that always apply and a table of where everything else lives: "when you're doing ads work, read the ads skill; when you need a tax or account fact, read the facts index". The rest stays unread until a task needs it. Most people's instructions file is a notebook that grew for months. Mine is a map.
Facts have an index, not copies. My facts index is one page of rows saying which file holds which kind of fact, an address, a tax number, which account owns which app, with no values in it. The rule on top: never answer a fact from memory, read the one row it points to. A value copied into a second place is the stale copy that gets read next month.
Learnings are sorted, not piled. One data analyst skill I built keeps its learnings in separate files by kind: what the business terms mean, which tables and fields to trust, how users are identified, and baseline numbers. The baselines do quiet work. Before the skill presents a number, it compares it with the stored baseline and flags anything far outside it for a second look.
Map the company so agents know where they are
An agent needs to know where it's standing before it can act well: which project this is, who owns it, which tracker and which data belong to it, which channel to report to. People pick that up from context. Agents need it written.
A simple map does most of the work: teams, projects, owners, and for each project, where its issues live, where its data lives, and what an agent may and may not touch there. With a tracker like Linear used headlessly, the project structure is already half of that map. In my own setup, the folder I'm working in decides which project, which tracker workspace and which Slack workspace a write may go to, and the agent checks the workspace before its first write. That rule, backed by separate credentials for each company, is what keeps their work apart.
Help me write an agent map of our company in docs/company-map.md. Ask me
for our teams and projects, then for each project list: the owner, the
tracker project, the data sources (read-only), the Slack channel it reports
to, and what an agent may never change there. Keep it under 150 lines and
link to deeper docs instead of copying them. Show me the draft here and
don't save anything until I approve it.
A digital twin for every person
The part that surprises people most is also the simplest. Each person's agent can learn to work the way that person works: their checks, their shortcuts, the mistakes they've already made and don't make anymore. Over months, it becomes a working copy of their judgment for the jobs they do most. A digital twin, in a modest and practical sense.
It's built from things you've seen in this blog already. Skills that hold how a job is done. A notes file the skill reads first, where every correction lands as a rule. A few MUSTs and MUST NOTs the person would say out loud if you asked. Nothing exotic, just kept up.
The value shows up when someone else uses it.
- A junior or a new hire gets the senior's way of doing the job on day one. Not a wiki page about it: the actual skill, with the senior's documented checks and the things they refuse to do. Permissions and review still guard anything that must never happen.
- Another senior leading a neighboring department can ask how the growth lead would approach a pricing test, and get an answer shaped by that person's real rules instead of a generic one.
- The senior themselves stops being the bottleneck for questions they've answered fifty times.
Draft my working twin as a skill at .claude/skills/<my-role>/SKILL.md.
Read my existing skills, their learnings files, and my last 30 days of
corrections in this project. Write: the jobs I do most, how I do each one,
the checks I never skip, my MUSTs and MUST NOTs with the reason for each,
and when to ask me instead of deciding. Only include what you can point to
in those files; list anything you guessed separately for me to confirm.
Show me the draft here; don't create the file until I approve it.
Here's what that looks like for me, concretely. My ads operator keeps four files next to the skill: the accounts it may touch, the goals, a log of every change it made, and a learnings file with every correction I've made to it. My standup skill reconstructs what I actually did on a given day from my session history, my commits and the tracker, and writes it as the update the team expects in Slack. Neither is me. Both carry how I work, and a colleague could adapt either one once they've set up their own access and read its assumptions.
A twin is a copy of how someone works, not a replacement for them. It should say when it's unsure, and it should hand decisions it wasn't built for back to a person.
What this looks like in real skills
Here are skills I run myself or built with teams, with identifying details generalized.
| Role | What the skill does | What it carries that a new person wouldn't know |
|---|---|---|
| Data analyst | Answers revenue and funnel questions | What each term means in the data, which internal accounts to leave out, baselines to check every number against |
| Lifecycle marketer | Builds and sends campaigns | Recalculate the audience right before every send, because a saved audience goes stale; show the exact reach and wait for a yes |
| Support | Drafts replies to customer emails | Real replies mined from thousands of past threads, a live account check, and: never close a ticket whose reply can't be delivered |
| User researcher | Finds users worth interviewing | Shortlist cheaply first, profile only the few worth it |
| Operations calendar | Runs what's due today | A ticket opens and closes around each run, so a skipped day is visible; findings go to a person, not the board |
| Ads operator | Proposes ad changes | Goals, accounts, a change log and learnings; spending needs a yes |
| Portfolio lead | Keeps the tracker honest | The code is the truth; close an issue only with evidence posted first |
Read the right-hand column again: it's what a good colleague tells you in your second week, after you've already made the mistake once.
The team layer: two repositories and a few team rules
The next step is deciding which skills the team shares and who looks after them. It's simple, and it's the part most teams skip.
Two repositories, and every skill lives in exactly one. My personal skills sync to my own private repository. The team's skills sync to a company repository that every employee pulls, with a clear naming prefix so nobody wonders which is which. A skill never lives in both, because two copies drift and nobody can tell which one is right. After a reviewed change, a sync script pushes it, and everyone gets it on their next pull.
Every department owns its skills. Growth owns the ads and lifecycle skills, product owns analysis and research, engineering owns release and triage. The people who use a skill every day find what's missing, and they're the ones allowed to improve it.
Team rules sit on top of personal ones. At one company I work with, agents don't file defects into the team's tracker at all: they report to a person, and a person decides what reaches the board, because an issue saying "this is broken" lands on someone's work. In my own setup, the folder I'm working in decides which workspace a write may go to. Rules like these aren't about any one skill. They're the team's character, applied to every agent at once.
Help me set up our team's skills repository. Ask me for our departments and
who owns each, then propose: a naming prefix for team skills, a folder per
department, an owner line at the top of every SKILL.md, a CONTRIBUTING.md
that says how a correction gets back into a skill, and the list of skills
from my personal setup that belong to the team instead. Leave out anything
with credentials, customer data or private notes. Don't move or copy
anything yet; show me the plan and wait for my OK.
Decisions written where agents read them
The heaviest part of working in a team is usually not the work. It's the communication around it: explaining earlier decisions again and again. A lot of that exists only because the decision was never written anywhere a new person, or an agent, would find it.
A decision log fixes most of it, if it's kept the way agents need it: one entry per decision, with the date, who decided, what was decided, why, and what would make us revisit it. Linked from the project it affects. Agents read it before proposing anything in that area; people read it instead of asking.
Read the last 30 days of <Slack channel or meeting notes> and the closed
issues in <tracker project>. Find decisions that were made: pricing, scope,
rules, trade-offs. For each, draft a decision log entry: date, who decided,
the decision, the reason, and what would make us revisit it. Mark anything
you inferred rather than read. Don't write to any tool; show me the list so
I can approve each entry.
Slack, read-only, and only as much as the team wants
Most of a team's live context is in Slack, so it's tempting to plug every agent into every channel. I'd go slower. The Slack connector can also send messages, so turn its write tools off in the connector settings and check which channels the connected account can actually see. Then let the team decide the scope: some channels on by default, others only when someone asks an agent to look, and some never.
Two rules make this work. The agent reads, it doesn't post, unless a specific routine has one channel to report to. And people know which channels agents can read. A team that finds out later that its jokes were being summarized won't trust the setup again, and it shouldn't.
Keep it true, or it's worse than nothing
A queryable company is only useful if the answers are right. An agent that confidently repeats a stale decision or a broken metric does more damage than one that says "I don't know".
Three habits keep it honest:
- Check numbers against the source. An agent that reports a metric should say where it came from and when. A number that suddenly drops to zero is a question, not an answer: check that data is still arriving before believing it.
- Give decisions an expiry. Every decision entry says what would make it worth revisiting. A monthly routine reads the log and flags the ones whose conditions changed.
- Re-test when the tools change. The frontier moves every few months, and the newest harnesses and models unlock things the old ones couldn't. A queryable company is exactly the kind of long-context, many-source work where that shows. When a new model or harness lands, run it on a handful of real questions your team asks and keep it if the answers are better.
What can go wrong
| Risk | What it looks like | What to do |
|---|---|---|
| It feels like surveillance | People stop writing openly in channels agents read | Publish which channels are read, read-only, and let the team choose |
| A twin that fossilizes | It keeps applying last year's rules | Rules carry a date and a reason; old ones get reviewed |
| Stale decisions | Agents defend a choice nobody believes anymore | Each decision says when to revisit it |
| Wrong data, confidently | A broken metric becomes a plan | Every number cites its source and time |
| Someone leaves | Nobody knows who owns their twin | Skills belong to the team's repository, with a named owner per department |
Structures you can copy
These are the shapes I use, trimmed. Copy them, then let the team fill them in.
--- skills/<department>-<job>/SKILL.md
---
name: growth-lifecycle
description: Builds and sends push and email campaigns. Use when asked to
plan, preview or send a campaign, or "who will this reach".
owner: <name>, growth
---
Before anything: read state/learnings.md.
Steps: ...
Always stop and ask before: sending, spending, deleting.
--- skills/<...>/state/learnings.md (one dated line per correction)
<date> <what went wrong, and what to do instead>
<date> Leave internal accounts out of every rate.
--- decisions/<date>-<topic>.md
Decided: <the decision>
By: <name>, with <names>
Why: <the evidence or reasoning>
Revisit if: <the condition that would change it>
--- <team>/CLAUDE.md (short: the map, not the manual)
Always: <3-5 rules that apply to every task>
Read when needed: ads work -> skills/growth-ads; a fact -> facts-index.md
Never: <the MUST NOTs>
Start this week
You're done when a new person's agent can answer "why do we do it this way?" with the real reason and the name of the person who decided it. What I find most striking about teams that get here is how little of it is technology. The agents were always capable. What was missing was the attention the team had already paid, written down where they could use it.
The mechanics behind all of this are in my Harness Engineering series: skills that keep your corrections, routines that run on their own, and one tracker for people and agents.