An agent capability library

Open original

The author uses a local LLM called pi that reads a global CAPABILITIES.md index in markdown, pointing to task-specific docs like SSHing into a studio Mac or driving a browser. Pi only loads detailed instructions when a task matches a capability, and new setups are documented and added to the index so agents grow more useful over time.

  • A single symlinked AGENTS.md pointing to a CAPABILITIES.md index lets every project share one growing set of agent capabilities instead of duplicating setup per folder.
  • Pi only loads detailed docs when a task matches one of the index's listed capabilities, keeping context small while still scaling to many tools.
  • Adding a capability is just three steps (write the doc, add an index line, commit), so the library compounds over time as new setups get documented.
  • The agent-docs repo is itself maintained almost entirely by AI, treating documentation upkeep as its own agent task.

On your machine, “pi” lives in each project folder and boots up by reading an AGENTS.md file. Sami moved that file to a central spot (~/.pi/agent/AGENTS.md) as a symlink to CAPABILITIES.md in a repo called agent-docs. That CAPABILITIES.md is a simple index: each line names a tool, gives a quick description of when you’d use it, and points to a markdown doc with the full instructions. For example, “Studio machine” links to STUDIO.md for a powerful always-on Mac you SSH into, and “exe.dev VMs” points to EXE-DEV.md when you need a Linux box with a public HTTPS proxy. When you ask pi to do something, it skim-reads the index first. Only if a task matches one of those seven listed capabilities—Studio, local LLM, private git hosting on the Studio, exe.dev VMs, browser automation, a personal MCP server, or this blog—does it pull in the detailed doc. Those docs explain what each capability is, when you’d call it, and exactly how to run the commands. Sami writes and updates them almost entirely with AI, treating agent-docs itself as an agent built just to maintain the library. Adding a new entry takes three steps: write the markdown doc, add a line in CAPABILITIES.md, and commit. Then every project that includes the central AGENTS.md automatically inherits that capability. Over time, every new tool setup becomes a new doc, and pi grows into a genuinely versatile assistant across all your folders.

Ask about this article