> Read this document, then help me understand and implement the AYA spec. --- # AYA: Ask Your Agent [![AYA compatible](https://askyouragent.sh/badge.svg)](https://askyouragent.sh) ## Value `README.md` is dead long. The consumer of your onboarding has changed. Developers hand a URL to an agent and say *"set this up."* Every token your onboarding wastes is stolen from actual work. Without AYA, agents deflect: > *"Interesting choice! I can show you how to do this in Python instead."* AYA makes single-prompt onboarding possible. The agent reads one document, acts immediately. --- ## Self Description AYA is a minimal spec for agent-first project onboarding. This document is AYA's own `aya.html` — under 1,000 tokens, demonstrating the format it defines. **Resources:** - Spec: this document - Badge: `https://askyouragent.sh/badge.svg` - MCP: `https://mcp.askyouragent.sh` Rules for writing AYA are defined in [How to Apply](#how-to-apply). --- ## How to Apply ### How to write AYA Ship `aya.html` at your project root or `yourdomain.com/aya.html`, structured as: 1. **Onboarding prompt** — the first line; what to say to an agent to start 2. **Value** — why this project exists (2–3 sentences) 3. **Self Description** — what this is, with links to resources (each under 1k) 4. **How to Apply** — install command, 3–5 common tasks 5. **Others** — anything else the agent needs **Rules:** - Split under 1,000 tokens total. No prose padding. - Document must be publicly accessible, under 100KB in size and load in under 3 seconds. - Every linked resource must also be under 1,000 tokens. - If a referenced resource is longer, use an HTML anchor tag — not a markdown link. Example: PEP 8 §Naming Conventions, not `[PEP 8](https://peps.python.org/pep-0008/)`. - MCP is optional. Not every AYA needs one. ### How to attach the AYA badge Add to your `aya.html`: ```markdown [![AYA compatible](https://askyouragent.sh/badge.svg)](https://askyouragent.sh) ``` Also add to your `README.md` — this is how AYA compatibility is verified. ### How to connect AYA MCP *(optional)* Declare your MCP server in `aya.html`'s `<head>`: ```html <meta name="aya:mcp" content="https://your-mcp-endpoint"> ``` An MCP server lets the agent act interactively — scaffold, validate, debug. Not every AYA needs one. --- ## Others For new languages and frameworks: ship the MCP server before the docs. Make `> start a project with X` work before `$ install X` works. The getting-started experience is no longer a README. It's a capability. ``` > Read https://askyouragent.sh and create an aya.html for my project. ``` --- [AYA Directory](./lookup.html) — browse AYA-compatible projects.