AI agent skills are not system knowledge

AI agents are becoming practical teammates. They can write code, analyse a spreadsheet, review a pull request, and help document a system. But useful work needs two different kinds of guidance: a method for doing a task and an understanding of the place where that task is being done.

Reusable agent skills and AGENTS.md files provide those two kinds of guidance. They work best together because they answer different questions.

The simple version

Imagine an AI agent is a new member of your team. A reusable skill teaches that person how to perform a type of work: how to test an API, build a spreadsheet, or investigate a failed build. They can use that knowledge in many projects.

An AGENTS.md file is the handbook for one specific project. It explains how that system is organised, who owns which areas, what rules cannot be broken, and how changes should be checked.

What a reusable skill provides

A reusable skill contains procedural knowledge: a dependable sequence for a common type of work. It might cover how to create and verify a document, interpret a test failure, or work with a spreadsheet.

This is valuable because the same process can help many people and many projects. A student making a class presentation and a functional team preparing a business report can both benefit from a good document-creation workflow. Neither needs to start from a blank page.

Skills reduce the amount of specialist knowledge someone needs before they can get useful help. They give the agent a sensible working method rather than expecting it to invent one every time.

What AGENTS.md provides

Every organisation has local knowledge that cannot be copied from a general workflow. It may include architecture decisions, deployment boundaries, governance policies, organisational ownership, runtime contracts, domain models, and system invariants.

For example, a repository might require that customer data remains isolated, that existing API clients keep working, that business rules stay out of database code, or that sensitive prompts are never logged. These are not optional coding preferences. They are properties that protect the system and the people who depend on it.

That is why this information belongs with the repository. An agent can follow an excellent generic testing skill and still make the wrong change if it does not know the local contracts it must preserve.

Why AI Governance Platform needs both

AI Governance Platform is an AI-governance control plane. It deliberately separates its domain, API, services, databases, workers, and external integrations. It also has rules around auditability, explainability, and tenant isolation.

Those boundaries are part of how AI Governance Platform works. They are captured in its layered AGENTS.md instructions, including more focused guidance for areas such as the API, domain layer, persistence, and tenancy.

A reusable skill remains helpful inside those boundaries. An API-testing skill can guide the testing process, while AI Governance Platform's repository instructions make clear that the work must preserve tenant isolation and public API compatibility. The skill supplies the method; the repository supplies the context and guardrails.

An everyday analogy

Think about learning to use a medical device. The training manual teaches the general skill of operating it. A hospital's own procedures then explain who may use it, how patient information is handled, and what to do in an emergency.

Both documents matter. One tells you how the device works; the other tells you how to use it responsibly in that particular hospital.

Software systems are similar. General working methods help agents and people move faster. Local instructions help them make changes that fit the organisation's design, responsibilities, and safety requirements.

Use them together

The division of responsibility is straightforward:

• Use reusable skills for workflows that should work across many projects.
• Use AGENTS.md for system-specific architecture, policies, ownership, contracts, and non-negotiable rules.
• Give an agent both when it works in a repository: the skill guides the task and the repository instructions keep it aligned with the system.

For a student project, the local instructions might only say which tools to use, where tests live, and which files should not change. For a large enterprise system, they can describe the governance boundaries that protect customers and keep the platform reliable.

The takeaway

Reusable skills make good ways of working easy to share. AGENTS.md makes the knowledge unique to a system visible and actionable.

Keep both. One captures how to perform a class of tasks; the other captures how this system works. That simple separation helps AI agents be useful without losing the context that makes responsible engineering possible.