Skill Commands - Better Skills

The Better Skills CLI provides comprehensive commands for discovering, creating, updating, and managing skills.

List Skills

List skills from your vaults with optional filtering:

better-skills list

Output Format

3 skill(s) matching "typescript":

[1] TypeScript Best Practices
    Modern TypeScript patterns for type safety and maintainability
    vault: personal (personal)
    id: 123e4567-e89b-12d3-a456-426614174000 | slug: typescript-best-practices | updated: 2024-03-15

[2] TypeScript Testing
    Unit testing strategies for TypeScript projects
    vault: team (enterprise) [read-only]
    id: 223e4567-e89b-12d3-a456-426614174001 | slug: typescript-testing | updated: 2024-03-14

[3] Advanced TypeScript
    Advanced type system features and patterns
    vault: public (system_default) [read-only] [DISABLED]
    id: 323e4567-e89b-12d3-a456-426614174002 | slug: advanced-typescript | updated: 2024-03-13

Flags

[search] - Optional search term to filter skills
--all - Show all skills without pagination limit
--limit N - Set custom limit (default: 20)

Search Skills

Perform full-text search across skill content:

better-skills search "authentication"

Output Format

found 2 skill(s) matching "authentication":

[1] OAuth Authentication (semantic 85%)
    Implement OAuth 2.0 authentication flows
    vault: personal (personal)
    id: 123e4567-e89b-12d3-a456-426614174000 | slug: oauth-auth | updated: 2024-03-15
    snippet: ...device-code flow for authentication. This provides secure...

[2] JWT Best Practices (keyword 72%)
    Security patterns for JWT token handling
    vault: team (enterprise)
    id: 223e4567-e89b-12d3-a456-426614174001 | slug: jwt-practices | updated: 2024-03-14

Match Types

semantic - Vector similarity match (higher relevance)
keyword - Full-text keyword match

Flags

<query> - Search query (required)
--limit N - Number of results (default: 5)

Get Skill Details

Fetch and display complete skill information:

better-skills get typescript-best-practices

Output Format

# TypeScript Best Practices

id: 123e4567-e89b-12d3-a456-426614174000
slug: typescript-best-practices
updated: 2024-03-15
description: Modern TypeScript patterns for type safety and maintainability
resources: examples/tsconfig.json, examples/utility-types.ts

---

# TypeScript Best Practices

This skill provides modern patterns for writing type-safe TypeScript...

[Full rendered markdown content follows]

Identifier Formats

The CLI accepts three identifier formats:

Slug - typescript-best-practices
Vault/Slug - personal/typescript-best-practices
UUID - 123e4567-e89b-12d3-a456-426614174000

Clone Skills

Clone a skill to a local directory for editing:

better-skills clone typescript-best-practices

What Gets Cloned

The clone command creates:

typescript-best-practices/
├── SKILL.md              # Original markdown (with UUID links)
├── .resource-ids.json    # Resource UUID to path mapping
└── resources/
    ├── tsconfig.json
    └── utility-types.ts

Link Context Table

After cloning, the CLI displays a context table for UUID-based links:

link context (uuid -> skill / resource):

| uuid                                 | type     | target                                    |
|--------------------------------------|----------|-------------------------------------------|
| 223e4567-e89b-12d3-a456-426614174001 | skill    | Advanced TypeScript                       |
| 323e4567-e89b-12d3-a456-426614174002 | resource | TypeScript Testing / examples/vitest.ts   |
| 423e4567-e89b-12d3-a456-426614174003 | resource | (unknown resource)                        |

This helps you understand external dependencies before editing.

Flags

<identifier> - Skill to clone (slug, vault/slug, or UUID)
--to <dir> - Target directory (default: skill slug)
--force - Overwrite existing directory if not empty

Next Steps

After cloning:

cd typescript-best-practices
# Edit SKILL.md and resources
better-skills validate .
better-skills update 123e4567-e89b-12d3-a456-426614174000 --from .

Create Skills

Create a new skill from a local directory:

better-skills create --from ./my-skill

Directory Structure

Your local directory must contain:

my-skill/
├── SKILL.md              # Skill markdown (required)
└── resources/            # Optional resources directory
    ├── config.json
    └── example.py

SKILL.md Format

---
name: My Skill Name
description: Short description for skill cards
slug: my-skill  # Optional, overridden by --slug
---

# My Skill Name

Skill content goes here.

Reference local resources:
- [[resource:new:config.json]]
- [[resource:new:example.py]]

Reference external skills:
- [[skill:123e4567-e89b-12d3-a456-426614174000]]

Resource Mentions

Use [[resource:new:path]] for local resources:

[[resource:new:config.json]] - References resources/config.json
[[resource:new:scripts/setup.sh]] - References resources/scripts/setup.sh

The CLI automatically resolves these to UUID-based links after creation.

Output

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "slug": "my-skill",
  "name": "My Skill Name"
}

Flags

--from <dir> - Source directory (required)
--slug <s> - Custom slug (overrides frontmatter)
--vault <slug|uuid> - Target vault (default: personal vault)

Update Skills

Update an existing skill from local changes:

better-skills update typescript-best-practices --from ./typescript-best-practices

Update Behavior

The update command:

Loads the local skill draft from --from directory
Resolves the target skill by identifier
Diffs resources (added, removed, modified)
Updates the skill on the server
Resolves new resource mentions if present

Resource Handling

Resources are compared by path:

Added - New files in resources/
Modified - Changed content for existing paths
Removed - Files deleted from resources/
Unchanged - Files with matching content

Output

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "slug": "typescript-best-practices",
  "name": "TypeScript Best Practices"
}

Flags

<identifier> - Skill to update (slug, vault/slug, or UUID)
--from <dir> - Source directory (required)
--slug <s> - New slug (optional)

Delete Skills

Delete a skill with confirmation:

better-skills delete typescript-best-practices

Confirmation Prompt

In interactive mode, you’ll be prompted:

◆  found TypeScript Best Practices (typescript-best-practices)
│
◆  delete TypeScript Best Practices? this cannot be undone
│  ● Yes
│  ○ No

Non-Interactive Mode

In CI/CD or non-interactive environments, use --yes:

better-skills delete my-skill --yes

Deleting a skill is permanent and cannot be undone. Skills referenced by other skills will show broken links.

Flags

<identifier> - Skill to delete (slug, vault/slug, or UUID)
--yes - Skip confirmation prompt

Check Skill References

Find which skills reference a specific skill:

better-skills references typescript-best-practices

Output Format

# skills referencing TypeScript Best Practices

- React TypeScript Guide (react-ts-guide) [direct]
- Advanced TypeScript (advanced-typescript) via examples/utility-types.ts [resource]
- Testing Patterns (testing-patterns) [direct]

Reference Kinds

direct - Skill mentions this skill in its SKILL.md
resource - Skill mentions this skill’s resources

Use Case

Check references before deleting a skill to understand impact:

better-skills references my-skill
# Review references
better-skills delete my-skill --yes

Get Unmanaged Skills

Find local skills not managed by Better Skills:

better-skills get-unmanaged-skills

Output Format

found 3 unmanaged skill(s)

OpenCode (~/.config/opencode/skills):
  custom-skill
  local-tool

Claude Code (~/.claude/skills):
  experimental-feature

This command scans configured agent directories and compares them against the install lock (~/.config/better-skills/install-lock.json).

Use Case

Identify skills that were manually created or copied:

Run get-unmanaged-skills to find local skills
Decide whether to import them to Better Skills
Use create --from to import them

Command Reference Summary

Command	Description	Key Flags
`list`	List skills with optional search	`--all`, `--limit N`
`search`	Full-text search across skills	`--limit N`
`get`	Display skill details	None
`clone`	Clone skill to local directory	`--to <dir>`, `--force`
`create`	Create skill from local directory	`--from <dir>`, `--slug <s>`, `--vault <id>`
`update`	Update skill from local changes	`--from <dir>`, `--slug <s>`
`delete`	Delete skill with confirmation	`--yes`
`references`	Show skills referencing a skill	None
`get-unmanaged-skills`	Find local unmanaged skills	None

Get Started

Core Concepts

Web Dashboard

CLI Tool

Guides

​List Skills

​Output Format

​Flags

​Search Skills

​Output Format

​Match Types

​Flags

​Get Skill Details

​Output Format

​Identifier Formats

​Clone Skills

​What Gets Cloned

​Link Context Table

​Flags

​Next Steps

​Create Skills

​Directory Structure

​SKILL.md Format

​Resource Mentions

​Output

​Flags

​Update Skills

​Update Behavior

​Resource Handling

​Output

​Flags

​Delete Skills

​Confirmation Prompt

​Non-Interactive Mode

​Flags

​Check Skill References

​Output Format

​Reference Kinds

​Use Case

​Get Unmanaged Skills

​Output Format

​Use Case

​Command Reference Summary

​Next Steps

Sync Workflow

Validation

Build docs developers (and LLMs) love

List Skills

Output Format

Flags

Search Skills

Output Format

Match Types

Flags

Get Skill Details

Output Format

Identifier Formats

Clone Skills

What Gets Cloned

Link Context Table

Flags

Next Steps

Create Skills

Directory Structure

SKILL.md Format

Resource Mentions

Output

Flags

Update Skills

Update Behavior

Resource Handling

Output

Flags

Delete Skills

Confirmation Prompt

Non-Interactive Mode

Flags

Check Skill References

Output Format

Reference Kinds

Use Case

Get Unmanaged Skills

Output Format

Use Case

Command Reference Summary

Next Steps