Getting Started

Create your first AI coding skill and publish it

Overview

Skills are reusable instructions for AI coding agents. They're markdown files with YAML frontmatter that teach agents how to perform specific tasks — from code review to testing to deployment automation.

As a skill creator, you write a SKILL.md file, validate it, and publish it so other developers can install and use it with their preferred agent.

Your First Skill

The fastest way to get started is with the CLI scaffold command:

$ osk init my-skill

# Or specify an agent target
$ osk init my-skill --agent claude

This creates a directory with a SKILL.md template:

---
name: my-skill
description: A brief description of what this skill does
version: 1.0.0
tags:
  - example
---

# My Skill

Instructions for the AI agent go here.

Skill Structure

A skill is a single SKILL.md file, typically in its own directory. You can organize multiple skills in a repository:

my-skills-repo/
├── README.md
├── code-review/
│   └── SKILL.md
├── testing-helper/
│   └── SKILL.md
└── api-docs/
    └── SKILL.md

Validate and Test

Before publishing, validate your skill format:

$ osk validate ./my-skill/SKILL.md

Install it locally to test with an agent:

$ osk install ./my-skill -t claude

Run a security audit to check for potential issues:

$ osk audit ./my-skill

Publish

There are two ways to make your skill available to others:

• Git repository — Push your skill to GitHub. Users install with osk install github:owner/repo. OpenSkill automatically discovers skills from public repositories.
• Direct push — First log in with osk login, then push with osk push ./my-skill (creates a draft), and finally make it public with osk publish my-skill.

# Authenticate first
$ osk login

# Push as draft
$ osk push ./my-skill

# Make it public
$ osk publish my-skill