Writing Experience into the Repository

Recently, I read OpenAI's article about Skills and the Agents SDK, and there's been a small question rolling around in my head.

Are we using AI, or are we gradually organizing our work methods into something AI can also handle?

I used to think that "AI productivity" meant the core was the model getting stronger. It could write code, explain errors, summarize documentation, and translate vague requirements into something usable. But when you actually put it into daily engineering work, things quickly become more concrete.

You realize the problem often isn't that it's not smart enough—it's that it doesn't know how you actually work.

Take "check it after modifying code" for example. Some people naturally run format, lint, and test together. Some only run for the current module. Some remember to add typecheck. Some assume CI will cover it.

Or take preparing to open a PR. Some write the background, scope, and verification methods clearly. Others just leave a short title, like dropping a stone into a river and leaving the ripples for the reviewer to figure out.

These differences seem like personal habits. But if you think one level deeper, they're actually unwritten experience.

And that's what makes Skills interesting.

It's not about making the model learn one more thing, or giving prompts a fancier name. It's more like saying: if something happens over and over, and there's already a relatively stable approach to it, why not write it down carefully, put it in the repository, make it a callable capability?

This touches me a little. Because it's not pursuing a flashier sense of intelligence—it's doing something quite humble: gradually organizing work habits that only existed in people's heads into part of a system.

What Is a Skill Like?

Looking at the surface, a skill is easy to understand as a "prompt template."

But I've come to think of it more as a small work unit. It knows when it should appear, knows what it needs to accomplish, and knows which parts should be left to the model's judgment and which should be handed to scripts.

The OpenAI article mentions that a skill typically has its own description file, and might also carry scripts, reference materials, even some auxiliary resources. In other words, it's not just a casual "help me do this"—it's a slightly organized package of experience.

I really like this feeling.

Because often, knowledge in a team isn't absent—it's just in a very loose form. It might be hiding in a senior engineer's habits, in comments from a code review, in an internal convention mentioned only once. Ask about it and everyone knows a bit; try to write it down and it always feels like "isn't this obvious?"

But once you hand it to an Agent, many "obvious" things suddenly stop being obvious.

It won't naturally know what modifying those directories means. It won't naturally know that some types of changes require full verification while others only need minimal checks. It won't naturally know how you prefer to describe a change, or how to pass context to the next person who picks it up.

So the meaning of skills becomes clear. They're not replacing experience—they're preserving experience. They're not creating new processes—they're shaping those things that were previously maintained by mutual understanding into reusable forms.

The Real Difficulty Isn't Writing "What to Do," But "When to Do It"

I think the most thought-provoking point in OpenAI's article is its emphasis on skill descriptions.

Whether a skill is truly useful isn't about how completely it's written, but how precisely it's written. Especially the boundaries of "when it should be triggered."

This sounds granular, but it's actually a lot like collaborating with people day-to-day. What makes collaboration smooth is never just the steps themselves—it's the timing.

If you only say "run the verification process," that's correct, but almost useless. Because the most important questions remain unanswered:

What kind of changes need verification? Just documentation changes? Just file renames? If tests or build pipelines are touched, should it escalate to a full check? Is this action suggested or required?

When these boundaries aren't clarified, a skill easily becomes decorative. It exists but isn't reliable; sometimes gets called, sometimes gets ignored. The problem isn't with the model—the capability simply hasn't defined when it should appear.

I'd say writing a skill is a bit like writing a very light policy. Policies don't rely on forceful language—they rely on clear boundaries. When something should happen, when it shouldn't, what's exceptional, what must be executed—once these are clear, the process becomes simpler.

The Repository Has Actually Been Missing "Documentation for Agents"

The article also mentions AGENTS.md. I really like this idea.

It's a bit like the onboarding documentation we write for new colleagues, except this time the reader isn't human—it's an Agent.

The repository has its own personality. How directories are structured, where the core paths are, which conventions seem minor but can't be broken, why certain modules' tests run a certain way, whether to trust source code or documentation for certain API behaviors—these are the internal language of the repository.

Usually, humans can understand these things without major problems. They guess, ask questions, fill in a lot of implicit information from context.

But Agents are different. They can reason, of course, but what they fear most is what everyone assumes exists but nobody actually wrote down.

So AGENTS.md feels like not just another document, but finally a clear vessel to hold those "should have been written clearly long ago" repository共识.

If AGENTS.md is like a general introduction, then skills are more like individual workflow units. The former answers "what kind of place is this," the latter answers "how to do a particular thing here."

Going further, there are more deterministic automations like GitHub Actions as the fallback. Looking at this layered approach, it actually makes a lot of sense.

Humans are responsible for forming experience. Documentation is responsible for expressing experience. Skills are responsible for invoking experience. Scripts and CI are responsible for executing experience.

This is quite different from my previous imagination of "AI changing engineering." It's not particularly dramatic—it's more like the familiar path software engineering has always taken: gradually organizing unstable manual operations into stable system behaviors.

The Model Doesn't Need to Do Everything

There's another point in the article I strongly agree with: models shouldn't handle everything.

This is simple to say, but when actually doing it, it's easy to be greedy. Because the model seems capable of handling anything, we unconsciously lump understanding, judgment, execution, and formatted output all together and hand it to the result.

The outcome usually isn't great.

Tasks that require understanding context, making comparisons, summarizing, and judging—models are good at these. But tasks that require fixed command sequences, collecting state, outputting predictable results—are fundamentally more suitable for scripts.

Once this boundary is clear, many design problems solve themselves.

For example, determining if a change is a behavioral change requires the model. It needs to read the diff, understand the intent, and grasp the surrounding context. But "which commands to run first, how to aggregate failures, where to collect git status and branch information"—these should be handed to scripts as much as possible.

I've always believed good systems don't pile capabilities at one point—they separate responsibilities. The model handles what was inherently uncertain. The script handles what should be as deterministic as possible.

This is also why skills feel more "engineering" to me. It doesn't imagine the model as an omnipotent entity—it's willing to acknowledge that truly stable workflows often come from collaboration between different capabilities, not the inflation of a single capability.

In the End, Skills Are Organizing "Tacit Experience"

The more I think about it, the more I feel the most valuable thing about Skills might not be how much efficiency it can improve, but how it forces the team to face something they usually avoid: so much of our work is actually built on tacit experience.

This experience doesn't seem scarce in daily life. Because there's always someone who knows. In a team, there's always some people who are familiar with the repository, familiar with the processes, familiar with all the "unwritten but everyone does it this way" things. So problems always seem solvable, processes always seem to work.

But once the team grows, projects become more complex, or Agents are introduced—these hidden parts immediately surface.

Because AI won't automatically inherit team默契. It also won't naturally understand certain "shouldn't need to be said" rules.

So many problems that used to be quietly消化 by the knowledge network now must be explicitly stated:

What must be done? What's just suggested? Which steps must be automated? Which judgments still need humans? Which knowledge should be written into the repository instead of staying in chat records?

From this perspective, it's not just helping Agents—it's also helping the team re-understand itself. How do you actually work? Which experiences are transferable? Which processes are worth solidifying? Which places relying on personal memory should have been replaced long ago?

It's not a simple new feature—it's more like a quiet organization.

Where Would I Start?

If I were really going to gradually build skills in a repository, I wouldn't start with a big system right away.

I'd rather start with things that are already repetitive enough, clear enough, and have low enough failure costs.

Take verification processes, for example. This is almost the most natural category. What to run after changes, in what order, which cases need additional checks, how to clearly explain failures when they happen—these are all very suitable for organizing into a skill. It's high-frequency, repetitive, and especially prone to gaps when relying on memory.

Or take PR cleanup work. How to write titles, how to summarize changes, how to explain scope, how to write verification methods so reviewers don't have to work hard. These things aren't difficult themselves, but consume a lot of attention. A good draft can often save a lot of back-and-forth explanation.

Then there's documentation verification. OpenAI mentioned in the article that when it comes to platform or API behavior, they have Agents check current documentation instead of relying on memory. I really like this principle. Because things that change fast most fear "I think it was like this." Making "check documentation first, then answer" a default action is essentially adding a necessary constraint to the system.

Further along might be pre-release checks. This kind of process doesn't necessarily happen daily, but when it goes wrong, it often makes people regretful. Version numbers, changelogs, whether examples still run, release note drafts, confirming breaking changes—these are all suitable for gradual沉淀.

They share one thing in common: none are creative work—they're repetitive work. And precisely because of that, they're more worth writing into the repository.

Why I'm Slightly Optimistic About This

There's been a lot of discussion about AI these years, with plenty of excitement. But the more time passes, the more I find myself moved by quieter things. Not the model刷新ing another benchmark, not the Agent completing another complex task, but designs like Skills that don't seem as dazzling but are close to real work sites.

It makes me feel that AI truly entering engineering doesn't have to be through a dramatic replacement—it might be more about this kind of slow infiltration: first taking over a small workflow, then taking over a work habit, then gradually turning a practice that only existed in experience into part of the repository.

What's fascinating about this is it's not creating a new myth—it's preserving things that were already valuable.

We've always said software engineering is about systematizing manual experience. To some extent, Skills is just pushing this statement forward one step.

Before, we wrote experience into documentation, into scripts, into CI. Now, we're starting to try writing experience into capabilities Agents can understand and use.

I quite like this change.

Because it makes me feel for the first time that the Agent isn't an outsider suddenly bursting into the engineering system. It's more like a new participant. And the most important thing for a new participant isn't "how much it can do," but "whether we're willing to seriously tell it how we work."

In the end, skills aren't teaching the model how to work. They're forcing us to first clarify how we actually work.