feat: implement .well-known/skills/ discovery endpoint (Cloudflare RFC)

[AlexMikhalev]

Summary

Implement the Cloudflare Agent Skills Discovery RFC for terraphim-skills. This would allow our skills to be discoverable via a standardised .well-known/skills/ endpoint, replacing manual configuration.

Background

Cloudflare published a draft RFC defining a mechanism for discovering AI agent skills using .well-known URIs (RFC 8615). The spec addresses the fragmentation problem where skills are scattered across repositories with no unified discovery.

Our terraphim-skills already align closely with this spec:

• We use SKILL.md files with YAML frontmatter
• We have scripts, references, and assets per skill
• Our naming convention (lowercase, hyphens) matches the RFC naming requirements

What This Enables

1. Web-native skill discovery: Agents fetch https://zestic.ai/.well-known/skills/index.json to discover all published skills
2. Progressive disclosure: Three-level loading (index -> SKILL.md -> resources) reduces token waste
3. Cross-organisation sharing: Clients could auto-discover our skills without manual .claude/settings.json configuration
4. Standard compliance: Aligns with an emerging industry standard backed by Cloudflare

Proposed Implementation

Phase 1: Generate discovery index

• Add a derive-skills-index.py script that generates index.json from existing skill directories
• Each skill entry includes: name, description (from SKILL.md frontmatter), files (list of all files in skill directory)

Phase 2: Serve via static hosting

• Publish generated index.json and skill files at /.well-known/skills/ path
• Could be a static site on Cloudflare Pages, GitHub Pages, or any web server

Phase 3: Progressive disclosure in client

• Update skill loading to use three-level pattern:
  • Level 1: Load only index (name + description) at startup (~100 tokens/skill)
  • Level 2: Load SKILL.md when task matches description (<5k tokens)
  • Level 3: Load scripts/references/assets only when task requires them

Phase 4: Client-side discovery

• Add --discover <url> flag or config option to fetch skills from any .well-known/skills/ endpoint
• Cache aggressively per session

Security Considerations

• Sandbox script execution from discovered skills
• Require user confirmation before running scripts from external origins
• Trust boundaries for skills fetched from non-local origins

References

• RFC: https://github.com/cloudflare/agent-skills-discovery-rfc
• RFC 8615 (Well-Known URIs): https://tools.ietf.org/html/rfc8615
• Agent Skills Specification: https://agentskills.io
• Knowledge base entry: knowledge/cloudflare-agent-skills-discovery-rfc.md