Author an Atom Eve agent
Atom Eve is an open registry of installable AI agents, like shadcn but for agents. Authoring one
means adding a folder under registry/<agent>/ in the elie222/atom-eve repo and opening a PR. This
skill is the entry point; the full reference is the repo's AGENTS.md, and the README has its own
skill, agent-readme.
Get into the repo
You author inside the repo, next to the example agents and the generator that validates them.
- Not in the repo yet: fork and clone it (
gh repo fork elie222/atom-eve --clone, or clone your
fork), then pnpm install.
- Already in it: work in
registry/<agent>/.
Start from the closest existing agent (browse registry/) rather than a blank folder.
What earns being an agent
An agent must do work only an LLM can do: judgment, reasoning, writing. If removing the model leaves
roughly the same output, it is a script, not an agent. Tools, CLIs, and connections return raw
facts; the model does the reasoning and the writing. Never bake copy or decisions into tool code.
Do not publish a registry entry that is only a thin wrapper around a reusable skill. If the same
result is better achieved by telling Claude Code or another coding agent to load the raw skill, keep
it as a skill rather than an Atom Eve agent. The strongest shape is an unattended check-then-act
loop: the agent checks real project state (merged PRs, live pages, connected data), verifies what it
finds, and then acts — opens a PR, files issues, or alerts a channel only on material change
(docs-sync is the model). Channel workflows that change where work happens, connected data
sources, durable history, and guarded writes also count. A schedule or Slack access alone does not:
a cron that re-runs a generic audit and emits a report is still a skill wrapper, and a prompt that
says "use this skill/CLI and write a report" is not enough on its own.
The pattern (headlines; AGENTS.md has the detail)
- Structure.
registry/<agent>/ holds exactly three things: README.md (manifest in its
frontmatter, pitch in the body), SETUP.md (env/config facts in frontmatter, walkthrough in the
body), and agent/ (instructions.md, which opens with a <!-- project-config --> block, plus
optional connections/, schedules/, sandbox/, tools/, skills/, lib/). The build derives
name, title, family, and connections. See "Anatomy of an Agent".
- Capability: walk the ladder, stop at the first rung that fits. Start by looking the service
up on integrations.sh (
GET https://integrations.sh/api/{domain}/surface, or its public MCP
server https://integrations.sh/mcp) to see which surfaces exist and what auth they need; its
credential guides also feed SETUP.md env entries (verify discovered facts against official
docs). Then: 1) A good CLI exists: run it in the sandbox + a usage skill. 2) A hosted MCP server
exists: MCP connection, narrowed with tools.allow. 3) A small known API surface: plain
defineTool with a direct fetch, shared client code in agent/lib/. 4) Big API surface, no
CLI, no MCP: OpenAPI connection, the last resort, narrowed with operations.allow. See "Giving
an agent capability".
- Be opinionated. Wire every data source the agent needs and make them all required; name a
primary (first-party ground truth) and a secondary (competitive / gap) rather than marking
either optional. Only a stack-dependent write destination (a GitHub blog vs a CMS) is optional.
- Config in one place. What the operator sets (site, domain, repo, keywords) lives in the
<!-- project-config --> block at the top of instructions.md, mirrored one-to-one by
SETUP.md config; the schedule's prompt stays generic and refers to "the configured X".
instructions.md is addressed to the agent in the second person. No credentials, no
marketing tone, no "edit this after install".- README: use the
agent-readme skill. Value-led "What it does", skimmable, no Setup section.
Everything the agent needs (env, config, the wiring walkthrough) goes in SETUP.md instead.
Verify
Run pnpm check. For install-sensitive changes, also run the clean install flow in AGENTS.md
("Verification"). Then open a PR against elie222/atom-eve.
1---2name: author-atom-eve-agent3description: Use when authoring or contributing a NEW Atom Eve agent to the registry (not installing an existing one) - designing what it does, wiring its capability and connections, and writing the README, SETUP.md, and agent/ source. Triggers include "build a new Atom Eve agent", "contribute an agent", "add a new agent to the registry", "author an Atom Eve agent". To install an existing agent, use install-atom-eve-agent instead.4---56# Author an Atom Eve agent78Atom Eve is an open registry of installable AI agents, like shadcn but for agents. Authoring one9means adding a folder under `registry/<agent>/` in the `elie222/atom-eve` repo and opening a PR. This10skill is the entry point; the full reference is the repo's `AGENTS.md`, and the README has its own11skill, `agent-readme`.1213## Get into the repo1415You author inside the repo, next to the example agents and the generator that validates them.1617- Not in the repo yet: fork and clone it (`gh repo fork elie222/atom-eve --clone`, or clone your18 fork), then `pnpm install`.19- Already in it: work in `registry/<agent>/`.2021Start from the closest existing agent (browse `registry/`) rather than a blank folder.2223## What earns being an agent2425An agent must do work only an LLM can do: judgment, reasoning, writing. If removing the model leaves26roughly the same output, it is a script, not an agent. Tools, CLIs, and connections return raw27facts; the model does the reasoning and the writing. Never bake copy or decisions into tool code.2829Do not publish a registry entry that is only a thin wrapper around a reusable skill. If the same30result is better achieved by telling Claude Code or another coding agent to load the raw skill, keep31it as a skill rather than an Atom Eve agent. The strongest shape is an unattended check-then-act32loop: the agent checks real project state (merged PRs, live pages, connected data), verifies what it33finds, and then acts — opens a PR, files issues, or alerts a channel only on material change34(`docs-sync` is the model). Channel workflows that change where work happens, connected data35sources, durable history, and guarded writes also count. A schedule or Slack access alone does not:36a cron that re-runs a generic audit and emits a report is still a skill wrapper, and a prompt that37says "use this skill/CLI and write a report" is not enough on its own.3839## The pattern (headlines; `AGENTS.md` has the detail)4041- **Structure.** `registry/<agent>/` holds exactly three things: `README.md` (manifest in its42 frontmatter, pitch in the body), `SETUP.md` (env/config facts in frontmatter, walkthrough in the43 body), and `agent/` (`instructions.md`, which opens with a `<!-- project-config -->` block, plus44 optional `connections/`, `schedules/`, `sandbox/`, `tools/`, `skills/`, `lib/`). The build derives45 name, title, family, and connections. See "Anatomy of an Agent".46- **Capability: walk the ladder, stop at the first rung that fits.** Start by looking the service47 up on integrations.sh (`GET https://integrations.sh/api/{domain}/surface`, or its public MCP48 server `https://integrations.sh/mcp`) to see which surfaces exist and what auth they need; its49 credential guides also feed SETUP.md `env` entries (verify `discovered` facts against official50 docs). Then: 1) A good CLI exists: run it in the sandbox + a usage skill. 2) A hosted MCP server51 exists: MCP connection, narrowed with `tools.allow`. 3) A small known API surface: plain52 `defineTool` with a direct fetch, shared client code in `agent/lib/`. 4) Big API surface, no53 CLI, no MCP: OpenAPI connection, the last resort, narrowed with `operations.allow`. See "Giving54 an agent capability".55- **Be opinionated.** Wire every data source the agent needs and make them all required; name a56 **primary** (first-party ground truth) and a **secondary** (competitive / gap) rather than marking57 either optional. Only a stack-dependent write destination (a GitHub blog vs a CMS) is optional.58- **Config in one place.** What the operator sets (site, domain, repo, keywords) lives in the59 `<!-- project-config -->` block at the top of `instructions.md`, mirrored one-to-one by60 SETUP.md `config`; the schedule's prompt stays generic and refers to "the configured X".61- **`instructions.md` is addressed to the agent** in the second person. No credentials, no62 marketing tone, no "edit this after install".63- **README: use the `agent-readme` skill.** Value-led "What it does", skimmable, no Setup section.64 Everything the agent needs (env, config, the wiring walkthrough) goes in SETUP.md instead.6566## Verify6768Run `pnpm check`. For install-sensitive changes, also run the clean install flow in `AGENTS.md`69("Verification"). Then open a PR against `elie222/atom-eve`.
elie222