Skip to main content
Skills are reusable instruction sets stored in your Better Skills vault. This guide covers creating skills from scratch using the CLI and web interface.

​
Folder Structure

Every skill follows a standard directory layout: 
skill-name/
├── SKILL.md              # Required: metadata + core instructions (<500 lines)
├── references/           # Supplementary context (schemas, cheatsheets, guides)
├── scripts/              # Executable code designed as tiny single-purpose CLIs
└── assets/               # Templates or static files used in output

​
Structure Guidelines

  • SKILL.md acts as the “brain”: navigation + high-level procedures only
  • references/ for contextual docs loaded just-in-time
  • scripts/ for deterministic helpers (not library code)
  • assets/ for output templates not intended for context loading
  • Use relative paths with forward slashes regardless of OS
  • Prefer flat references over deep nesting (e.g. references/schema.md over references/db/schema.md)

​
Writing SKILL.md

Every SKILL.md requires frontmatter with name and description: 
---
name: skill-name
description: |
  Creates React components with Tailwind CSS. Use when user wants to update
  component styles or UI logic. Do not use for Vue, Svelte, or vanilla CSS projects.
---

​
Frontmatter Rules

  • name: 1-64 characters, lowercase letters, numbers, hyphens only (no consecutive hyphens)
  • Name must exactly match the parent directory name
  • description: max 1024 characters, written in third person
  • Include realistic user phrasings (aliases, common variants)
  • Include negative triggers: what should NOT trigger this skill

​
Description Best Practices

Good: “Creates React components with Tailwind CSS. Use when user wants to update component styles or UI logic. Do not use for Vue, Svelte, or vanilla CSS projects.”
Bad: “React skills.” (too vague, no trigger context, no negative triggers)
Keep SKILL.md under 500 lines by moving detailed workflows to reference files.

​
Using the CLI

Create skills from your local filesystem using the better-skills create command.
1

Gather Requirements

Before creating, clarify:
  1. Name: What should the skill be called? (lowercase, letters/numbers/hyphens, 1-64 chars)
  2. Purpose: What does this skill do? What problem does it solve?
  3. Triggers: When should this skill activate? What user phrases or requests should route here?
  4. Negative triggers: What should NOT trigger this skill?
  5. Scope: What reference files are needed? (guides, schemas, cheatsheets, scripts, templates)
2

Check for Related Skills

Search existing vault skills to identify potential cross-links:
better-skills list --all
Note any relevant UUIDs for cross-linking later.
3

Create the Folder Structure

Create the skill folder in your current directory (never use tmp directories):
mkdir -p ./skill-name/references
Write SKILL.md with frontmatter and routing sections. Add reference files under references/, scripts/, or assets/.
4

Add Resource Mentions

Every resource file must be referenced using mention syntax. In SKILL.md or other resource files, add:
[[resource:new:references/guide.md]]
[[resource:new:scripts/setup.ts]]
[[resource:new:assets/template.html]]
See Markdown Mentions for full syntax details.
5

Validate Before Creating

Run validation to catch issues before upload:
better-skills validate "./skill-name"
Validation is strict — any warning is treated as a failure. Fix all issues before proceeding.
6

Create the Skill

Upload the skill to your vault:
better-skills create --from "./skill-name" [--slug custom-slug]
The CLI resolves [[resource:new:...]] mentions to UUID-based references during creation.
7

Sync and Confirm

Download the created skill to verify:
better-skills sync
better-skills get <slug-or-uuid>
Start a new session so the updated skill catalog is reloaded.

​
Slug and Naming Conventions

The --slug parameter is optional. If omitted, Better Skills generates a slug from the skill name.

​
Slug Rules

  • Lowercase letters, numbers, and hyphens only
  • No consecutive hyphens
  • Must be unique within your vault
  • Used in skill URLs and CLI commands

​
Example

# Name: react-tailwind-components
# Auto-generated slug: react-tailwind-components

better-skills create --from "./react-tailwind-components"

# Custom slug
better-skills create --from "./react-tailwind-components" --slug react-tw

​
Creating Skills via Web UI

You can also create skills through the Better Skills web console:
  1. Navigate to your vault dashboard
  2. Click Create Skill
  3. Fill in the skill name and description
  4. Add resource files through the web editor
  5. Use [[resource:new:path]] mentions to link resources
  6. Save to create the skill
The web UI validates frontmatter and mention syntax before saving.

​
Next Steps

Skill Resources

Learn how to add and organize reference files, scripts, and assets

Markdown Mentions

Master mention syntax for linking skills and resources

Build docs developers (and LLMs) love

Get started for freeTalk to us