Capability discovery is one of those problems that quietly gets solved five different ways in the same company.
For AI agents it matters even more: if you cannot reliably discover and describe your own capabilities, models will not either.
A simple, robust pattern is directory-as-ID:
Why this helps:
Natural for developers
Your repo already uses directory structure to organize concepts. Making it the capability ID means git diff
, code review, and grep remain your primary tools.
Good for governance
ACLs and approval rules can be attached at directory boundaries (e.g., payments/*
requires stronger checks than analytics/*
).
Legible to AI systems
Models (or offline indexers) can infer semantics from stable paths and read schemas/metadata without custom discovery code.
A minimal implementation looks like:
capabilities/
payments/charge/
schema.json
metadata.yaml
implementation.py
Your runtime:
capabilities/
.From there you can project the same capability into MCP tools, HTTP endpoints, CLIs, or direct imports—with governance hanging off the catalog instead of scattered across services.
If you are wrestling with “how do I let agents discover what they can safely do?”, directory-as-ID is a surprisingly powerful starting constraint.