What it is
Agent Skills are small, markdown-based documents teaching an agent how to do a specific task (e.g. "make a reservation", "search our docs", "fill this form"). The Cloudflare Agent Skills Discovery RFC defines an index at /.well-known/agent-skills/index.json listing available skills with metadata.
Why it matters
- Portable, reusable knowledge that any agent can load.
- A skill is small (<100 KB), precise, and authored for clarity, unlike general web pages.
- Combined with MCP, skills become tactical playbooks.
Remediation Prompt
I want to improve my site's agent readiness. Please implement the following fix for Agent Skills Index across our codebase. Instructions: Please fix the Agent Skills Index issue on my site so it is agent-ready.
How we test it
| Step | Method | URL |
|---|---|---|
| A | GET | /.well-known/agent-skills/index.json |
| B (sample) | GET | the first skill URL from the index |
Body cap 256 KB for index; 512 KB for sampled skill.
Pass Warn Fail Matrix
| Condition | Status | Score |
|---|---|---|
| A exists + valid JSON + ≥1 skill + sampled skill reachable | pass | 1.0 |
| A exists + valid JSON + ≥1 skill but sampled skill 404 | warn | 0.6 |
| A exists but empty skills | warn | 0.3 |
| 404 | fail | 0.0 |
Sub Tests
| id | Weight | Pass when |
|---|---|---|
index-present |
0.4 | 200 + parseable JSON |
well-formed |
0.3 | Has skills array with entries containing id, name, url |
sample-reachable |
0.3 | First listed skill URL returns 200 |
Remediation Prompt
Please publish an Agent Skills index at /.well-known/agent-skills/index.json. The index lists skills an agent can download to learn how to perform specific tasks on my site.
Structure:
{
"version": 1,
"skills": [
{
"id": "search",
"name": "Search",
"description": "Search the knowledge base and return top results.",
"url": "https://example.com/skills/search.md",
"inputs": [{"name":"query","type":"string","description":"Search query"}]
}
]
}
For each skill:
- Author a short markdown document (under 2000 words) explaining exactly how to perform the task — step by step, with explicit APIs, endpoints, example inputs, and expected outputs. No marketing prose.
- Host at the URL in the index.
- Keep each skill single-purpose.
Also add an HTTP Link header on the homepage:
Link: </.well-known/agent-skills/index.json>; rel="agent-skills"; type="application/json"
Test Fixtures
pass.json+ one sample skill markdownwarn-empty.jsonwarn-dead-skill.json(index lists a 404 skill URL)fail-404.json