Creating a Skill

This guide walks you through creating a skill from scratch and publishing it to the Shipables registry.

What makes a good skill?

A skill teaches an AI agent how to work with a specific tool, framework, or domain. Good skills:

• Focus on one domain — "PostgreSQL best practices" rather than "all databases"
• Give actionable instructions — Tell the agent what to do, not just what something is
• Include examples — Show patterns the agent should follow
• Declare tools — Use MCP servers to give the agent live capabilities

Quick start

Scaffold a new skill:

mkdir my-skill && cd my-skill
shipables init

The init wizard creates all required files. See shipables init for details.

Skill directory structure

A complete skill looks like this:

my-skill/
├── SKILL.md              # Agent instructions (required)
├── shipables.json        # Package manifest (required)
├── .shipablesignore      # Files to exclude from publishing
├── scripts/              # Executable scripts (optional)
│   ├── setup.sh
│   └── validate.sh
├── references/           # Supplementary docs (optional)
│   ├── api-reference.md
│   └── examples.md
└── assets/               # Images, diagrams (optional)
    └── architecture.png