{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs-realm.sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"redocly_category":"Realm","type":"markdown"},"seo":{"title":"Agent skills","description":"OpenAPI-generated documentation tool with 24k+ stars on Github - make APIs your company's superpower.","siteUrl":"https://redocly.com","image":"/assets/redocly-card.f670aae34a39545a5ea633a540cb3a4a333a1f23bb2ed3c4a1b17a5fbcf0ac85.db81178d.png","lang":"en-US"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"agent-skills","__idx":0},"children":["Agent skills"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Agent skills let AI agents complete tasks in your product — like placing an order or searching your catalog — by following steps you write, not by guessing from your reference docs."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each skill is a short, task-focused Markdown file named ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SKILL.md"]}," that follows the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://agentskills.io"},"children":["agentskills.io"]}," format."," ","You author skills alongside your docs, and Realm publishes them at ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#agent-discovery"},"children":["standard discovery endpoints"]}," so agents can find and load them."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"add-a-skill","__idx":1},"children":["Add a skill"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Place each skill in its own folder under ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@skills"]}," at your project root, with the instructions in a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SKILL.md"]}," file:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"treeview","header":{"controls":{"copy":{}}},"source":"your-project/\n├── @skills/\n│   ├── orders/\n│   │   └── SKILL.md\n│   └── menu/\n│       └── SKILL.md\n└── redocly.yaml\n","lang":"treeview"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use kebab-case folder names — the folder name determines the skill's ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#skill-slugs-and-collisions"},"children":["slug"]},"."," ","Inside ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@skills"]}," folders, Realm matches the filename case-insensitively, so ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["skill.md"]}," works the same as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SKILL.md"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can also add a root skill — a single file at the project root named exactly ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SKILL.md"]},"."," ","A root skill is a good place to orient an agent before it picks a task-specific skill."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"skill-format","__idx":2},"children":["Skill format"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SKILL.md"]}," file starts with YAML front matter followed by Markdown instructions."," ","The body is served verbatim."," ","Write it for agents: state when to use the skill, then give ordered steps and links to the relevant reference pages."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["name"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED."]}," Display name for the skill."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["description"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REQUIRED."]}," One or two sentences describing what the skill does and when an agent needs to use it."," ","Agents use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]}," to decide whether to load the skill."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["rbac"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Map[string, string]"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Access rules for the skill, using the same scheme as ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/realm/access/page-permissions"},"children":["page RBAC"]},"."," ","Requires an Enterprise or Enterprise+ plan."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["tags"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["[string]"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Labels that group related skills."," ","Tags appear in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#agent-card"},"children":["agent card"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A skill that is missing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]},", or that has invalid front matter, is skipped with a build warning."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example","__idx":3},"children":["Example"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This skill guides an agent through placing a cafe order and is available only to authenticated users:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","data-title":"@skills/orders/SKILL.md","header":{"title":"@skills/orders/SKILL.md","controls":{"copy":{}}},"source":"---\nname: orders\ndescription: >-\n  Place a Redocly Cafe order for drinks or desserts and track its status.\n  Use when a customer wants to order from the menu or asks about an order they already placed.\nrbac:\n  authenticated: read\n  '*': none\ntags:\n  - cafe\n  - orders\n---\n\n# Place a cafe order\n\n## When to use\n\nUse this skill when a user wants to order drinks or desserts from the cafe menu, or check the status of an order they already placed.\n\n## Steps\n\n1. Find the items the customer wants with `GET /menu`. Note the `menuItemId` of each item.\n2. Place the order with `POST /orders`. The request body takes `customerName` and `orderItems`.\n    Each order item requires `menuItemId` and `quantity`.\n3. Track the order with `GET /orders/{orderId}` until its `status` is `completed`.\n\n## Reference\n\n- Cafe API reference: [https://cafe.redocly.com/openapi/cafe](https://cafe.redocly.com/openapi/cafe)\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"skill-slugs-and-collisions","__idx":4},"children":["Skill slugs and collisions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each skill's slug identifies it in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#agent-discovery"},"children":["discovery endpoints"]},", as the path segment of the skill's published URL."," ","The slug depends on where the skill is defined:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@skills"]}," folder's slug is its folder name, converted to a URL-safe form."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The root ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SKILL.md"]}," slug is your project slug."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Slugs must be unique."," ","If two ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@skills"]}," folders produce the same slug, or a folder collides with the root skill, Realm keeps one skill and logs a build warning for the rest."," ","The root skill always wins a collision."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"agent-discovery","__idx":5},"children":["Agent discovery"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An agent needs only your project URL to discover your skills."," ","It reads the skills index to see which skills are available, then fetches the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SKILL.md"]}," file for the task at hand."," ","A2A-compatible agents can start from the agent card instead."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Discovery respects ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/realm/access/rbac"},"children":["RBAC"]}," and the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/realm/config/skills"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["skills"]}," configuration"]},"."," ","For agents without access, a protected skill is omitted from the skills index, the agent card, and the MCP resources."," ","A direct request for its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SKILL.md"]}," returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]},", as if it doesn't exist."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"skills-index","__idx":6},"children":["Skills index"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The skills index is available at ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/.well-known/agent-skills/index.json"]}," at your project root and follows the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://agentskills.io"},"children":["agentskills.io"]}," discovery schema."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"GET https://example.com/.well-known/agent-skills/index.json\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example response lists a single published skill:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"$schema\": \"https://schemas.agentskills.io/discovery/0.2.0/schema.json\",\n  \"skills\": [\n    {\n      \"name\": \"orders\",\n      \"type\": \"skill-md\",\n      \"description\": \"Place a Redocly Cafe order for drinks or desserts and track its status. Use when a customer wants to order from the menu or asks about an order they already placed.\",\n      \"url\": \"https://example.com/.well-known/agent-skills/orders/SKILL.md\",\n      \"digest\": \"sha256:dced662f5761ef4a8c0ba4b6168901d131a058a37ef5df58c5ade73cf222152a\"\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each entry links to the skill's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SKILL.md"]}," and includes a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["digest"]}," — a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sha256"]}," hash of the file's contents — so an agent can detect when a skill changes."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"skill-files","__idx":7},"children":["Skill files"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Fetch a skill's instructions from the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["url"]}," in its index entry."," ","Each file is served as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["text/markdown"]}," at ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/.well-known/agent-skills/<slug>/SKILL.md"]},", where ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<slug>"]}," is the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#skill-slugs-and-collisions"},"children":["skill's slug"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"GET https://example.com/.well-known/agent-skills/orders/SKILL.md\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"agent-card","__idx":8},"children":["Agent card"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Realm hosts an ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://a2a-protocol.org"},"children":["Agent-to-Agent (A2A)"]}," agent card at ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/.well-known/agent-card.json"]},"."," ","The agent card is a standardized JSON document that lets A2A-compatible agents discover your site and its skills in a single request."," ","It complements the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/realm/customization/mcp-server"},"children":["MCP server"]}," with a lightweight discovery layer."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"GET https://example.com/.well-known/agent-card.json\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For an agent with access to the restricted ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["orders"]}," skill, the following agent card is returned:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"name\": \"Redocly Cafe docs\",\n  \"description\": \"Documentation agent card announcing this site's agent skills and MCP server.\",\n  \"url\": \"https://example.com/a2a\",\n  \"documentationUrl\": \"https://example.com/\",\n  \"version\": \"0.0.1\",\n  \"protocolVersion\": \"0.3.0\",\n  \"preferredTransport\": \"HTTP+JSON\",\n  \"capabilities\": {\n    \"streaming\": false,\n    \"pushNotifications\": false,\n    \"extensions\": [\n      {\n        \"uri\": \"https://modelcontextprotocol.io\",\n        \"description\": \"Model Context Protocol server exposing the documentation tools and skills.\",\n        \"params\": {\n          \"url\": \"https://example.com/mcp\",\n          \"authentication\": {\n            \"required\": true,\n            \"schemes\": [\"bearer\", \"oauth2\"]\n          }\n        }\n      }\n    ]\n  },\n  \"defaultInputModes\": [\"text/plain\"],\n  \"defaultOutputModes\": [\"text/plain\"],\n  \"skills\": [\n    {\n      \"id\": \"orders\",\n      \"name\": \"orders\",\n      \"description\": \"Place a Redocly Cafe order for drinks or desserts and track its status. Use when a customer wants to order from the menu or asks about an order they already placed.\",\n      \"tags\": [\"cafe\", \"orders\"],\n      \"url\": \"https://example.com/.well-known/agent-skills/orders/SKILL.md\"\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The card's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]}," map from the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["title"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]}," fields of your ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/realm/config/seo"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["seo"]}," configuration"]},"."," ","Each entry in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["skills"]}," uses the skill's ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#skill-slugs-and-collisions"},"children":["slug"]}," as its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},"."," ","When the MCP server requires login, the MCP extension declares its authentication schemes so an agent knows to authenticate."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"skills-as-mcp-resources","__idx":9},"children":["Skills as MCP resources"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When skills are published, Realm also registers them as resources on the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/realm/customization/mcp-server"},"children":["Docs MCP server"]},"."," ","An agent connected over MCP can read each skill as a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["text/markdown"]}," resource without fetching the skills index separately."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"resources","__idx":10},"children":["Resources"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/realm/config/skills"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["skills"]}," configuration"]}]}," - Hide skills or exclude files from discovery"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/realm/config/mcp"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mcp"]}," configuration"]}]}," - Enable and configure the Docs MCP server"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/realm/customization/mcp-server"},"children":["Model Context Protocol server"]}]}," - Connect an AI tool to the MCP server that exposes your skills as resources"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/realm/access/rbac"},"children":["RBAC concepts"]}]}," - Control which teams and users can access each skill"]}]}]},"headings":[{"value":"Agent skills","id":"agent-skills","depth":1},{"value":"Add a skill","id":"add-a-skill","depth":2},{"value":"Skill format","id":"skill-format","depth":2},{"value":"Example","id":"example","depth":3},{"value":"Skill slugs and collisions","id":"skill-slugs-and-collisions","depth":2},{"value":"Agent discovery","id":"agent-discovery","depth":2},{"value":"Skills index","id":"skills-index","depth":3},{"value":"Skill files","id":"skill-files","depth":3},{"value":"Agent card","id":"agent-card","depth":3},{"value":"Skills as MCP resources","id":"skills-as-mcp-resources","depth":3},{"value":"Resources","id":"resources","depth":2}],"frontmatter":{"products":["Redoc","Revel","Reef","Realm"],"plans":["Pro","Enterprise","Enterprise+"],"seo":{"title":"Agent skills"}},"lastModified":"2026-07-14T14:31:10.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/realm/customization/agent-skills","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}