# Chowdahh skill contract

> Canonical spec for **incoming** skills — anything anyone is building that talks to the Chowdahh agent API on behalf of an LLM. Read this before opening a PR or publishing a third-party integration.

This doc is the source of truth for what a "Chowdahh skill" means. The API itself is documented at <https://chowdahh.com/api> and the machine spec is at <https://chowdahh.com/.well-known/openapi.json>; this doc only covers the **skill layer** sitting on top of the API.

## What a skill is

A **skill** is a small, self-contained package that lets a specific LLM platform read curated news from Chowdahh and write reader signals. One skill = one platform target.

A skill is NOT:
- A new API endpoint (those live in `/Users/splash/Ohpan`).
- A general-purpose SDK (that's `/Users/splash/chowdahh_recipes`).
- A user-facing app.

If your thing is a system-prompt addendum, a Custom GPT, an MCP server, a Claude.ai Skill, a Cursor entry, a Zapier action, or any equivalent — it's a skill.

## The four required pieces

Every skill in `/skills/{name}/` must contain, at minimum:

1. **A platform manifest** in whatever format the target platform uses. Examples:
   - `SKILL.md` with YAML frontmatter for Claude.ai Skills.
   - `instructions.md` + `actions.yaml` for ChatGPT Custom GPTs.
   - `main.go` + `*.mcp.json` for MCP servers.
   - `init-prompt.txt` for raw LLM system-prompt addendums.

2. **A `README.md`** that answers, in order:
   - One-line description (under 25 words).
   - "Install" instructions (paste, upload, build — whatever the platform needs).
   - "Smoke test" — one shell or chat-prompt command that proves the skill is wired up.

3. **The auth contract** — every skill must:
   - Accept a Chowdahh token from the user (env var, paste field, MCP config — pick what's natural for the platform).
   - Use `Authorization: Bearer <token>` for writes (POST/PATCH/PUT).
   - Either use the header form for reads OR use `?key=<token>` on GET URLs (whichever fits the platform). The two forms are interchangeable.
   - Never log, persist, or transmit the token to anywhere except `chowdahh.com`.

4. **The behavior contract** — every skill must:
   - Read `guidance` on every response before acting on `data`. `capability_hints` explains the data; `next_best_actions` tells you what to call next; `suggested_copy` is phrases you can say verbatim.
   - On 401 / 410 / 429, follow the recovery actions in `guidance.next_best_actions` instead of retrying blindly.
   - When summarizing a card for a user, cite the original publisher from `source_urls[0]` and credit chowdahh.com as the curator. Both attributions are non-optional.
   - Identify itself as "Chowdahh" to the user — not Kiteloop, not Ohpan, not the underlying brand.

## Tools / functions a skill should expose

Pick the subset that fits the platform. None are required, but every skill should expose **at least one of the read tools and one of the write tools** so it can both fetch and react.

**Read tools** (any GET on `/api/v1/*`):
- `list_streams` → `GET /streams`
- `get_stream` → `GET /streams/{slug}` (slugs: top, latest, science, world, tech, business, health, culture, sports, good-news, local)
- `search` → `GET /search?q=...`
- `get_topic` → `GET /topics/{id}`
- `get_curator` → `GET /curators/{id}`

**Write tools**:
- `record_signal` → `POST /signals` (types: open, save, share, source_open, track, dismiss, close, react, seen, dwell, tts_play, tts_listen)
- `submit_feedback` → `POST /feedback`
- `submit_item` → `POST /submissions/items`

**Stateful (advanced)**:
- Feed sessions (`POST /feed-sessions`, `/more`, `/controls`) — use when the platform supports long-running state.
- Radio sessions (`POST /radio-sessions`) — use when the platform can play audio.

## Naming

- Skill directory: `skills/{lowercase-hyphenated-name}/`.
- Skill identifies as **Chowdahh** in all user-visible copy.
- Tool names follow the pattern `chowdahh_{verb_noun}` (e.g. `chowdahh_get_stream`) so they don't collide with other vendors' tools in the same agent.

## How to submit

1. Open a PR against the [Ohpan repo](https://github.com/) adding `skills/{name}/`.
2. Include the four required pieces above.
3. Smoke test must pass; include the command in the README.
4. The PR description should answer: which LLM platform, what does the install look like for a non-developer, and one example user request → tool call.
5. If you'd rather not vendor your skill into this repo, link a third-party repo from a one-liner in `skills/THIRD_PARTY.md` (create the file if it doesn't exist) — we'll review and surface it from the landing page.

## What we will not accept

- Skills that bypass `guidance` to do their own thing.
- Skills that summarize cards without citing the publisher.
- Skills that store the Chowdahh token anywhere other than the user's local machine (cloud-stored tokens require a registered curator agreement).
- Skills that scrape `/api/v1/*` for bulk training-dataset extraction. Read `/llms.txt` for the policy.

## Source of truth

When in doubt, the OpenAPI spec at <https://chowdahh.com/.well-known/openapi.json> is authoritative for endpoint behavior, and this doc is authoritative for skill-level contract. If they disagree, file an issue.