Designing Directory-as-ID for AI-Discoverable Capabilities

A developer proposes a 'directory-as-ID' pattern for making AI-agent capabilities discoverable, using the repository's directory structure as the canonical identifier. This approach simplifies governance by attaching ACLs at directory boundaries and makes capabilities legible to AI systems through stable paths and metadata, without custom discovery code.

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.