add-example-agent - SKILL.md Agent Skill

name: add-example-agent description: Add a new self-contained example agent under examples/. Use when asked to "create an example for ", "add a tutorial agent", "demo integration with ", or when showcasing a new pattern users should copy.

Add Example Agent

Overview

Examples under examples/ are the fastest way users learn Bindu. Each is a self-contained mini-project demonstrating one integration pattern. Follow existing structure — users and agents discover examples by convention, so inconsistency hurts discoverability.

Inputs

<name>: kebab-case slug, e.g. pdf-research-agent, weather-research.
<framework>: Python (agno, langchain, langgraph, crewai) or TypeScript (openai, langchain).
<purpose>: one-sentence "what this demonstrates".

Safety

Never commit .env files. Only .env.example with placeholder values and # pragma: allowlist secret to bypass pre-commit.
Never hardcode API keys, even in comments.
Never introduce paid-only services without a free-tier alternative. Examples must be runnable by a new user within minutes.
Never hardcode ports — default to 3773 with BINDU_PORT override.

Execution Contract

Pick a matching template from existing examples.
Create the directory with the required file set.
Wire the handler to bindufy() with consistent config.
Write a README following the four-section pattern below.
Update parent indexes.
Test end-to-end in a clean environment before committing.

Steps

1. Pick a template

Find an existing example in the same framework and match its layout:

Python — simple: examples/beginner/
Python — multi-agent: examples/agent_swarm/
Python — agno: examples/medical_agent/
Python — langgraph: examples/langgraph_blog_writing_agent/
TypeScript — openai: examples/typescript-openai-agent/
TypeScript — langchain: examples/typescript-langchain-agent/

2. Create the directory

examples/<name>/
├── README.md
├── .env.example
├── main.py          # or index.ts for TypeScript
├── pyproject.toml   # or package.json
└── skills/          # optional, only if agent advertises skills
    └── <skill>/
        └── skill.yaml

3. Wire the handler

Python handler signature:

def handler(messages: list[dict[str, str]]) -> str | dict:
    ...

TypeScript handler signature:

async (messages: ChatMessage[]) => Promise<string | HandlerResponse>

Call bindufy(config, handler) at the bottom of the entry file. Follow the config shape from the template example — don't invent new keys.

4. Write README.md

Four sections, in this order:

What it does — one or two sentences.
Prerequisites — API keys, external services. Link docs for each.
Setup — cp .env.example .env, fill-in list, install command.
Run — uv run python main.py or npx tsx index.ts, plus one example curl against localhost:3773.

5. Update parent indexes

Add a row to examples/README.md.
If this is a new framework, add it to the main README.md framework table.

6. Test in a clean environment

# Python
cd examples/<name>
uv venv --python 3.12.9
source .venv/bin/activate
uv pip install -e .
python main.py &
sleep 3
curl -X POST http://localhost:3773/ -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"message/send","id":"test","params":{"message":{"role":"user","kind":"message","parts":[{"kind":"text","text":"Hello"}],"messageId":"1","contextId":"1","taskId":"1"}}}'

If response arrives and the DID signature is present in metadata, the example is good.

7. Commit

One commit covering the whole example. Conventional commit:

feat(examples): add <name> — <one-line purpose>

Never do

Never copy-paste secrets from another example's .env.example. Each example lists its own required vars.
Never skip the README — an example without a README is invisible.
Never introduce a new pattern (auth flow, storage backend, deployment target) without matching docs in docs/. Examples showcase existing patterns, not unreleased ones.