Agent skills: how one developer’s workflow becomes the team’s

An agent skill is a file of instructions that a coding agent loads when a matching task comes up: how this team writes migrations, what our release checklist verifies, which conventions our tests follow. It lives in the repository, gets reviewed in pull requests, and versions like any other code. The idea is almost embarrassingly simple, and it is the single mechanism we have seen most reliably turn scattered individual AI wins into a team capability.

The problem skills solve is familiar to anyone who has run a rollout. Two developers on the team are dramatically effective with agents. Ask them why and you get a shrug, because their advantage is not talent, it is accumulated procedure: how they frame a migration task, which checks they insist on, what context they feed the agent first. All of it sits in their heads and their private prompt history. A skill is that procedure written down where the agent, and therefore everyone, can use it.

What an agent skill is, mechanically

In practice a skill is a markdown file with a name, a short description of when it applies, and the instructions themselves: the steps, the conventions, the checks, sometimes a script or template alongside. The agent reads the description up front and loads the full instructions only when the task matches. That on-demand loading matters more than it sounds: it keeps the agent’s context lean, instead of drowning every session in every rule the team ever wrote.

Skills are not the same thing as the context files agents read on every session. Context files carry what is always true about the codebase: build commands, architecture, universal conventions. Skills carry what is true about a kind of task, loaded only when that task shows up. Confusing the two produces bloated context files and skills nobody triggers, so the distinction is worth enforcing early.

Most agent tooling now supports some version of this pattern. The mechanics differ by tool; the practice of writing procedures down and versioning them transfers everywhere, which is also why skill libraries survive tool migrations better than any other rollout asset.

The skills that pay off first

Start where work is recurring, procedural and annoying to re-explain.

A code review checklist: what this team always checks (error handling on external calls, permission checks on new endpoints, no silent catches), so an agent pre-reviews every PR against your standards rather than generic ones.

A migration procedure: how to write, order and verify database migrations here, including rollback expectations and naming. Migrations are high-stakes and pattern-heavy, the exact combination agents handle badly without instructions and well with them.

Test conventions: fixtures, factories, what gets mocked and what never does, how integration tests get their data. Without this skill, agents write tests that pass and match nothing the team maintains.

A release runbook, a new-service scaffold, an incident postmortem template: each one a procedure someone currently carries in their head. The rule generalizes: if you would explain it the same way twice, it is a skill.

From one developer’s workflow to the team’s

The compounding effect shows up when skills are treated as shared infrastructure rather than personal dotfiles. Written after the second repetition, not the tenth. Reviewed in PRs, because a skill is executable team policy and deserves the scrutiny policy gets. Improved by whoever hits its limits, the way code is.

This is also the honest fix for the adoption gap between your power users and everyone else: the gap is workflow knowledge trapped in heads, and skills are the extraction mechanism. A new hire, or a skeptic finally giving the tools a week, inherits the team’s accumulated judgment on day one instead of rediscovering it. Alongside shared conventions for how tasks get framed, the skill library becomes the place where good practice stops depending on who is at the keyboard.

Building the library without a committee

Resist the workshop where the team brainstorms twenty skills. Most will be speculative and wrong. Better rules: write a skill only for work that has actually recurred; give each one an owner; keep them short enough to review in minutes; delete the ones nobody triggers. Start from evidence, too: the transcripts of your best agent sessions already contain the procedures worth extracting, verbatim.

Expect the library to be small and boring. Five skills that fire weekly beat forty that fire never. And expect pushback that this is documentation nobody will maintain: the difference is that documentation decays invisibly, while a broken skill fails loudly the next time an agent uses it, which turns out to be exactly the feedback loop that keeps it alive.

Seeding the first skills from a pilot squad’s real work, then growing the library squad by squad, is a standard part of how we run agentic engineering with client teams. It is quiet work, and a year later it is the asset teams say they would rebuild first.