Putting Experience into the Repository
I recently read OpenAI’s article about Skills and the Agents SDK, and one small question kept turning over in my head.
Are we using AI, or are we gradually organizing how we work into something AI can pick up as well?
I used to think that the core of “AI productivity” was simply that models were getting stronger. They can write code, explain errors, summarize documentation, and turn a vague request into a reasonably usable implementation. But as soon as you actually put one into day-to-day engineering, everything quickly becomes concrete again.
You start to notice that the problem is often not that it isn’t smart enough, but that it doesn’t know how your team actually gets things done.
Consider the routine “check it” after a code change. Some people casually run format, lint, and test; others only run the checks for the current module; some remember to add typecheck; others assume CI will catch anything that slips through.
The same goes for preparing a PR. Some people clearly document the context behind a change, its scope, and how it was verified; others leave only a short title, like throwing a stone into a river and leaving all the ripples for the reviewer to interpret.
These differences look like personal habits. But look one layer deeper, and they’re really forms of experience that have never been written down.
That’s where Skills become interesting.
They don’t teach a model a little more, and they aren’t just a more polished name for a prompt. They say something more like: if a task keeps coming up, and there’s already a relatively stable way to handle it, why not write it down properly, put it in the repository, and turn it into a capability that can be invoked?
This moves me a little. It isn’t about pursuing a more dazzling form of intelligence. It’s doing something much plainer: slowly turning work habits that exist only in people’s heads into part of a system.
What a Skill Is Like
On the surface, it’s easy to think of a skill as a “prompt template.”
But I increasingly think of it as a small unit of work.
It knows when it should appear, what it is supposed to accomplish, and which decisions belong to the model and which belong to a script.
The OpenAI article notes that a skill usually has an instruction file of its own, and may include scripts, reference material, or even supporting resources. In other words, it isn’t a throwaway “please do this for me,” but a body of experience that’s been lightly organized.
I really like that quality.
Because teams do have knowledge; it just tends to live in a loose form. It might sit in a senior engineer’s habits, in the comments from one code review, or in an internal convention that’s mentioned only once. Ask anyone, and they know a bit; ask them to write it down, and they feel, “Isn’t that just obvious?”
But once you hand it to an Agent, many things that seemed obvious stop being obvious.
It won’t inherently know what it means to change those directories.
It won’t inherently know that one kind of change requires full verification, while another needs only a minimal check.
Nor will it know how your team describes a change or how you pass context to the next person who picks up the work.
That’s when the purpose of a skill starts to become clear.
It doesn’t replace experience; it preserves it.
It doesn’t create new processes; it gradually turns things that once held together through tacit understanding into forms that can be reused.
The Hard Part Is Writing “When,” Not “What”
The point in OpenAI’s article that I keep coming back to is its emphasis on the skill description.
Whether a skill is genuinely useful comes down less to how complete its description is than to how precise it is.
Especially the boundary that determines “when it should trigger.”
This sounds like a small detail, but it’s much like working with other people.
What makes collaboration flow smoothly is never just the steps themselves; timing matters just as much.
If you only say “run the validation process,” you’re not wrong, but it’s hardly useful.
The most important questions are still unanswered:
What kinds of changes require validation? What if you only changed the documentation? What if you merely renamed a file? If tests or the build pipeline are affected, should that escalate to a full check? Is this action advisory or mandatory?
When those boundaries aren’t clear, a skill can easily become decorative. It exists, but it’s unreliable; sometimes it gets invoked, and sometimes it gets ignored. The problem then isn’t the model. It’s that the capability has never really defined when it should show up.
Writing a skill feels a little like writing a lightweight policy.
Policies don’t work because they sound forceful; they work because their boundaries are clear.
Once you define when something should happen, when it shouldn’t, what counts as an exception, and what must be done, the rest of the process becomes simpler.
What Repositories Have Long Been Missing: “Documentation for Agents”
The article also mentions AGENTS.md. I like the idea behind it too.
It’s a little like the onboarding docs we used to write for new colleagues, except this time the reader is an Agent.
Every repository has its own character.
How the directory tree is organized, which paths are core, which conventions look unobtrusive but must not be touched, why tests in certain modules have to run that way, and whether a given API’s behavior should be trusted in the source code or in the documentation—all of this forms the repository’s internal language.
People make sense of this kind of thing, and usually it isn’t a problem. Humans guess, ask questions, and fill in a lot of implicit information from context.
Agents are different. They can reason, of course, but what they fear most is the kind of thing everyone assumes exists even though no one has bothered to write it down.
So AGENTS.md doesn’t feel like just another document to me. It feels like the first explicit home for repository consensus that “should have been written down long ago.”
If AGENTS.md is more like the general guide, a skill is more like an individual workflow.
The former answers, “What kind of place is this?” The latter answers, “How should this particular task be done here?”
Then there’s GitHub Actions, providing a more deterministic automated safety net.
Looking at the whole structure layer by layer, it feels quite coherent.
People form experience.
Documentation captures it.
Skills invoke it.
Scripts and CI carry it out.
This is very different from how I used to imagine “AI changing engineering.” There’s nothing especially dramatic about it. Instead, it follows one of software engineering’s most familiar paths: gradually turning unstable manual work into stable system behavior.
Models Don’t Need to Do Everything
There’s another judgment in the article that I strongly agree with: the model shouldn’t be responsible for everything.
It’s a simple thing to say, but in practice it’s very easy to overreach.
Because models seem capable of handling anything, we unconsciously bundle understanding, judgment, execution, and formatted output into one and hand it all to the model.
The results usually aren’t very good.
Models excel at work that requires understanding context, comparing options, summarizing, and making judgments.
But tasks that involve running commands in a fixed order, collecting state, and producing predictable results are still better suited to scripts.
Once you’ve thought through that boundary, many design questions fall into place.
Deciding whether a change is a behavioral change, for example, is a job for the model. It needs to read the diff, understand the intent, and grasp the surrounding context.
But “which commands to run first, how to summarize failures, and where to collect git status and branch information” should be left to scripts wherever possible.
I’ve always thought that a good system doesn’t pile all its capabilities into one place; it separates responsibilities.
The model handles the parts that are inherently uncertain.
Scripts handle the parts that should be as deterministic as possible.
That’s also why a Skill feels closer to “engineering” to me. It doesn’t cast the model as an all-powerful actor; it’s willing to acknowledge that reliable workflows usually come from different capabilities working together, not from a single capability growing indefinitely.
Ultimately, Skills Are About Making Tacit Knowledge Explicit
The more I think about it, the more I believe the most valuable thing about Skills may not be how much efficiency they add. Rather, they force teams to confront something they usually avoid: much of our work rests on tacit knowledge.
That knowledge doesn’t seem scarce in day-to-day work.
Because someone always knows.
Every team has people who know the repository well, know the processes well, and know all the things that “aren’t written down, but everyone does them.” So the problem always looks solvable, and the process always looks like it can be completed.
But as soon as a team grows, a project becomes more complex, or an Agent joins, those implicit parts are immediately exposed.
AI doesn’t inherit a team’s shared understanding on its own.
Nor does it naturally understand the rules that “didn’t need to be said.”
So many problems that the informal network of people who know one another used to absorb quietly now have to be stated explicitly:
What must be done? What is merely recommended? Which steps need to be automated? Which judgments still require a human? What knowledge should be written into the repository instead of being left in chat logs?
This makes me feel that, on the surface, Skills help the Agent; underneath, they also help the team understand itself.
How do you actually work?
Which parts of experience are transferable?
Which processes are worth making explicit and durable?
Which parts that depend on one person’s memory should have been replaced long ago?
From this angle, Skills aren’t simply a new feature. They’re more like a very quiet exercise in tidying up.
Where I’d Start
If I were really building out a skill in a repository, I probably wouldn’t start by building a large system.
I’d rather begin with work that is already repetitive enough and clear enough, and where failure would be costly.
The validation workflow is an obvious example.
What to run after a change, in what order, which cases require extra checks, and how to explain the results when something fails—all of this is well suited to a skill. It comes up frequently, it’s repetitive, and when it lives only in someone’s memory, it’s especially easy to miss something.
Then there’s preparing a PR.
How to write the title, summarize the change, explain its impact, and make verification easy for the reviewer. The work itself isn’t difficult, but it consumes attention. A good draft can save a lot of back-and-forth.
Checking documentation is another example.
In the article, OpenAI mentions that when questions involve platform or API behavior, they have the Agent check the current documentation instead of answering from memory. I like that principle. Things that change quickly are especially vulnerable to “I remember it being like this.” Making “check the docs first” the default action is, in effect, adding a necessary constraint to the system.
Later, I might add a pre-release checklist.
This process may not happen every day, but when something goes wrong, people often regret it. Version numbers, the changelog, whether the examples run, drafting the release note, and confirming breaking changes—all of these can gradually be captured in a skill.
They have one thing in common: none of them is creative work; they’re all repetitive.
Which is exactly why they’re especially worth capturing in the repository.
Why I’m a Little Optimistic About This
There’s been a lot of discussion about AI in recent years, and a lot of noise.
Lately, though, quieter things have moved me more. Not because a model has set a new benchmark score or an Agent has completed an even more complex task, but because of designs like Skills—less flashy on the surface, yet much closer to the reality of actual work.
It makes me think that AI’s real entry into engineering may not come through a single dramatic replacement. More likely, it happens through gradual infiltration: first taking on a small workflow, then a work habit, then slowly turning a practice that once existed only in experience into part of the repository.
What’s appealing about this is that it isn’t creating a new myth; it’s preserving things that were already valuable.
We’ve long said that software engineering is about turning manual experience into systems.
In some sense, Skills simply take that idea one step further.
We used to turn experience into documentation, scripts, and CI.
Now, we’re starting to turn it into capabilities that Agents can understand and use.
I like this shift.
Because it makes me feel, for the first time, that the Agent isn’t an outsider who has suddenly barged into the engineering ecosystem.
It feels more like a new participant.
And for a new participant, the important question isn’t “How much can it do?” but “Are we willing to take the time to explain how we work?”
Ultimately, a skill isn’t teaching the model how to work.
It’s forcing us to first figure out how we work ourselves.