Add Agent Skills discovery index (.well-known/agent-skills)

.well-known/agent-skills/index.json

@@ -0,0 +1,99 @@
+{
+  "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
+  "name": "DIDWW Agent Skills",
+  "description": "Official DIDWW agent skills: put an AI voice agent on a real DIDWW phone number with any major voice AI platform, through the DIDWW MCP (https://api.didww.com/mcp).",
+  "repository": "https://github.com/didww/ai",
+  "homepage": "https://www.didww.com/",
+  "skills": [
+    {
+      "name": "didww-connect",
+      "type": "archive",
+      "description": "Connect a DIDWW phone number to ANY AI voice platform: helps choose the platform, then wires the SIP trunk pair and number. Use whenever the user wants a voice AI agent on a DIDWW number and has not committed to a platform, asks which AI platform to use with DIDWW, or names a platform that has no dedicated didww-to-X skill installed. Covers ElevenLabs, Vapi, Retell, Ultravox, Vogent, OpenAI Realtime, xAI, LiveKit and the enterprise-gated platforms.",
+      "url": "didww-connect.tar.gz",
+      "digest": "sha256:50a913c53d738eeb409f565143d176998a04edd8008dcbdbf0777a056a52a9f5",
+      "version": "1.0.2",
+      "documentation": "https://github.com/didww/ai/blob/main/docs/didww-connect.md",
+      "install": "npx didww-connect"
+    },
+    {
+      "name": "didww-to-elevenlabs",
+      "type": "archive",
+      "description": "Connect a DIDWW phone number to an ElevenLabs voice agent over SIP, as automatically as both platforms allow. Use whenever the user wants an ElevenLabs agent (Agents Platform, Conversational AI) on a real phone number via DIDWW, mentions pairing DIDWW with ElevenLabs, importing a SIP trunk into ElevenLabs, sip.rtc.elevenlabs.io, or debugging calls between the two. Covers inbound, outbound, transfers and verification.",
+      "url": "didww-to-elevenlabs.tar.gz",
+      "digest": "sha256:522f41eada5f5e6269f9ea71de7452d13e57d077d11643abb6b222fc50bc1e9c",
+      "version": "1.1.0",
+      "documentation": "https://github.com/didww/ai/blob/main/docs/didww-to-elevenlabs.md",
+      "install": "npx didww-to-elevenlabs"
+    },
+    {
+      "name": "didww-to-livekit",
+      "type": "archive",
+      "description": "Connect a DIDWW phone number to a LiveKit Agents worker over SIP, on LiveKit Cloud or self-hosted: inbound trunk, dispatch rule to a named agent, optional outbound trunk. Use whenever the user wants a LiveKit agent (any STT, LLM and TTS combination, including Claude as the brain) answering a real number via DIDWW, mentions sip.livekit.cloud, SIP inbound trunks or dispatch rules, lk sip commands, agent_name dispatch, or debugging calls between DIDWW and LiveKit. This is the bring-your-own-brain pairing: the agent is code the user runs.",
+      "url": "didww-to-livekit.tar.gz",
+      "digest": "sha256:b080e937be6335de5dab427e74584f15d8621445e6bc7969a8b5b24607b2aa62",
+      "version": "1.1.1",
+      "documentation": "https://github.com/didww/ai/blob/main/docs/didww-to-livekit.md",
+      "install": "npx didww-to-livekit"
+    },
+    {
+      "name": "didww-to-openai-realtime",
+      "type": "archive",
+      "description": "Point a DIDWW phone number directly at OpenAI's Realtime API over SIP, with a generated webhook backend for call control. Use whenever the user wants gpt-realtime answering a real phone number via DIDWW, mentions sip.api.openai.com, realtime.call.incoming webhooks, Realtime SIP, or debugging calls between DIDWW and OpenAI. This is the developer-grade pairing: the agent behavior is code the user owns.",
+      "url": "didww-to-openai-realtime.tar.gz",
+      "digest": "sha256:78f33de78d5aa29d849480e4df51c43802d738350a1d0403be725c808a190c25",
+      "version": "1.1.0",
+      "documentation": "https://github.com/didww/ai/blob/main/docs/didww-to-openai-realtime.md",
+      "install": "npx didww-to-openai-realtime"
+    },
+    {
+      "name": "didww-to-retell",
+      "type": "archive",
+      "description": "Connect a DIDWW phone number to a Retell AI agent over custom telephony, with full MCP automation: Retell's official MCP can create agents AND import numbers. Use whenever the user wants a Retell agent on a real phone number via DIDWW, mentions pairing DIDWW with Retell, custom telephony, sip.retellai.com, import-phone-number, or debugging calls between the two.",
+      "url": "didww-to-retell.tar.gz",
+      "digest": "sha256:fe40bae473df088d22c28343df1fab04b86d1b96a250a922cf7e5aa93e82c1b0",
+      "version": "1.0.2",
+      "documentation": "https://github.com/didww/ai/blob/main/docs/didww-to-retell.md",
+      "install": "npx didww-to-retell"
+    },
+    {
+      "name": "didww-to-ultravox",
+      "type": "archive",
+      "description": "Connect a DIDWW phone number to an Ultravox Realtime voice agent over SIP. Use whenever the user wants an Ultravox agent on a real phone number via DIDWW, mentions pairing DIDWW with Ultravox, an account SIP domain, agent_ addresses, allowedCidrRanges, or debugging calls between the two. Covers the address-based routing model that makes Ultravox different from every number-import platform.",
+      "url": "didww-to-ultravox.tar.gz",
+      "digest": "sha256:fbf193be6f46d53965c42f9f086c8b6752885e7cb9497b3708df5bca6ed412e5",
+      "version": "1.1.0",
+      "documentation": "https://github.com/didww/ai/blob/main/docs/didww-to-ultravox.md",
+      "install": "npx didww-to-ultravox"
+    },
+    {
+      "name": "didww-to-vapi",
+      "type": "archive",
+      "description": "Connect a DIDWW phone number to a Vapi assistant over BYO SIP trunking, as automatically as Vapi allows. Use whenever the user wants a Vapi assistant on a real phone number via DIDWW, mentions pairing DIDWW with Vapi, byo-sip-trunk credentials, sip.vapi.ai, or debugging calls between the two. Covers inbound, outbound, transfers and agent binding, following Vapi's and DIDWW's own DIDWW guides.",
+      "url": "didww-to-vapi.tar.gz",
+      "digest": "sha256:d624bbb9ffa4f3ad69488a779c42ed85a06964c03539a41763556746581cc582",
+      "version": "1.1.0",
+      "documentation": "https://github.com/didww/ai/blob/main/docs/didww-to-vapi.md",
+      "install": "npx didww-to-vapi"
+    },
+    {
+      "name": "didww-to-vogent",
+      "type": "archive",
+      "description": "Connect a DIDWW phone number to a Vogent voice agent over SIP import. Use whenever the user wants a Vogent agent on a real phone number via DIDWW, mentions pairing DIDWW with Vogent, sip_import numbers, sip.vogent.ai, or debugging calls between the two.",
+      "url": "didww-to-vogent.tar.gz",
+      "digest": "sha256:1c2227a36a7909cc0fd6c7ebe496c275070b466086a9e0c18614bd05b4df31bd",
+      "version": "1.0.2",
+      "documentation": "https://github.com/didww/ai/blob/main/docs/didww-to-vogent.md",
+      "install": "npx didww-to-vogent"
+    },
+    {
+      "name": "didww-to-xai",
+      "type": "archive",
+      "description": "Point a DIDWW phone number at xAI's Grok voice over SIP. Use whenever the user wants Grok answering a real phone number via DIDWW, mentions sip.voice.x.ai, xAI realtime calls, registering a phone number with xAI, or debugging calls between DIDWW and Grok. Developer-grade: agent behavior is configured per call over a websocket the user's code owns.",
+      "url": "didww-to-xai.tar.gz",
+      "digest": "sha256:7d9fbc775ed9718758b43a9afc93e3b8e020f77780fd9226b4c4dee65f0e6c79",
+      "version": "1.0.2",
+      "documentation": "https://github.com/didww/ai/blob/main/docs/didww-to-xai.md",
+      "install": "npx didww-to-xai"
+    }
+  ]
+}

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to the skills in this repository. Each skill is versioned independently in its `package.json`.
 
+## Agent Skills discovery index (2026-10-30)
+
+- New `.well-known/agent-skills/index.json` in the [Agent Skills discovery](https://github.com/cloudflare/agent-skills-discovery-rfc) format v0.2.0, the same format Telnyx serves at `telnyx.com/.well-known/agent-skills/index.json`. Every skill is a `type: "archive"` entry: a `.tar.gz` with `SKILL.md`, `scripts/`, `references/` and `LICENSE` at the root, and its sha256 `digest`. Extra fields (`version`, `documentation`, `install`) are ignored by clients that do not know them.
+- `scripts/build_index.py` generates the folder from `skills/` (descriptions from the SKILL.md frontmatter, versions from `package.json`); archives are rewritten only when their contents change, so digests stay stable. `--check` runs in `scripts/test.sh` and CI.
+- `scripts/mirror_index.py` lets didww.com keep its copy current from GitHub on a schedule: it verifies every digest and archive before swapping the new set in, and leaves the live folder untouched on any failure. Handoff for the web team: [`docs/agent-skills-index.md`](docs/agent-skills-index.md).
+
 ## Security and correctness review (2026-10-13)
 
 `didww-to-openai-realtime` 1.1.0, `didww-to-vapi` 1.1.0, `didww-to-ultravox` 1.1.0, `didww-to-elevenlabs` 1.1.0, `didww-to-livekit` 1.1.1, and 1.0.2 of `didww-connect`, `didww-to-retell`, `didww-to-vogent` and `didww-to-xai`. Started from an automated review; every finding was reproduced in code and checked against the vendor's own documentation or OpenAPI schema before it was fixed, and the request shapes of all scripts were rechecked against those schemas.

CONTRIBUTING.md

@@ -14,7 +14,8 @@ skills/<name>/        one Claude Code skill = one npm package
   tests/              request-shape tests against stubbed HTTP; no keys, no network
   package.json        npm name = skill name; files whitelist
 docs/                 pages for doc.didww.com, one per skill
-scripts/              family-wide test and publish runners
+scripts/              family-wide test and publish runners, the index builder and the website mirror
+.well-known/agent-skills/  generated: discovery index.json + <name>.tar.gz per skill (never edit by hand)
 ```
 
 ## Before you open a pull request
@@ -24,6 +25,7 @@ scripts/              family-wide test and publish runners
 3. Never commit credentials, account identifiers or real phone numbers. Tests use stubbed HTTP and fake keys.
 4. Verify platform facts against the platform's current documentation and update the "verified" date at the end of the skill's `SKILL.md`.
 5. If you change a skill's behaviour, update its page in `docs/` in the same change.
+6. Run `python3 scripts/build_index.py` and commit `.well-known/` with the change. CI fails while the index or an archive is out of date with `skills/`.
 
 ## Adding a platform
 

README.md

@@ -10,6 +10,7 @@ Open-source tools from [DIDWW](https://www.didww.com/) for building AI voice age
 | [`skills/`](skills/) | Nine Claude Code agent skills that connect a DIDWW number to an AI voice platform. Each is its own npm package. |
 | [`docs/`](docs/) | Documentation pages for the skills, written for [doc.didww.com](https://doc.didww.com/). |
 | [`scripts/`](scripts/) | Family-wide test and publish runners used by maintainers and CI. |
+| [`.well-known/agent-skills/`](.well-known/agent-skills/) | The [Agent Skills discovery](https://github.com/cloudflare/agent-skills-discovery-rfc) index plus one archive per skill, generated from `skills/`, for didww.com to serve at `/.well-known/agent-skills/index.json`. |
 
 ## Skills
 
@@ -34,6 +35,8 @@ npx didww-connect
 npx didww-to-livekit
 ```
 
+Any agent that reads the Agent Skills discovery format can also find all of them from one URL, [`.well-known/agent-skills/index.json`](.well-known/agent-skills/index.json), which lists every skill with a sha256-verified `.tar.gz`.
+
 Straight from this repository, without the npm registry: `npx skills add didww/ai --skill <name>`, or `npx skills add didww/ai --list` to see all nine. Restart Claude Code after installing.
 
 ### Requirements
@@ -51,6 +54,7 @@ The installers copy files and nothing else. The skills store no credentials; pla
 bash scripts/test.sh            # every skill's checks: stdlib Python plus node, no network, no keys
 bash scripts/publish.sh         # publish all nine to npm (after npm login)
 bash scripts/publish.sh didww-to-vapi   # publish one
+python3 scripts/build_index.py  # regenerate .well-known/agent-skills/ after changing a skill
 ```
 
 GitHub Actions runs the same tests on every push and pull request. See [CONTRIBUTING.md](CONTRIBUTING.md) for the skill layout, versioning and how to add a platform, and [CHANGELOG.md](CHANGELOG.md) for releases.

docs/agent-skills-index.md

@@ -0,0 +1,53 @@
+# Serving the agent skills index on didww.com
+
+For the DIDWW web team. The goal is one URL that lets AI agents and skill directories find every DIDWW agent skill:
+
+```
+https://www.didww.com/.well-known/agent-skills/index.json
+```
+
+It uses the [Agent Skills discovery](https://github.com/cloudflare/agent-skills-discovery-rfc) format (v0.2.0), the same one Telnyx serves at `https://telnyx.com/.well-known/agent-skills/index.json`. Nothing on the site is written by hand: the files are generated in the [didww/ai](https://github.com/didww/ai) repository and the site keeps a copy.
+
+## What gets served
+
+The folder [`.well-known/agent-skills/`](../.well-known/agent-skills/) in the repository, as is:
+
+| File | Content-Type |
+|---|---|
+| `index.json` | `application/json` |
+| `<skill-name>.tar.gz` (one per skill) | `application/gzip` |
+
+The index refers to each archive by a relative URL (`didww-connect.tar.gz`), so the files must sit side by side under `/.well-known/agent-skills/`.
+
+## Keeping it current
+
+Run the mirror script on a schedule, for example hourly from cron. It needs Python 3 and nothing else:
+
+```bash
+python3 mirror_index.py --dest /path/to/webroot/.well-known/agent-skills
+```
+
+Download [`scripts/mirror_index.py`](../scripts/mirror_index.py) once, or run it from a clone of the repository. It reads the index from GitHub (`main` branch), downloads every archive, checks each sha256 digest and that every archive is safe to unpack, then replaces the folder in a single step. If anything fails (network, a digest mismatch, a malformed archive) it exits with code 1 and leaves the live folder exactly as it was. It only fetches files that sit next to the index on GitHub.
+
+Example crontab line:
+
+```
+17 * * * * python3 /opt/didww-skills/mirror_index.py --dest /var/www/didww.com/.well-known/agent-skills >> /var/log/didww-skills-mirror.log 2>&1
+```
+
+## Web server settings
+
+- The Content-Types above. With nginx, `location ~ ^/\.well-known/agent-skills/.+\.tar\.gz$ { types { } default_type application/gzip; }` covers the archives; `.json` is mapped to `application/json` by the default `mime.types`.
+- `GET` and `HEAD`, and `404` for files that do not exist.
+- `Cache-Control: public, max-age=3600` matches an hourly mirror.
+- `Access-Control-Allow-Origin: *`, so browser-based agents can read the index.
+- No redirect from `didww.com` to `www.didww.com` is required, but agents follow redirects if there is one.
+
+## Checking it
+
+```bash
+curl -sI https://www.didww.com/.well-known/agent-skills/index.json   # 200, application/json
+curl -s  https://www.didww.com/.well-known/agent-skills/index.json | python3 -m json.tool | head
+```
+
+Every `digest` in the index must equal `sha256:` plus the SHA-256 of the archive the site serves. The mirror guarantees this as long as nothing else writes to the folder.