Creating Skills

Write your first AI coding skill

Scaffold a Skill

Use the init command to create a new skill template:

$ osk init my-skill

# With agent and template options
$ osk init my-skill --agent claude --template basic

This creates a directory with a SKILL.md file pre-filled with frontmatter and a basic content template.

Writing Content

The content body of your skill is where you define the instructions for the AI agent. Write clear, specific instructions using markdown:

---
name: testing-helper
description: Generate comprehensive test suites
version: 1.0.0
tags:
  - testing
  - tdd
---

# Testing Helper

When asked to write tests, follow these guidelines:

## Structure
- Group related tests in describe blocks
- Use descriptive test names that explain the expected behavior
- Follow the Arrange-Act-Assert pattern

## Coverage
- Test happy paths first
- Add edge cases (null, undefined, empty, boundary values)
- Test error scenarios and error messages

Best Practices

• Be specific — Include concrete examples rather than vague guidelines
• Show before/after — Demonstrate the desired transformation with code examples
• Keep it focused — One task per skill works better than a catch-all skill
• Use headers — Organize content with markdown headers for readability
• Include context — Explain when and why to apply certain patterns

Testing Your Skill

Validate your skill format before publishing:

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

Then install it locally to test with your agent:

$ osk install ./my-skill -t claude