Skip to content

Document multi-skill support #5228

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
Open

Document multi-skill support #5228

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
24 changes: 24 additions & 0 deletions ai/skillmd.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
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,30 @@

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 are best described separately, you can create multiple skill files using the `.mintlify/skills/` directory. Each subdirectory contains a `SKILL.md` file that defines one skill.

```
.mintlify/
└── skills/
├── api-client/
│ └── SKILL.md
└── data-export/
└── SKILL.md
```

Each `SKILL.md` file follows the same format as a root `skill.md` file, including YAML frontmatter and the [agentskills.io specification](https://agentskills.io/specification).

When you use multiple skill files:
- The `/skill.md` endpoint redirects to `/.well-known/skills/index.json` so agents discover all available skills.
- Each skill appears as a separate entry in the [discovery endpoints](#skills-discovery-endpoints).
- The `name` field in each file's frontmatter determines its URL slug. For example, a skill named `api-client` is served at `/.well-known/skills/api-client/skill.md`.

<Note>
If you have both a root `skill.md` and files in `.mintlify/skills/`, the `.mintlify/skills/` directory takes precedence.
</Note>

### Frontmatter fields

Custom `skill.md` files must start with YAML frontmatter.
Expand Down
Loading