Skip to main content

​
Quickstart

Get started with Better Skills in under 5 minutes. This guide walks you through installing the CLI, authenticating, and syncing your first skill.
Better Skills requires an account. The CLI will open your browser for device flow authentication.

​
Prerequisites

  • Operating System: macOS (Darwin) or Linux
  • Architecture: x64 (x86_64/amd64) or arm64 (aarch64)
  • Shell: bash or compatible
  • Internet Connection: Required for installation and authentication

​
Installation

1

Run the Installer

Install the Better Skills CLI with a single command:
curl -fsSL https://better-skills.dev/install | bash
The installer will:
  • Detect your OS and architecture
  • Download the latest CLI binary from GitHub releases
  • Install to ~/.local/bin/better-skills
  • Configure the wrapper script with the default server URL
The installer defaults to $HOME/.local/bin. Make sure this directory is in your PATH.
2

Verify Installation

Check that the CLI is installed and accessible:
better-skills --version
You should see output like:
better-skills v0.1.0
If you see command not found, add ~/.local/bin to your PATH:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
(Use ~/.zshrc for Zsh)
3

Check Server Health

Verify connectivity to the Better Skills server:
better-skills health
A successful response confirms the CLI can reach the API.

​
Authentication

Better Skills uses device flow authentication for secure CLI access.
1

Start Login

Initiate the login process:
better-skills login
The CLI will:
  1. Request a device code from the server
  2. Display a verification URL
  3. Automatically open your browser to the authorization page
  4. Show a user code (e.g., ABCD-EFGH)
2

Authorize in Browser

If the browser doesn’t open automatically, manually visit the URL shown in the terminal.
  1. Enter the displayed user code when prompted
  2. Sign in or create a Better Skills account
  3. Authorize the CLI application
The CLI polls the server every few seconds until you complete authorization.
3

Confirm Success

Once authorized, the CLI will:
  • Receive and store your access token
  • Display your account email/name
  • Save the session to ~/.better-skills/session.json
✓ login successful
logged in as user@example.com
session saved to /home/user/.better-skills/session.json
4

Verify Identity

Check your current authentication status:
better-skills whoami
Output:
email: user@example.com
name: Your Name

​
Sync Your First Skill

Now that you’re authenticated, sync your vault skills to your local environment.
1

Run Sync

Sync all enabled vault skills to .agents/skills/ directories:
better-skills sync
The CLI will:
  1. Fetch all skills from your personal and enterprise vaults
  2. Install each skill to .agents/skills/<vault-slug>/<skill-slug>/
  3. Create SKILL.md and resource files
  4. Write a .better-skills-lock.json to track synced skills
By default, sync installs skills for the OpenCode agent. Specify other agents with:
AGENTS=cursor,windsurf better-skills sync
2

Review Synced Skills

List the skills in your local environment:
ls -la .agents/skills/
You’ll see directories named by vault and skill slug, for example:
.agents/skills/
├── system-default/
│   └── better-skills/
│       ├── SKILL.md
│       └── references/
└── personal/
    └── my-skill/
        ├── SKILL.md
        └── scripts/
3

Inspect a Skill

Open a synced skill to see its structure:
cat .agents/skills/system-default/better-skills/SKILL.md
You’ll see:
  • YAML frontmatter with name, description, and routing metadata
  • Markdown instructions for agents
  • Mention links to resources: [[resource:<uuid>]]

​
List and Search Skills

Explore your vault skills with the CLI.
1

List All Skills

View skills from your enabled vaults:
better-skills list
Output:
system-default/better-skills
  Index and route better-skills vault operations from the CLI.

personal/react-patterns
  Common React patterns and best practices.
Use --limit N to cap results, or --all to fetch all skills.
2

Search by Query

Find skills by keyword:
better-skills search "react"
Search matches skill names, slugs, and descriptions.
3

Get Skill Details

View full details for a specific skill:
better-skills get system-default/better-skills
You can identify skills by:
  • Vault-scoped slug: vault-slug/skill-slug
  • Slug alone (if unique): better-skills
  • UUID: 550e8400-e29b-41d4-a716-446655440000

​
Clone and Edit a Skill

Clone a skill to a local directory for editing.
1

Clone the Skill

Download a skill to a local folder:
better-skills clone system-default/better-skills --to ./my-skill
The CLI will:
  • Create the target directory
  • Write SKILL.md with original markdown (UUID mention tokens)
  • Write all resource files
  • Generate .resource-ids.json for validation
Use --force to overwrite an existing non-empty directory.
2

Edit Locally

Make changes to SKILL.md or resource files:
cd my-skill
vim SKILL.md
Add resources, update instructions, or modify mentions.
3

Validate Changes

Before updating, validate the skill structure:
better-skills validate ./my-skill
This checks:
  • Frontmatter required fields
  • [[resource:new:...]] mention targets exist
  • All resources are referenced in SKILL.md or another resource
4

Update the Skill

Push your changes back to the vault:
better-skills update system-default/better-skills --from ./my-skill
The CLI will:
  • Resolve [[resource:new:...]] mentions to [[resource:<uuid>]]
  • Update the skill markdown and resources
  • Rebuild auto links in the skill graph
You can only update skills in vaults where you have write permissions (owner/admin role).

​
Next Steps

You’ve successfully installed Better Skills, authenticated, and synced your first skill!

Create a Skill

Learn how to create a new skill from scratch

CLI Commands

Explore all available CLI commands and options

Web Dashboard

Manage skills visually in the web app

Skill Structure

Understand the anatomy of a skill and best practices

​
Troubleshooting

The installer currently supports macOS (Darwin) and Linux only. Windows support is planned.Supported architectures:
  • x64 (x86_64, amd64)
  • arm64 (aarch64)
Common causes:
  • Network firewall blocking https://server.better-skills.dev
  • Browser did not complete authorization
  • Server is unreachable (check better-skills health)
Try:
  1. Run better-skills health to verify connectivity
  2. Check your firewall settings
  3. Manually open the verification URL in your browser
By default, sync writes to .agents/skills/ in the current working directory.The CLI detects agent configuration from:
  • AGENTS environment variable (comma-separated)
  • .better-skills.json config file
  • Interactive prompt (if TTY is available)
Override with:
AGENTS=cursor better-skills sync
Add ~/.local/bin to your PATH:
export PATH="$HOME/.local/bin:$PATH"
Add this to your shell profile (~/.bashrc, ~/.zshrc, etc.) to persist.
For more help, see the CLI Reference or open an issue on GitHub.

Build docs developers (and LLMs) love

Get started for freeTalk to us