Designing Directory-as-ID for AI-Discoverable Capabilities

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:

• The directory path on disk is the capability identifier.
• A schema + metadata file live alongside the implementation.
• The runtime walks the tree to build a catalog.

Why this helps:

1. 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.

2. Good for governance
   
   ACLs and approval rules can be attached at directory boundaries (e.g., payments/* requires stronger checks than analytics/*).

3. 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:

• Recursively walks capabilities/.
• Loads schema + metadata.
• Registers the capability under the directory path as ID.

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.