Skills should exist in layers

The more I work with coding agents, the more I think agent skills should not be treated as one flat repository. They should exist in layers. Some skills might exist and belong at the enterprise level e.g. security rules, compliance expectations, architectural principles, deployment standards. Some belong at the technology or platform level e.g. how this organisation/programme/project uses React, .NET, Terraform, Postgres, eventing, or testing. And some skills should be deeply local e.g. the small but important rules that only make sense inside one team’s application.

That local layer is easy to underestimate, but it might be where some of the most useful agent behaviour comes from. Every mature codebase has things a human team knows but an agent may miss. For example “when you add a database migration, remember to update import/export mappings,” “when you add a new permission, update the admin seed data,” “when this enum changes, update the reporting transform.” These are not global best practices. They are team-specific operating knowledge. Turning them into local skills gives the agent access to the same muscle memory the team has built up over time.

The mistake is assuming all useful agent guidance has to be broad, reusable, or centrally managed. Some of it should be. But the closer a skill gets to the codebase, the more specific and valuable it can become. Enterprise skills create alignment. Platform skills create consistency. Team skills prevent the small, recurring mistakes that only people close to the system know to watch for.

In that sense, agent skills are not just prompts. They are a way to encode organisational memory at the right level. The goal is not to overload the agent with every rule everywhere. It is to give it the right guidance at the right layer, so it can behave less like a generic coding assistant and more like someone who understands how this particular team builds this particular system.