# Echobell Agent
`echobell-agent` is a dedicated repository for agent-facing Echobell integrations.
Version 1 ships one thing only: a reusable Echobell notification skill for
long-running agent work, packaged in a way that can be installed through common
agent instruction surfaces first, with native Codex support as a secondary path.
## What This Repository Includes
- A portable `AGENTS.md` template for agents that support repository-level
instructions
- A reusable `SKILL.md` skill folder for skill-aware runtimes
- Agent-specific adapters for Claude Code, Cursor, Windsurf, Copilot, and Codex
- Generic and Codex-specific installers
- Prompt and payload examples
- Detailed setup, compatibility, usage, adapter, and troubleshooting docs
- A validation script and CI workflow
## Current Scope
- Included: Skill-based agent integration
- Not included yet: MCP server, hosted API helpers, IDE extensions
## Quick Start
1. Create an Echobell channel or Direct key and copy the webhook URL.
2. Export the webhook URL:
```bash
export ECHOBELL_WEBHOOK_URL="https://hook.echobell.one/your-channel-or-direct-url"
```
3. Install the generic repository-level adapter:
```bash
./scripts/install-agent-adapter.sh agents-md /path/to/your/workspace
```
4. If your agent supports native skill directories, optionally install the skill
folder too:
```bash
./scripts/install-skill.sh
```
5. If you use Codex specifically, you can also install the native Codex skill:
```bash
./scripts/install-codex-skill.sh
```
6. Use prompts such as:
```text
Use $echobell-notify and send me a time-sensitive Echobell notification when this refactor finishes.
```
## Repository Layout
```text
.
โโโ docs/
โ โโโ compatibility.md
โ โโโ installation.md
โ โโโ other-agents.md
โ โโโ troubleshooting.md
โ โโโ usage.md
โโโ adapters/
โ โโโ claude-code/
โ โโโ copilot/
โ โโโ cursor/
โ โโโ windsurf/
โโโ examples/
โ โโโ env.example
โ โโโ prompt-kit.md
โโโ scripts/
โ โโโ install-agent-adapter.sh
โ โโโ install-skill.sh
โ โโโ install-codex-skill.sh
โ โโโ uninstall-skill.sh
โ โโโ uninstall-codex-skill.sh
โ โโโ validate-skill.sh
โโโ templates/
โ โโโ AGENTS.md
โ โโโ CLAUDE.md
โโโ skills/
โโโ echobell-notify/
โโโ SKILL.md
โโโ agents/openai.yaml
โโโ references/
โโโ payloads.md
โโโ setup.md
```
## Documentation
- [Compatibility](./docs/compatibility.md)
- [Installation](./docs/installation.md)
- [Usage](./docs/usage.md)
- [Using the repo with other agents](./docs/other-agents.md)
- [Troubleshooting](./docs/troubleshooting.md)
- [Prompt examples](./examples/prompt-kit.md)
## Design Notes
The skill stays intentionally narrow:
- It does not invent a notification product abstraction.
- It assumes Echobell already owns delivery.
- It helps the agent decide when to notify, what urgency to use, and how to
structure a clean payload.
That keeps the skill useful across code review, refactors, data jobs, CI
triage, and other long-running agent tasks without turning the repository into
an SDK too early.
## Validation
Run the local validation flow:
```bash
./scripts/validate-skill.sh
```
The script validates the generic skill installer, the AGENTS/CLAUDE adapters,
the Codex wrapper, and the expected repository assets.
## Roadmap
- Add an MCP server as a separate module
- Add hosted webhook helper tooling if the ergonomics justify it
- Add IDE-specific adapters once the skill workflow stabilizes