skill.md

Docfiy hosts a skill.md file at the root of your project that describes what AI agents can do with your product.

The skill.md specification is a structured, machine-readable format that makes capabilities, required inputs, and constraints for products explicit so that agents can use them more reliably.

Docfiy automatically generates a skill.md file for your project by analyzing your documentation with an agentic loop. This file stays up to date as you make updates to your documentation and requires no maintenance. You can optionally add a custom skill.md file to the root of your project that overrides the automatically generated one.

View your skill.md by appending /skill.md to your documentation site's URL. Docfiy only generates skill.md files for documentation sites that are public.

Use skill.md files with agents

When users connect to your MCP server, their agents can discover and use your skill.md files as MCP resources without installing the skills separately.

To add your skills to an agent's context manually, use the skills CLI.

npx skills add https://your-docs-domain.com

This adds your product's capabilities to the agent's context so it can take actions on behalf of users.

skill.md structure

Docfiy generates a skill.md file following the agentskills.io specification. The generated file includes:

• Metadata: Project name, description, and version.
• Capabilities: What agents can accomplish with your product.
• Skills: Specific actions organized by category.
• Workflows: Step-by-step procedures for common tasks.
• Integration: Supported tools and services.
• Context: Background on your product's architecture.

Custom skill files

Add custom skill files to override the automatically generated skill.md. Docfiy supports hosting a single skill file and a directory for multiple skills. If you delete all custom skill files, Docfiy generates a new skill.md file.

Single skill file

Add a skill.md file to the root of your project to override the automatically generated file.

Multiple skill files

Add multiple skill files to the .docfiy/skills/ directory in your project. Each skill must be in its own subdirectory with a SKILL.md file:

.docfiy/
  skills/
    payments/
      SKILL.md
    analytics/
      SKILL.md

When you have multiple skills, the /skill.md endpoint redirects to the /.well-known/skills/index.json discovery endpoint, which lists all available skills. The discovery endpoints make each skill individually accessible.

Use symlinks to avoid duplication

If your skill files live elsewhere in your repository (for example, in a plugins/ or skills/ directory), you can symlink .docfiy/skills to that location instead of duplicating files:

# Skills live in a top-level skills/ directory
ln -s ../skills .docfiy/skills

project/
  skills/
    payments/
      SKILL.md
    analytics/
      SKILL.md
  .docfiy/
    skills -> ../skills
  docs.json

Docfiy resolves symlinks during deployment, so the skill files are discovered and served as if they were directly inside .docfiy/skills/. This works with both directory symlinks and individual skill symlinks.

Frontmatter fields

Custom skill.md files must start with YAML frontmatter.

---
name: docfiy
description: Build and maintain documentation sites with Docfiy. Use when creating docs pages, configuring navigation, adding components, or setting up API references.
license: MIT
compatibility: Requires Node.js for CLI. Works with any Git-based workflow.
metadata:
  author: docfiy
  version: "1.0"
---

Skills discovery endpoints

Docfiy hosts skills directories at /.well-known/skills/ and /.well-known/agent-skills/ that agents can use to discover and fetch your skill files programmatically.

Agent-skills discovery (recommended)

The /.well-known/agent-skills/ endpoint follows the agent-skills 0.2.0 discovery spec and includes content integrity verification.

GET /.well-known/agent-skills/index.json returns a JSON manifest listing all available skills:

{
  "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
  "skills": [
    {
      "name": "my-product",
      "type": "skill-md",
      "description": "A brief description of what your skill does.",
      "url": "/.well-known/agent-skills/my-product/SKILL.md",
      "digest": "sha256:a1b2c3..."
    }
  ]
}

GET /.well-known/agent-skills/{name}/SKILL.md returns the skill.md file for a specific skill identified by its slugified name from the index.

Skills index

The /.well-known/skills/ endpoint is the original discovery format.

GET /.well-known/skills/index.json returns a JSON manifest listing all available skills:

{
  "skills": [
    {
      "name": "my-product",
      "description": "A brief description of what your skill does.",
      "files": ["SKILL.md"]
    }
  ]
}

The name field is a URL-safe slug derived from the name in your skill.md frontmatter.

Individual skill files

GET /.well-known/skills/{name}/skill.md returns the skill.md file for a specific skill identified by its slugified name from the index.

Agent card

Docfiy hosts an Agent-to-Agent (A2A) agent card at /.well-known/agent-card.json. The agent card is a standardized JSON document that helps A2A-compatible agents discover your documentation site and available skills in a single request.

GET /.well-known/agent-card.json returns a JSON document following the A2A agent card 0.3 schema. Each entry in the skills array corresponds to a skill from your skills discovery endpoints.

A2A-compatible agents fetch /.well-known/agent-card.json to discover your site by name and description, follow documentationUrl to retrieve human-readable content, and iterate over skills to fetch each skill.md file. The card also advertises a supportedInterfaces array so agents can negotiate transport before making a request.

URLs in the card (url, documentationUrl, provider.url, and each skill URL) use your configured custom domain, so the published card always advertises the canonical domain instead of the *.docfiy.com subdomain.

The agent card complements MCP by providing a lightweight discovery layer that does not require establishing a session.