Skip to content

Document multiple skill files support #5229

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mintlify wants to merge 1 commit into
base: main
Choose a base branch
from
+28 −5
Open

Document multiple skill files support #5229

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 28 additions & 5 deletions ai/skillmd.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,13 +8,13 @@

The [skill.md specification](https://agentskills.io/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.

Mintlify 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.
Mintlify 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 custom skill files to override the automatically generated one.

<Note>
Generating or updating a `skill.md` file can take up to 24 hours.
</Note>

View your `skill.md` by appending `/skill.md` to your documentation site's URL. Mintlify only generates `skill.md` files for documentation sites that are public.
View your `skill.md` by appending `/skill.md` to your documentation site's URL. If your project has multiple skills, `/skill.md` redirects to the `/.well-known/skills/index.json` discovery endpoint. Mintlify only generates `skill.md` files for documentation sites that are public.

<PreviewButton href="https://mintlify.com/docs/skill.md">Open the skill.md for this site.</PreviewButton>

Expand Down Expand Up @@ -43,7 +43,7 @@
Teach your users how to use `skill.md` files with agents so that they have better results using your product with their AI tools.
</Tip>

## `skill.md` structure

Check warning on line 46 in ai/skillmd.mdx

View check run for this annotation

Mintlify / Mintlify Validation (mintlify) - vale-spellcheck

ai/skillmd.mdx#L46 

'structure' should use sentence-style capitalization.

Mintlify generates a `skill.md` file following the [agentskills.io specification](https://agentskills.io/specification). The generated file includes:

Expand All @@ -60,6 +60,29 @@

Write a custom file when you want precise control over how agents interact with your product. Follow the [agentskills.io specification](https://agentskills.io/specification) to ensure compatibility with agent tooling.

### Multiple skill files

If your product has distinct capabilities that you want to expose as separate skills, add multiple skill files to a `.mintlify/skills/` directory in your project. Each skill lives in its own subdirectory with a `skill.md` file:

```
.mintlify/
skills/
api-management/
skill.md
dashboard/
skill.md
```

Each `skill.md` file must include its own YAML frontmatter with a unique `name` field. The subdirectory name becomes the skill's slug in the discovery endpoints.

When your project defines multiple skills:

- The discovery endpoints at `/.well-known/skills/index.json` and `/.well-known/agent-skills/index.json` list all skills.
- `/skill.md` redirects to `/.well-known/skills/index.json` so agents can discover all available skills.
- Individual skill files are accessible at `/.well-known/skills/{slug}/skill.md`.

If you only need a single skill, you can still add a `skill.md` file to the root of your project. It takes precedence over the automatically generated file.

### Frontmatter fields

Custom `skill.md` files must start with YAML frontmatter.
Expand Down Expand Up @@ -93,7 +116,7 @@

The `/.well-known/agent-skills/` endpoint follows the [agent-skills 0.2.0 discovery spec](https://schemas.agentskills.io/discovery/0.2.0/schema.json) and includes content integrity verification.

`GET /.well-known/agent-skills/index.json` returns a JSON manifest listing all available skills:
`GET /.well-known/agent-skills/index.json` returns a JSON manifest listing all available skills. If your project defines [multiple skill files](#multiple-skill-files), each skill appears as a separate entry:

```json
{
Expand Down Expand Up @@ -125,7 +148,7 @@

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

`GET /.well-known/skills/index.json` returns a JSON manifest listing all available skills:
`GET /.well-known/skills/index.json` returns a JSON manifest listing all available skills. If your project defines [multiple skill files](#multiple-skill-files), each skill appears as a separate entry:

```json
{
Expand All @@ -139,7 +162,7 @@
}
```

The `name` field is a URL-safe slug derived from the `name` in your `skill.md` frontmatter.
The `name` field is a URL-safe slug derived from the `name` in your `skill.md` frontmatter, or the subdirectory name when using the `.mintlify/skills/` directory.

### Individual skill files

Expand Down
Loading