agent-tools: Instructions file for Codex

AGENTS.md

Guidance for AI coding agents working in this repository.

What this repository is

adadiamonds/agent-tools is the official, public Ada Diamonds plugin for AI agents. It contains no application code. It is:

• plugin.json: an Agent Plugins 1.0.0 manifest.
• mcp.json: the two Ada Diamonds MCP servers (ada-diamonds at https://www.adadiamonds.com/mcp, ada-diamonds-docs at https://www.adadiamonds.com/mcp/docs), Streamable HTTP, anonymous.
• skills/<name>/SKILL.md: four Agent Skills:
  • ada-diamonds-shopping: search the catalog and quote a complete ring (setting plus loose diamond, USD).
  • ada-diamonds-api: the public REST API reference (endpoints, auth, scopes, sandbox key, rate limits, errors, versioning).
  • ada-diamonds-mcp: connecting to and using the MCP servers from Claude Code, Claude Desktop, Cursor, ChatGPT, or any client.
  • ada-diamonds-commerce: agentic checkout (ACP checkout sessions, product feed, UCP discovery, sandbox vs live, webhooks).
• scripts/validate.mjs: the test suite. Plain Node, no dependencies.

The live source of truth for every fact in the skills is https://www.adadiamonds.com/developers (also served as markdown with Accept: text/markdown), https://www.adadiamonds.com/openapi.json, and https://www.adadiamonds.com/agents.md. When a skill and the live docs disagree, the live docs win; fix the skill.

How to use the skills here

Consumers install them with npx skills add adadiamonds/agent-tools (see README). Inside this repo, when you are asked a question about Ada Diamonds' API or checkout, read the relevant SKILL.md before answering; do not answer from memory.

Editing rules

• Keep every fact consistent with the live docs above. Do not invent endpoints, parameters, scopes, or prices.
• Prices in every example are US dollars as decimals, never cents.
• An engagement ring is a setting plus a loose diamond, priced separately. Every example that quotes a ring must show both numbers and the sum.
• Frontmatter: name must equal the directory name; description non-empty and at most 1024 characters, written as "what it does and when to use it"; keep license: MIT and metadata.homepage. Single-line values only (no YAML block scalars).
• Keep each SKILL.md under 500 lines. Long tables go in references/ inside the same skill directory and are linked relatively.
• Only the keys allowed by the Agent Plugins closed schema may appear in plugin.json ($schema, name, version, description, author, homepage, repository, license, keywords, extensions). Skills and MCP servers are never declared inline in plugin.json.
• mcp.json servers must have type and an absolute https url (for streamable-http / sse); no secrets in headers.
• Prose style: no em dashes; use commas, periods, or parentheses.
• Bump version in plugin.json and add a line to CHANGELOG.md for any user-visible change.