Turning team knowledge into agent skills

Most engineering teams have a procedure that exists partly in a document and partly in someone's head. Creating a service might require a particular authentication library, a health endpoint, a standard log format, and a deployment manifest. The template gets you halfway there. A senior engineer supplies the rest during review.

That missing half becomes a problem when an agent starts generating services. It can produce something that compiles while skipping the conventions that make the service supportable.

Anthropic's October 16, 2025 introduction of Agent Skills offered a practical packaging format for that knowledge: folders containing instructions, scripts, and supporting resources that Claude could use for relevant tasks. The release included Claude Code and the API, as well as Claude's applications. Anthropic's announcement describes the original scope.

We think the interesting part is the procedure inside the folder. A prompt library stores things people have asked. A useful skill captures how a team expects a job to be done, including the conditions under which the agent should stop.

Open full-size diagram ↗

Start with a procedure you can check

Consider a skill for adding an internal API endpoint. "Follow our best practices" gives the agent almost nothing to work with. A more useful procedure identifies the existing router, describes the authorization rule, points to a representative test, and specifies the commands that verify the change.

For an endpoint that reads a customer's invoices, the skill might require the implementation to take tenant identity from the authenticated session rather than a query parameter. It might also require a test in which a valid user requests an invoice belonging to another tenant. Those details are worth preserving because they capture the mistake a generic implementation could make.

The skill should not contain the production database password. It should explain which scoped tool or development environment is appropriate. Instructions tell an agent how to work; credentials determine what it can actually reach. Mixing them makes the procedure harder to share and increases the damage if someone copies it into the wrong context.

Some parts should remain ordinary code. If a required manifest field can be checked mechanically, put that check in CI. The skill can explain and invoke the check, but prose is a poor substitute for an enforced invariant.

Open full-size diagram ↗

Someone has to maintain it

Reusable instructions can become stale just like a project template. An old dependency name or retired deployment command is especially troublesome because the agent may apply it consistently across new work.

We would give each shared skill a named owner and keep changes under the same review process as other engineering configuration. When the underlying service conventions change, updating the skill belongs in that change. A small set of representative tasks can help catch regressions: add an endpoint, reject an unauthorized request, and handle a validation failure.

There is also a question of provenance. A downloaded skill may include executable scripts. Treating it as harmless documentation would be a mistake. Review what it reads, what it runs, and whether it sends data outside the environment before making it available to a team.

The immediate opportunity is fairly modest, and useful for that reason. Pick one repetitive task with a clear result. Encode the steps, run it against a real repository, and inspect where a reviewer still has to intervene. Improve the procedure at those points.

If the result is a folder of vague instructions that everybody loads and nobody owns, little has improved. If it removes a recurring review correction while preserving the team's checks, you've turned a piece of engineering knowledge into something people and agents can both use.