SKILL.md for AI Agents

What is SKILL.md?

SKILL.md is a format for agent skill discovery. Coding agents like Claude Code scan the name and description fields at startup, then activate the full skill body when a matching task comes in.

Think of it as a README for AI agents — it tells them what your site offers, how to connect, and when to use it. Install one file and every coding session has access to your content through MCP tools.

How It Works

What's Inside

A SKILL.md file contains everything an agent needs:

---
name: acme-docs-agent
description: "Use when user asks about Acme. Provides 4 MCP tools for site content and search."
---

# Acme Docs Agent Skill

## Site Overview
- Site: https://docs.acme.com
- Pages indexed: 42
- Description: Developer documentation for the Acme API

## MCP Server Connection

```json
{
  "url": "https://w2agent.dev/api/agent/docs-acme-com"
}
```

## Available Tools

### `list-pages`
Returns all indexed pages with titles and URLs.

### `search-site`
Full-text search across all indexed pages.

### `get-page`
Fetches the full markdown content of a specific page.

### `search-faq`
Searches FAQ-style content extracted from the site.

## Key Content Areas
- [Getting Started](https://docs.acme.com/getting-started)
- [API Reference](https://docs.acme.com/api)
- [Authentication](https://docs.acme.com/auth)

## Usage Instructions
Use this skill when the user asks about Acme or needs information from https://docs.acme.com.

Workflow:
1. Connect to the MCP server using the configuration above
2. Use `list-pages` to see available content
3. Use `search-site` to find relevant pages by keyword
4. Use `get-page` to retrieve full content for specific pages
5. Use `search-faq` for question/answer lookups

w2agent Hosted Skills

Every site agentized on w2agent gets a skill.md endpoint automatically at /api/sites/{slug}/skill.md. The MCP endpoint is pre-filled — just download and install.

CLI Generation

Generate a SKILL.md for any URL from the command line. Pass --mcp-endpoint to pre-fill the MCP server connection.

Get Started

Run an audit to get your w2agent score, then generate a SKILL.md to make your site discoverable by coding agents.

How Coding Agents Use SKILL.md

SKILL.md is designed for coding agents that connect to external tools via MCP (Model Context Protocol). When an agent like Claude Code loads a SKILL.md, it learns what content your site offers, which MCP tools are available, and how to connect to your agent server.

The agent reads the skill file once per session and uses the tool descriptions to decide when to call your server. For example, if a developer asks "how does authentication work on acme.com?", the agent sees the search-site tool in the skill and calls it with the query — returning relevant docs without the developer needing to leave their editor.

SKILL.md and the AI-Readiness Stack

SKILL.md is the active-access layer of your AI-readiness stack. While llms.txt provides a static content index for passive discovery, SKILL.md gives coding agents live, queryable access to your content via MCP tools.

Pair with agent-card.json for sites that want to support both coding-agent workflows and A2A protocol discovery. The w2agent score measures all of these layers together.

Related Articles

• agent-card.json — A2A protocol discovery that pairs with SKILL.md for coding-agent workflows.
• Agent Servers (MCP & A2A) — The server infrastructure that SKILL.md configures connections to.
• AI Readiness Audit — How the w2agent score measures your full agent protocol stack.