Publishing Guide

Creating a SKILL.md File

Every skill starts with a SKILL.md file. This is a markdown file with YAML frontmatter that follows the agent-skills specification. The frontmatter provides structured metadata for discovery and compatibility, while the markdown body contains the instructions your agent will execute.

---
name: api-docs-generator
description: >
  Generate comprehensive OpenAPI 3.1 documentation
  from source code, comments, and type definitions.
version: 1.2.0
license: Apache-2.0
compatibility:
  - cursor
  - claude-code
  - jetbrains-ai
metadata:
  category: documentation
  tags:
    - openapi
    - api
    - documentation
  author: acme
  homepage: https://github.com/acme/api-docs-skill
allowed-tools:
  - Read
  - Grep
  - Glob
  - Write
  - Bash
---

# API Documentation Generator

You are a technical writer specializing in API
documentation. When activated, analyze the codebase
and generate OpenAPI 3.1 specifications.

## Workflow

1. Scan for route handlers and controllers
2. Extract request/response types from source
3. Read inline JSDoc / docstring comments
4. Generate an `openapi.yaml` at the project root

## Output Format

Always produce valid OpenAPI 3.1 YAML. Include:
- Operation summaries and descriptions
- Request body schemas with examples
- Response schemas for all status codes
- Authentication requirements

Frontmatter Fields Reference

The following table describes every available frontmatter field, whether it is required, and its constraints.

Adding Supporting Files

Skills can include files beyond the core SKILL.md. These files are organized into conventional directories and stream on-demand during execution, keeping the initial context lightweight.

Example directory structure

my-skill/
  SKILL.md
  scripts/
    lint.sh
    format.sh
  references/
    style-guide.md
    api-schema.json
  assets/
    template.dockerfile

Saving via the Web UI

The simplest way to add a skill for the first time:

1. 1

   Navigate to Add Skill

   Go to your dashboard and click Add Skill in the top-right corner.

2. 2

   Upload your files

   Drag and drop your SKILL.md and any supporting directories. The UI validates the frontmatter in real time and highlights any issues.

3. 3

   Save

   Click Save. The skill is saved as private and becomes available immediately to your organization via the MCP tools.

4. 4

   Share globally (optional)

   To make your skill available to all users, visit the skill detail page and click Share Globally. This action requires confirmation and cannot be undone.

Adding via MCP

For CI/CD pipelines or automated workflows, use the add_skill MCP tool directly from any connected IDE or agent. Skills are saved as private by default.

// The add_skill MCP tool accepts:
add_skill({
  skillMdContent: "---\nname: code-review\ndescription: ...\n---\n\n# Code Review\n...",
  versionLabel: "1.0",
  files: [                  // optional supporting files
    {
      path: "references/style-guide.md",
      content: "<base64-encoded content>"
    }
  ]
})

Response

{
  "skill": { "owner": "acme", "name": "code-review" },
  "version": { "version": "1.0", "versionNumber": 1 },
  "created": true,
  "message": "Saved code-review v1"
}

See the MCP Reference for full parameter documentation and error handling.

Versioning

Skills Hub uses semantic versioning. Every time you publish an update, the version field in your frontmatter must be higher than the previous version.

// The get_skill MCP tool returns version info:
get_skill({ owner: "acme", name: "code-review" })

// Response includes current version details:
{
  "name": "code-review",
  "owner": "acme",
  "version": "1.2.0",
  "description": "Review code for bugs and security issues.",
  "files": [...]
}

Visibility

Each skill has a visibility setting that controls who can discover and activate it.

All skills start as private. To share a skill globally, visit the skill detail page and click Share Globally. This makes the skill visible to all users in the public catalog.

Best Practices

Well-crafted skills lead to better agent performance. Follow these guidelines to get the most from your skills.