Modules are portable, shareable units of context that anyone can drop into an agent folder. A module is a folder of files that teaches an agent how to do something. It works with whatever connections the agent already has.
## What a module is
A module is a folder inside `modules/`. The only requirement is an `index.md` that explains what the module does. Everything else depends on what the module is for.
A module does NOT contain code, API keys, or connection config. It contains knowledge, processes, and structure. The agent uses the module's instructions together with whatever connections are available in the folder.
## Why this works
Modules are connection-agnostic. A support workflow module doesn't know about Stripe or Postgres. It knows "intake a ticket, find the right playbook, execute with approval, log the result." The agent figures out which connections to use at runtime by reading `connections/`.
This means the same module works for:
- A company using Stripe + Cloudflare
- A company using Postgres + AWS
- A company using Linear + Firestore
The module provides the process. The connections provide the capabilities. The playbooks (built over time) provide the company-specific knowledge.
## Structure
Minimal module:
```
modules/my-module/
index.md # required: what this is, how it works
```
Workflow module (like support-workflow):
```
modules/support-workflow/
index.md # what this is, how the agent should use it
There is no enforced schema beyond `index.md`. Different modules have different structures depending on what they do. When `index.md` gets long, split it into more files and link them from `index.md`.
1. Reads `index.md` to understand what the module does
2. Reads any additional files (steps, playbooks, references)
3. Checks `connections/` for available services
4. Executes using `run_script` with the folder's secrets
5. Writes back to the module (new playbooks, logs) if the module's process calls for it
The module grows over time as the agent adds playbooks and logs. Each copy diverges from the original as it accumulates specific knowledge. When a module stops being relevant, move it to `archive/modules/`.
## What makes a good module
- **`index.md` is self-contained.** Anyone reading it (human or agent) should understand the module's purpose in the first paragraph.
- **Connection-agnostic.** Never reference specific services by name in the workflow steps. Say "the payment provider" not "Stripe."
- **Process over implementation.** Describe what to do, not how to call a specific API. The connection's `index.md` handles the API details.
- **Grows with use.** Playbooks and logs are empty when downloaded. They fill up as the agent works.
## Examples
**Support workflow**: a 5-step process for resolving support tickets. Ships with the process and empty playbooks. The agent builds playbooks as it resolves real issues for your company.
**Onboarding workflow**: a checklist for setting up new team members. Ships with the steps. Each company customizes it with their specific accounts, tools, and access requirements.
**Incident response**: a process for handling production incidents. Ships with severity levels and communication templates. Playbooks accumulate as incidents are resolved.
**SEO pipeline**: a content creation workflow. Ships with the process (research, write, review, publish). Adapts to whatever CMS and analytics connections the company has.
