Publishing Guide

Learn how to create and publish skills to the Asterism registry.

1. Create Your Skill

Use the CLI to scaffold a new skill project:

aster init my-awesome-skill

Or use a template for common skill types:

aster init my-skill --template pdf

Available templates: pdf, api, data, code, search

2. Write Your SKILL.md

Every skill needs a SKILL.md file with YAML frontmatter and markdown content:

---
name: my-awesome-skill
version: 1.0.0
description: A brief description of what your skill does
author: your-username
license: MIT
keywords:
  - keyword1
  - keyword2

contract:
  inputs:
    - name: text
      type: string
      required: true
      description: The input text to process
  outputs:
    - name: result
      type: string
      description: The processed result

capabilities:
  - capability: file:read
    reason: To read input files
    constraints:
      paths: ["*.txt", "*.md"]
---

# My Awesome Skill

Description of what your skill does and how to use it.

## Usage

Explain how AI assistants should use this skill.

## Examples

Provide clear examples of inputs and expected outputs.

3. Naming Requirements

Skill names must follow specific rules to ensure uniqueness and prevent confusion:

Lowercase letters, numbers, and hyphens only
Use gerund naming (e.g., "reviewing-code" not "code-review")
No leading, trailing, or consecutive hyphens
Maximum 64 characters

Reserved Names

Names containing these words are blocked to prevent impersonation:

anthropicclaudeopenaigooglemicrosoftgithubadminsystemofficial

Typosquatting Protection

Names too similar to existing popular skills are blocked. Use aster search to check for conflicts before publishing.

4. Security Requirements

All skills are automatically scanned for security issues. Your skill must:

Score at least 50/100 on the security scanner
Not contain hardcoded secrets or API keys
Not include dangerous shell commands (rm -rf, etc.)
Declare all required capabilities in the frontmatter

Run the security audit locally before publishing:

aster audit

5. Test Your Skill

Add tests to your SKILL.md to verify your skill works correctly:

---
# ... frontmatter ...
tests:
  - name: basic-test
    input:
      text: "hello world"
    expected:
      result: "HELLO WORLD"
---

Run tests locally:

aster test

6. Validate Your Skill

Check that your skill is correctly formatted:

aster validate

7. Publish

When you're ready, publish your skill to the registry:

aster publish

Your skill will be published as @username/skill-name. Public skills are immediately available for anyone to install.

8. Updating Your Skill

To publish updates, bump the version and publish again:

aster version patch