Creating Skills

Quick start

spm create my-skill
cd my-skill
# Edit SKILL.md
spm validate .
spm link .

Skill structure

A skill is a directory with one file:

my-skill/
└── SKILL.md      # Everything: metadata + instructions

That's it. Skills are not code — they're structured instructions with YAML frontmatter that any AI model can understand.

SKILL.md

A single file containing YAML frontmatter (machine-readable metadata) and a Markdown body (instructions for the AI model).

Frontmatter

Every SKILL.md begins with YAML frontmatter that declares what the skill does, when to use it, and what permissions it needs:

---
name: my-skill
version: 1.0.0
author: your-name
license: MIT
description: "Short description for humans"
language: en
 
trigger:
  description: "When to use this skill (read by the AI model)"
  tags: [keyword1, keyword2]
  priority: 50
 
security:
  permissions: []
 
compatibility:
  min_context_tokens: 1000
  requires: []
  models: []
 
---

See the full frontmatter specification for all fields.

Body structure with XML tags

Skillbase follows Anthropic's prompt engineering best practices for structuring prompts. XML tags create clear semantic boundaries that models parse more reliably than markdown headers or plain text.

---
name: My Skill
version: 1.0.0
author: your-name
license: MIT
description: "Expert in [domain]. Use when [trigger conditions]."
 
trigger:
  description: "Use when [trigger conditions]"
  tags: [domain, specific]
  priority: 50
---
 
<context>
Expert in [domain]. This skill exists because [problem] — it solves [challenge]
by bringing [specific expertise].
</context>
 
<instructions>
1. Step 1: [action]
2. Step 2: [action]
3. Step 3: [action]
</instructions>
 
<examples>
<example>
<input>User asks: "..."</input>
<output>Model responds with: ...</output>
</example>
</examples>

Custom XML tags

Skillbase does not enforce a fixed set of tags. Use any semantically meaningful XML tags that fit your skill's domain — this follows the same principle from Anthropic's documentation: "You can use any tag names... as long as you're consistent." Custom tags help the model distinguish between different types of instructions:

<stack>
- React 18+ / Next.js 14+ App Router
- Tailwind CSS v4 + shadcn/ui
- TypeScript always
</stack>
 
<web3_patterns>
Every wallet interaction must handle these states:
1. disconnected
2. wrong network
3. pending wallet signature
4. confirmed / failed
</web3_patterns>
 
<avoid>
- useEffect for data fetching
- any type — use unknown + narrowing
- inline styles
</avoid>

Choose tag names that describe the content's purpose. The model uses tag names as semantic context for how to apply the instructions.

Common tags

The table below lists tags we've found effective. None are mandatory — use what makes sense for your skill.

Writing tips

• Use XML tags — they create clear boundaries that models follow more reliably than markdown headers or plain text.
• Be specific — name exact libraries, APIs, file formats. The model follows literally.
• Use positive framing — "Always validate inputs" works better than "Don't skip validation".
• Include motivation — "Use pooling (keeps resources predictable)" helps the model generalize.
• Add 2-3 examples — cover a typical case and an edge case.
• Keep it concise — every token counts against the context budget.

Private knowledge

Skills can carry proprietary knowledge that doesn't exist on the internet — internal processes, compliance rules, deployment pipelines. This knowledge is loaded at runtime, never sent to model training data. Deploy a private registry to keep everything behind your firewall.

Validate

Always validate before installing:

spm validate ./my-skill

This checks frontmatter schema compliance, required fields, name format, and semver validity.

Install locally

spm link ./my-skill
spm list
spm info my-skill

The MCP server picks up changes automatically on the next skill_list call.

Publish

See Registry & Publishing for publishing to a remote registry.

The registry automatically scans skill content for prompt injection patterns and other security threats during publish. Skills with dangerous patterns may be blocked or flagged for manual review.