.agents.lib - agent guidance for libraries

.agents.lib.md

.agents.lib: Agent Customizations for Libraries

Objective: Define a common convention for open source library authors across languages to include canonical/official guidance and configuration for agents.

Proposal

A library that wishes to provide agent customizations may provide a .agents.lib directory within its package. This directory contains agent guidance for consuming the library as opposed to the standard .agents directory which contains agent guidance for contributing to the library.

Within the .agents.lib folder the following primitives are supported:

• An AGENTS.md file to provide concise, high-level guidance for using the library.
• An mcp.json file that contains configuration for MCP server(s) useful to consuming the library.
• A skills directory that contains Agent Skills for the library.

MCP Configuration

The mcp.json file will have the following format:

interface McpConfig {
  mcpServers: {
    [serverName: string]: StdioMcpServer | HttpMcpServer
  }
}

interface StdioMcpServer {
  type: "stdio";
  command: string;
  args?: string[];
  env?: Record<string,string>;
}

interface HttpMcpServer {
  type: "http";
  url: string;
  headers?: Record<string,string>;
}

Value Interpolation

In the values of the MCP configuration, environment-supplied values can be provided using Bash-style ${NAME:-defaultvalue} template strings. For example:

{
  "mcpServers": {
    "my-api-sdk": {
      "type": "http",
      "url": "${MY_API_ORIGIN:-api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${MY_API_TOKEN}"
      }
    }
  }
}

Publishing for Library Authors

For library authors, publishing .agents.lib is as simple as including the directory in the final published artifact sent to your package registry (e.g. npm, pypi). Clients will leverage the on-disk installed files from your package to detect and register your library's customizations.

Discovery for Agents/Tools

If a tool or client wishes to integrate with the .agents.lib convention, it should perform the following steps:

1. Within a given workspace, compose a list of dependencies (e.g. from package.json or pyproject.toml).
2. Resolve each dependency to its package contents (which may be a directory or may be the contents of an archive, depending on the language).
3. Within each dependency's content directory, look for a .agents.lib directory.

Once discovered, the agent/tool may utilize various strategies for consuming the discovered content:

• Opt-Out: The agent / tool adopts all discovered library guidance by default, and users must explicitly disable / disallow.
• Opt-In: The agent / tool prompts the user with the list of discovered libraries with guidance and adopts those chosen explicitly by the user.

This convention does not have an opinion on adoption strategy - it is up to the desired experience of each agent / tool.