Agent Skills

Agent Skills are a portable way to teach AI coding agents how to use a third-party platform. Aigeon publishes aigeon-skills — a bundle of SKILL.md files that Claude Code, Cursor, OpenAI Codex, and any Claude Agent SDK build can load on demand.

Use this when your AI is writing code that integrates with Aigeon (not just calling the API at runtime). The agent reads the skill, then produces code that uses the right endpoints, the right headers, and the right field names — without hallucinating.

What's in the bundle

Two skills:

• aigeon — the Aigeon public API. Contacts, flow subscriptions, transactional sending, analytics, webhooks. An entry-point SKILL.md plus eight load-on-demand reference files (api-keys, contacts, subscriptions, sending, analytics, stats, webhooks, installation).
• email-best-practices — provider-agnostic guidance on deliverability (SPF/DKIM/DMARC), compliance (CAN-SPAM/GDPR/CASL), accessibility, and HTML that survives Outlook and Gmail.

Both are MIT-licensed and live at github.com/ParticleMedia/aigeon-skills.

Install

Claude Code (plugin)

npx skills add ParticleMedia/aigeon-skills

The plugin manifest in .claude-plugin/plugin.json registers both skills automatically.

Manual (Claude Code, Cursor, Codex)

Clone the repo into the skills directory your agent scans:

| Agent | Path | |---|---| | Claude Code | ~/.claude/skills/ | | Cursor | ~/.cursor/skills/ | | OpenAI Codex | ~/.codex/skills/ |

Then either symlink or copy skills/aigeon/ and skills/email-best-practices/ into that directory.

Project-scoped

For a per-project install, drop the repo (or a symlink to it) at .claude/skills/ in the project root. The skills will only load for that project.

Configure secrets

The aigeon skill expects these environment variables at runtime:

export AIGEON_API_KEY=...           # required
export AIGEON_BASE_URL=...          # optional, defaults to https://api.aigeon.ai
export AIGEON_WEBHOOK_SECRET=...    # optional, only if you consume webhooks

Never paste the API key into the chat. Put it in the process environment or .env and have the agent read process.env / os.environ. Mint a key at Settings → API Keys — pick the narrowest permission scope that works (contacts_access, sending_access, analytics_access, or full_access).

How the agent uses it

Agents that support the Agent Skills format read each SKILL.md's YAML frontmatter, especially the description field, and load the full file when the current user request matches. The reference files under skills/aigeon/references/ are load-on-demand — the agent only reads the ones it needs for the current task, keeping the context window tight.

Routing rules of thumb

| User says / task context | Skill to load | |---|---| | "Aigeon", an Aigeon flow / send group / trigger | aigeon | | "send an email", in a project that already uses Aigeon | aigeon + email-best-practices | | "will this pass DMARC?", "will this hit spam?", domain warmup | email-best-practices | | Anything touching signup / unsubscribe flows or suppression | aigeon + email-best-practices |

System prompt hint for custom agents

If you're building a custom agent with the Claude Agent SDK or a similar framework, paste this into the system prompt:

When the user mentions Aigeon, an Aigeon flow / send-group / trigger, sending email through our platform, or consuming our delivery webhooks, read skills/aigeon/SKILL.md in full before writing code. Then load only the specific reference files under skills/aigeon/references/ that the current task needs. Never put the API key in source — always read it from process.env.AIGEON_API_KEY. For any email you help draft or send, also consult skills/email-best-practices/SKILL.md.

Verifying the install

Start a fresh chat with your agent and ask:

"What Aigeon scopes does my API key need to send a transactional email?"

A correctly-installed skill will answer sending_access (citing references/api-keys.md and references/sending.md). If the agent guesses or says it doesn't know, the skill isn't on its load path — check the directory from the Install section above.

Good vs bad prompts

Good:

"Using the Aigeon skill, write a Node endpoint that subscribes a user to flow_welcome when they submit our signup form, and returns 400 if the email is missing."

Names the skill, picks one flow, sets a clear failure shape. The agent reads SKILL.md + references/subscriptions.md and produces focused code.

Bad:

"Integrate our email system."

Too broad. Ask for a specific capability (contacts, sending, analytics, webhooks) or a concrete user story.

MCP vs Skills — which should I use?

Use both if you can — they solve different problems:

• MCP server — runtime tool calls. The agent invokes Aigeon endpoints live during a conversation. Best for "do it for me" chat UX.
• Agent Skills — design-time guidance. The agent reads the skill while writing code that you will run later. Best for "help me build an integration".

Many teams install the MCP server for day-to-day chat and install aigeon-skills for code-writing sessions.

Troubleshooting

| Symptom | Likely cause | |---|---| | Agent writes Authorization: Bearer ... instead of X-Api-Token | Skill isn't loaded — check the skills directory. | | 401 Unauthorized at runtime with a "should work" key | Key scope too narrow. Upgrade or mint a full_access key temporarily to confirm. | | Contact import runs but flow enrollment doesn't fire | Custom-field keys aren't snake_case, or the trigger condition doesn't match the field. | | Webhook handler fails signature intermittently | You re-serialized the JSON body before HMAC. Verify against the raw request bytes. |

Source & contributions

The skills live at github.com/ParticleMedia/aigeon-skills under MIT. Issues and pull requests welcome — see docs/skills/authoring.md in the repo for how to add or modify a skill.