Skip to main content
A skill is the core knowledge unit in Better Skills. Each skill packages agent instructions, references, scripts, and assets into a portable, version-controlled folder structure.

​
What is a Skill?

Skills are designed for AI agents, not human documentation readers. They store:
  • Agent instructions - how to route and execute tasks
  • Reference documentation - API guides, architecture docs, code patterns
  • Scripts and code samples - runnable examples and utilities
  • Assets - diagrams, config templates, etc.
Every skill is stored in the database with its full SKILL.md content and associated resource files.

​
SKILL.md Format

Each skill begins with a SKILL.md file containing:
  1. YAML frontmatter - structured metadata
  2. Markdown body - agent instructions and routing logic

​
Example: Real Skill from Better Skills

---
name: better-skills
description: |
  Index and route better-skills vault operations from the CLI.
  Trigger when users ask to manage better-skills or a skill vault
  (create, edit, delete, disable, remove, search, import, clone, link, sync, backup, onboard).
  Do not use when asked to use a skill.
---

# better-skills

## Flows

| Trigger                                                             | Flow                                              |
| ------------------------------------------------------------------- | ------------------------------------------------- |
| GitHub URL, skills.sh link, npm URL, blog post, any external source | \[[resource:new:references/import-skill.md]]       |
| User wants to create/write a new skill from scratch                 | \[[resource:new:references/create-skill.md]]       |
| User wants to update/edit an existing vault skill                   | \[[resource:new:references/edit-skill.md]]         |
| Asked to onboard, Existing local skill folders not yet in the vault | \[[resource:new:references/onboard-skills.md]]     |

## Shared references

- Authoring guidelines → \[[resource:new:references/authoring.md]]
- Mention linking → \[[resource:new:references/linking.md]]

## Rules

1. Every resource file must have a `\[[resource:new:<path>]]` mention — either
   in SKILL.md or in another resource. Never run create/update until validate exits clean.
2. Never use bare markdown links for internal resource references.
3. Always read authoring guidelines before creating or editing a skill.
The example above uses escaped mentions (\[[resource:new:...]]) for documentation purposes. In actual skill files, you use unescaped mentions to create real links.

​
Skill Properties

​
Database Fields

FieldTypeDescription
idUUIDPrimary key
owner_vault_idUUIDVault that owns this skill
slugtextURL-safe identifier (unique per vault)
nametextDisplay name
descriptiontextSummary text
skill_markdowntextFull SKILL.md content
frontmatterJSONBParsed YAML metadata from SKILL.md
metadataJSONBApplication-managed data (search index, hashes)
is_defaultbooleanTrue for system-provided template skills
source_urltextOptional origin URL
source_identifiertextOptional external ID
created_attimestampCreation time
updated_attimestampLast modification time

​
Frontmatter vs Metadata

Frontmatter

Author-defined structured data parsed from the YAML header in SKILL.md.Examples:
  • name, description
  • metadata.version
  • Custom tags or categories

Metadata

Application-owned enrichment data managed by Better Skills.Examples:
  • Search indexes
  • Content hashes
  • Diagnostic flags
  • Ranking scores

​
isDefault Skills

Skills marked with is_default: true are canonical templates provided by Better Skills:
  • Stored in the shared system_default vault
  • Read-only for normal users
  • Seeded from resources/default-skills/
  • Synced via bun run sync-default-skills
  • Include examples like better-skills, turborepo, next-best-practices
Default skills cannot be edited or deleted through normal user operations. They serve as stable, shared templates for all users.

​
Vault Ownership

Every skill belongs to exactly one vault via owner_vault_id:
  • Personal vaults: Private skills, writable by owner
  • Enterprise vaults: Shared team skills, writable by owner/admin
  • System default vault: Read-only template skills
Slug uniqueness is enforced per vault, so acme/my-skill and personal/my-skill can coexist.
The legacy owner_user_id field exists for backward compatibility but vault ownership is canonical.

​
Resources

Skills contain multiple resource files:
  • references/ - markdown documentation files
  • scripts/ - code samples and utilities
  • assets/ - images, configs, templates
See Skill Graph for how resources are represented as sub-nodes in the graph.

​
Next Steps

Vaults

Learn about vault types and permissions

Skill Graph

Understand the graph data model

Mentions

Link skills and resources with markdown mentions

Build docs developers (and LLMs) love

Get started for freeTalk to us