Skills Are Interfaces to Knowledge, Not the Source of Truth

Recently, I have been thinking more about what should actually live inside an Agent Skill.

Skills are a useful way to teach agents how to perform tasks.

They can describe workflows.

They can contain instructions.

They can reference documentation, scripts, templates, and other resources.

But I think there is an important distinction here.

A Skill can use knowledge.

That does not necessarily mean the Skill should become the source of truth for that knowledge.

Skills are becoming interfaces

Imagine a Skill that helps an agent review a pull request.

The Skill may need to know:

• coding conventions
• architecture decisions
• testing requirements
• security policies
• project terminology

One approach is to put all of this directly into the Skill.

That can work.

Especially when the Skill is small.

But over time, something interesting happens.

The architecture changes.

The security policy changes.

The testing strategy changes.

The terminology evolves.

Now the Skill contains copies of knowledge that may already exist somewhere else.

The Skill is no longer only describing how to perform a task.

It is also becoming another documentation system.

I am not sure that is always a good thing.

I increasingly think of a Skill as an interface between an agent and maintained knowledge.

The knowledge already has a home

Most organizations already have places where important knowledge lives.

Architecture decisions may live in Git.

Policies may live in Confluence.

API contracts may live in documentation.

Operational procedures may live in another repository.

Product terminology may be maintained by another team.

These systems are not going away because agents exist.

And I don’t think we should automatically copy everything from them into SKILL.md.

Consider this structure:

Confluence
Git repositories
ADRs
API documentation
Policies
        │
        ▼
   maintained context
        │
        ▼
       Skill
        │
        ▼
       Agent

The Skill does not need to own every piece of knowledge in this graph.

Its job can be much smaller.

It can explain what knowledge matters, when it matters, and how the agent should use it.

Copying knowledge creates another maintenance problem

Suppose a security team maintains an authentication policy.

A deployment Skill copies part of that policy into its instructions.

A code review Skill copies another part.

A testing Skill contains another summary.

Everything works well at first.

Then the security team changes the policy.

Now we have several questions.

Which Skills contain the old policy?

Who knows they need to change?

Which copy is authoritative?

Did every maintainer interpret the new policy in the same way?

This is a familiar problem.

Software engineers try not to duplicate important logic everywhere.

Documentation has similar problems when the same information is copied across many pages.

Agent knowledge will have the same problem.

The easier Skills become to create, the easier it also becomes to duplicate knowledge.

A reference is sometimes more valuable than a copy

This does not mean a Skill should contain no knowledge.

That would not be practical.

A Skill still needs enough context to explain its purpose and guide the agent.

But there is a difference between knowledge required to perform the workflow and knowledge that already has an authoritative owner elsewhere.

For example, a Skill might say:

Review the change against the current authentication policy.
Source:
security/authentication-policy
Pay particular attention to:
- token handling
- credential storage
- session lifetime

The workflow belongs to the Skill.

The authentication policy does not.

That distinction becomes important when knowledge changes.

Instead of asking:

Which Skills contain a copy of this policy?

we can ask:

Which Skills depend on this policy?

I think the second question is much easier to reason about.

It turns duplicated knowledge into a relationship.

The Agent Skills format already points in this direction

The Agent Skills format itself supports a similar separation.

A Skill has a SKILL.md, but it can also use references/, scripts/, and assets/.

Those resources can be loaded when they are needed instead of putting everything into the main instructions.

This progressive disclosure is useful for context efficiency.

But I think the architectural idea can go further.

Not every useful reference needs to become another copied document inside the Skill directory.

Sometimes the authoritative source belongs somewhere else.

A repository.

A documentation system.

A specification.

A service owned by another team.

The important thing is not necessarily moving all of that knowledge into the Skill.

The important thing is making the relationship understandable.

Source of truth and consumption are different responsibilities

This distinction feels important to me.

A system that owns knowledge and a system that consumes knowledge do not need to be the same thing.

We already accept this in software systems.

An application can consume an API without owning the database behind it.

A package can depend on another package without copying its implementation.

A CI workflow can use a policy without becoming the canonical definition of that policy.

Agent knowledge can work similarly.

A Skill can depend on knowledge without becoming its canonical home.

This gives us a structure that looks more like:

Source of Truth
      │
      ▼
   Context
      │
      ▼
    Skill
      │
      ▼
    Agent

And in a real organization, it may look more like a graph:

Architecture ADR ──────┐
Security policy ───────┼──> Review Skill
Testing guideline ─────┘
Release documentation ───> Release Skill
API specification ────────> Integration Skill
             │
             └────────────> Testing Skill

The relationships become part of the knowledge system.

That feels more scalable to me than copying everything into each Skill.

This changes what a Context Repository means to me

When I first started thinking about Context Repositories, I imagined reusable context assets maintained in Git.

I still think that is useful.

But I increasingly think a Context Repository should not try to become the canonical home of all organizational knowledge either.

That would create another knowledge silo.

Instead, it can also act as a maintained layer between Skills and their sources of truth.

For example, it can help answer questions such as:

• What knowledge does this Skill depend on?
• Where does that knowledge come from?
• Who owns it?
• Is the source internal or external?
• Which other Skills use the same source?
• Has the relationship been reviewed?
• Is the reference still valid?

The actual knowledge might live in Git.

Or Confluence.

Or an API specification.

Or another system entirely.

The Context Repository can make the relationships explicit without needing to own everything behind them.

This is one direction I have been exploring with Renma.

I don’t want Renma to replace those systems.

I want it to help make the knowledge that agents depend on understandable and maintainable.

Better models make this more important, not less

Foundation models will continue to improve.

I expect they will need less detailed instruction for many tasks.

Some things that require long prompts today may eventually need only a small amount of guidance.

But better reasoning does not tell a model which internal policy is authoritative.

It does not tell the model which architecture document is current.

It does not know which team owns a particular decision.

And it cannot resolve duplicated organizational knowledge if we do not understand those relationships ourselves.

Smarter models may need fewer instructions.

But they can make better use of well-maintained knowledge.

This is why I think the long-term value is not in making every Skill larger and more complete.

It may be in making Skills smaller, while making the knowledge behind them more trustworthy.

Skills do not need to know everything

I like Agent Skills because they provide a simple interface for giving agents specialized behavior.

I hope that simplicity remains.

A Skill should explain what an agent needs to do.

It should provide the context necessary to do that reliably.

It can package resources when that makes sense.

But it does not need to become the source of truth for every piece of knowledge it uses.

Sometimes the better design is to leave knowledge where it is maintained and make the dependency explicit.

Maybe this is another way to think about the role of Skills.

Not as containers for everything an agent might ever need to know.

But as maintained interfaces between agents and the knowledge they need to do their work.

References

• Agent Skills Specification
• Context Repository
• Renma