Overview
What an agent Skill is in this context, and the current state of one for Retidal.
A Skill, here, is not a Retidal feature — it’s a portable text artifact (a SKILL.md file plus
reference docs) that teaches an AI coding agent how to call an API correctly: which endpoints exist, what
auth to send, what a request/response actually looks like, and the operational gotchas a plain OpenAPI spec
doesn’t capture. You drop it into an agent’s skills directory (for example, ~/.claude/skills/) and the
agent reads it before it starts writing integration code against your API.
How one would be generated for Retidal
Section titled “How one would be generated for Retidal”The documentation platform this site runs on (reed) can generate a Skill pack automatically from an OpenAPI
spec — reed skill generate --spec <name> — deriving every endpoint, parameter, and example directly from
the spec, with a secret-scanning pass that guarantees the generated file never embeds a real credential value
(only an environment-variable placeholder).
Not turned on for this project yet
Generating a Skill pack requires a skill.<spec> block in docs.json naming which spec (ingestion
or management) to generate from and where to write the output. That block isn’t configured for Retidal
today, so reed skill generate isn’t currently wired up to produce one — running it against this project
as-is would fail with a “no skill.<spec> entries configured” error rather than silently doing
nothing.
What you can use right now
Section titled “What you can use right now”Until a generated Skill ships, the equivalent guidance already exists as regular documentation:
The event-ingestion contract an agent needs to write correct integration code — request shape, both response modes, every error code.
A live, callable equivalent: instead of reading a Skill, an agent can call the Retidal MCP server directly for a fixed set of integration and reporting tasks.