​

skill.md Files

Every Docsalot documentation site automatically serves a skill.md file that AI agents can install and use to better understand your product. This feature shipped last week and is available across all tiers with no configuration needed.

npx skills add https://your-docs.docsalot.dev

​

What is a skill.md File?

A skill.md file is a structured markdown document that teaches AI agents how to effectively use your product documentation. Think of it as a cheat sheet for AI that bridges the gap between raw documentation and practical usage.

While traditional documentation is written for humans who browse and build mental models over time, AI agents need different information:

​

Why skill.md Files Are Necessary

​

The Problem They Solve

Even with access to your full documentation, AI agents often struggle to:

• Navigate complex documentation structures efficiently
• Make correct choices between multiple implementation options
• Understand product-specific patterns and best practices
• Know which pages contain the most relevant information

skill.md files solve these problems by providing agents with a structured navigation guide that follows Anthropic’s best practices for agent context.

​

skill.md vs Other Standards

• vs llms.txt

• vs MCP

​

How It Works

​

Discovery Process

When an agent or the skills CLI tries to add your documentation, it follows this discovery flow:

{
  "skills": [{
    "name": "your-product",
    "description": "Your product documentation reference...",
    "files": ["SKILL.md"]
  }]
}

​

Automatic Generation

Docsalot automatically generates your skill.md file by:

1. Analyzing your layout.json to understand your documentation structure
2. Extracting key topics from your navigation groups
3. Creating decision tables that map needs to specific pages
4. Following Anthropic’s best practices for concise, effective skill files

The generated file is typically ~40 lines compared to generic templates that can be 120+ lines, making it more efficient for agents to process.

​

What’s Included

Your automatically generated skill.md file contains:

name: your-product
description: >
  Third-person description of your documentation.
  Includes trigger terms and key capabilities.

| Topic | Key Pages |
|-------|-----------|
| Getting Started | `/quickstart`, `/installation` |
| API Reference | `/api/endpoints`, `/api/authentication` |
| Guides | `/guides/basics`, `/guides/advanced` |

| Need | Action |
|------|--------|
| Full page list | Fetch `/llms.txt` |
| All content | Fetch `/llms-full.txt` |
| Specific page | Fetch `/{path}` |

- Read-only access to published documentation
- Cannot modify content or manage accounts
- Direct users to support for undocumented topics

​

Customizing Your skill.md

While Docsalot generates skill.md files automatically, you can customize them:

​

Adding a Custom Skill File

1. Create a SKILL.md file in your documentation repository
2. Follow the structure outlined above
3. Push to your repository
4. Docsalot will serve your custom file instead of the generated one

​

Best Practices for Custom Skills

​

Testing Your skill.md

To verify your skill.md file is working:

# Install the skill
npx skills add https://your-docs.docsalot.dev

# The skill will be installed to your agent's directory
# For Claude Code: ~/.claude/skills/your-product/SKILL.md

Then test with your AI agent:

1. Ask a question about your product
2. Observe which documentation pages the agent references
3. Check if it follows the guidance in your skill.md file

​

Supported AI Agents

The skill.md standard is supported by 20+ AI coding agents, including:

• Claude Code (Anthropic)
• Cursor
• OpenCode
• Codex
• Windsurf
• Continue
• Zed AI
• And many more…

​

Technical Implementation

For those interested in the technical details:

​

Endpoints Served

Every Docsalot site serves three endpoints:

​

Progressive Disclosure

The skill.md system uses a three-tier approach:

1. Level 1 (Metadata): ~100 tokens loaded at startup for all installed skills
2. Level 2 (SKILL.md): The main file, read when triggered, kept under 5K tokens
3. Level 3 (Resources): Additional files like /llms.txt loaded on demand

This ensures agents only load what they need, when they need it.

​

Learn More

​

References

• Cloudflare Skills RFC - The protocol specification
• agentskills.io - Community standard and compatibility
• Vercel skills CLI - The npx skills add implementation
• Anthropic Best Practices - Official authoring guide