Publishing Guide

Create well-structured skills and save them to the registry via the web UI or GitHub App sync. The MCP surface is read-only — publishing does not go through MCP.

On this page

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.
license: Apache-2.0
compatibility: "cursor claude-code jetbrains-ai"
metadata:
  category: 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.

Field	Required	Constraints
`name`	Yes	Lowercase alphanumeric + hyphens. Max 64 characters. Must be unique within the owner namespace.
`description`	Yes	Plain text, max 1,024 characters. Used for search indexing and discovery.
`license`	No	Free-form license string (e.g. `MIT`, `Apache-2.0`). Omit if you don't want to declare one.
`compatibility`	No	Free-form string, max 500 characters, describing the environments the skill targets (e.g. `"cursor claude-code jetbrains-ai"`). Omit to indicate universal compatibility.
`metadata`	No	Flat map of arbitrary string-key to string-value entries. No reserved keys.
`allowed-tools`	No	Space-delimited string listing the tool names the skill may invoke (e.g. `"Read Write Bash"`). Experimental per the agent-skills spec.

The full SKILL.md body (frontmatter + markdown) must stay under 5,000 tokens to comply with the activation budget defined in the agent-skills specification.

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.

scripts/

Executable scripts the skill can invoke via the Bash tool. Examples: linters, formatters, migration runners. Must be referenced in the SKILL.md body to be accessible.

references/

Documentation, schema files, or specification excerpts the agent can read for context. Useful for domain-specific knowledge that does not fit in the main body.

assets/

Templates, configuration files, and static resources. For example, a boilerplate .eslintrc or a Dockerfile template the skill can scaffold.

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
Navigate to Add Skill
Open the dashboard and click Add Skill in the sidebar.
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
Save
Click Save. The skill is saved as private and added immediately to your team library — your teammates' dev environments will pick it up on their next skillrepo update.
4
Publish (optional)
To make your skill available to all users, visit the skill detail page and click Publish. This action requires confirmation. You can reverse it at any time by unpublishing from the skill detail page, the REST API, or the CLI.

Publishing programmatically

MCP is read-only

The account MCP server exposes four tools — get_skill, get_skill_content, get_skill_file, and list_library. None of them create, update, or delete skills. Publishing goes through the web UI above, the GitHub App sync, or the CLI.

The skillrepo CLI covers both sides. Use skillrepo add, remove, and update to curate the library you've subscribed to for a given environment. To create or modify a skill in the registry, use skillrepo push to upload (and version) a local skill directory, then skillrepo publish or skillrepo unpublish to control catalog visibility. Committing to a tracked GitHub repository (the integration syncs every push) and the web UI remain the other two paths.

See the MCP Reference for the full tool surface.

Versioning

Versions are managed by the registry, not by a field in your SKILL.md. Each save creates a new immutable version row, and the server picks the bump kind from the diff: major if description, allowed-tools, or compatibility changed; minor otherwise. A byte-identical re-save is a no-op.

Latest is always served. When an agent calls get_skill or get_skill_content, it receives the current published version. No pinning is required.

Full history retained. Every version is preserved in the registry. View version history on the skill detail page.

Explicit labels (power-user). The dedicated POST /api/v1/library/{owner}/{name}/versions endpoint lets you supply a version label and an optional changelog string — use it when you want to mirror an external version scheme. See the Automation guide for the full recipe.

Visibility

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

Private

Only members of your organization can discover and activate the skill. Ideal for internal tooling, proprietary workflows, and skills containing sensitive business logic.

Global

Visible to all authenticated registry users. Shows up in the public Skills catalog for all users.

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

To remove a skill entirely, delete it from your dashboard. This permanently removes the skill and all its versions.

Best Practices

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

Write clear, scoped descriptions

The description is what agents use to decide relevance. Be specific about what the skill does, not what it is. “Review TypeScript code for null safety issues and missing error handlers” is better than “Code review skill.”

Keep the body under 5,000 tokens

Move supplementary content into references/ files that stream on-demand. The body should contain the essential instructions the agent needs to start working.

Declare allowed-tools explicitly

Listing the tools your skill requires helps users assess risk before activation. A skill that only needs Read and Grep is safer than one that needs Bash.

Use structured output formats

When your skill produces output, define a clear format (markdown, JSON, YAML) in the instructions. This helps downstream tools parse the results.

Avoid hardcoding paths or secrets

Skills run in different environments. Use relative paths and environment variable references instead of absolute paths or embedded credentials.

Test before publishing

Skills start as private by default. Test with your own IDE integration and validate the output quality before using Publish to make the skill public.

Next steps

Want to read published skills from a remote agent? The MCP Reference documents the four read-only tools — get_skill, get_skill_content, get_skill_file, and list_library.

MCP Reference Getting Started