Sync Workflow

​

Sync Skills to Agents

better-skills sync

​

How Sync Works

1. Check authentication - Verifies valid session
2. Load skills - Fetches all skills from your vaults (paginated)
3. Install skills - Writes each skill to agent directories
4. Prune stale skills - Removes skills deleted from server
5. Update install lock - Records installed skill state

​

Supported Agents

​

Environment Variables

• XDG_CONFIG_HOME - Base config directory (default: ~/.config)
• CODEX_HOME - Codex home directory (default: ~/.codex)
• CLAUDE_CONFIG_DIR - Claude config directory (default: ~/.claude)

​

Skill Installation Format

~/.config/opencode/skills/
└── personal__typescript-best-practices/  # Vault-scoped folder name
    ├── SKILL.md                          # Rendered markdown
    └── resources/
        ├── config.json
        └── example.ts

​

Install Lock

~/.config/better-skills/install-lock.json

• Which skills are installed
• Skill UUIDs for each folder
• Last sync timestamp

• Pruning - Remove skills deleted from server
• Unmanaged detection - Find manually-added skills
• Sync verification - Detect drift between server and local

​

Configure Agents

better-skills config

​

Configuration Storage

~/.config/better-skills/config.json

{
  "version": 1,
  "agents": ["opencode", "claude-code", "cursor"]
}

​

First-Time Setup

1. Interactive mode - Prompts for agent selection
2. Non-interactive mode - Uses all agents by default

​

Installing Private Skills

better-skills sync

​

Vault Types

• personal - Your private vault (read-write)
• enterprise - Team vaults you have access to (read-only or read-write)
• system_default - Public Better Skills library (read-only)

​

Access Control

1. Authenticates with your session
2. Fetches only skills you have permission to access
3. Installs all accessible skills to agent directories

​

Backup Local Skills

better-skills backup

​

Backup Structure

/tmp/better-skills-backup-{timestamp}/
├── raw/                    # Original files (vault__slug format)
│   ├── personal__my-skill/
│   └── team__api-guide/
├── work/                   # Ready for create/update (slug format)
│   ├── my-skill/
│   └── api-guide/
└── metadata.json           # Backup manifest

​

Work Directory

cd /tmp/better-skills-backup-{timestamp}/work/my-skill
better-skills validate .
better-skills create --from .

• SKILL.md - Original markdown
• resources/ - All resource files
• .resource-ids.json - Resource UUID mapping (for validation)

​

Backup Flags

• --source <dir> - Source directory to backup (overrides agent config)
• --out <dir> - Output directory (default: /tmp/better-skills-backup-{timestamp})
• --agent <agent> - Specific agent(s) to backup (repeatable)

​

Use Cases

better-skills backup
# Backup created, review work/ before re-importing

better-skills backup --agent opencode
cd /tmp/better-skills-backup-*/work/deleted-skill
better-skills create --from .

​

Validate Skills

better-skills validate ./my-skill

​

Validation Checks

1. SKILL.md exists - Required markdown file
2. Frontmatter - Contains name and description
3. Resource mentions - All [[resource:new:path]] have matching files
4. Unused resources - Warns about unreferenced files
5. External links - Validates [[skill:uuid]] format

​

Resource Mention Validation

• Path must exist in resources/ directory
• Path cannot escape resources directory (no ../)
• Path must be relative

• Uses .resource-ids.json to distinguish internal vs external
• Internal resources must exist in resources/
• External resources are not validated locally

​

Exit Code

• 0 - Validation passed (warnings allowed)
• 1 - Validation failed (errors present)

better-skills validate ./skill && \
  better-skills update my-skill --from ./skill

​

Rewrite Resource Links

better-skills rewrite-links ./my-skill

​

What Gets Rewritten

• Local file links - [config](resources/config.json) → [[resource:new:config.json]]
• Local relative paths - ./resources/setup.sh → [[resource:new:setup.sh]]
• Markdown references - References to files in resources/

​

Output Format

◆  link rewrite complete
●  5 link(s) rewritten in 2 file(s)
●  - SKILL.md: 3
●  - resources/guide.md: 2
●  scanned 4 file(s)

​

Dry Run Mode

better-skills rewrite-links ./my-skill --dry-run

◆  dry run complete
●  5 link(s) would be rewritten in 2 file(s)
●  - SKILL.md: 3
●  - resources/guide.md: 2

​

Use Case

# Clone skill
better-skills clone my-skill
cd my-skill

# Edit files with normal markdown links
echo '[See config](resources/config.json)' >> SKILL.md

# Rewrite to UUID format before update
better-skills rewrite-links . --dry-run
better-skills rewrite-links .

# Validate and update
better-skills validate .
better-skills update my-skill --from .

​

Limitations

• Only processes markdown files (.md, .mdx)
• Does not rewrite skill links (use UUIDs manually)
• Preserves external URLs unchanged

​

Workflow Examples

​

Daily Sync Workflow

# Authenticate once
better-skills login

# Configure agents (first time)
better-skills config

# Sync regularly
better-skills sync

​

Create and Publish Workflow

# Create local skill
mkdir my-skill
cd my-skill
cat > SKILL.md << 'EOF'
---
name: My Skill
description: A useful skill
---

# My Skill

Content here.
EOF

# Validate
better-skills validate .

# Create on server
better-skills create --from .

# Sync to agents
better-skills sync

​

Clone, Edit, Update Workflow

# Clone skill
better-skills clone my-skill
cd my-skill

# Edit SKILL.md and resources
vim SKILL.md
vim resources/config.json

# Rewrite local links
better-skills rewrite-links .

# Validate changes
better-skills validate .

# Update on server
better-skills update my-skill --from .

# Sync to agents
better-skills sync

​

Backup and Restore Workflow

# Backup all local skills
better-skills backup

# Review backup
cd /tmp/better-skills-backup-*/work
ls -la

# Restore a skill
cd my-skill
better-skills validate .
better-skills create --from .

​

Command Reference Summary

​

Troubleshooting

​

Sync Fails with Authentication Error

better-skills login
better-skills sync

​

Skills Not Appearing in Agent

1. Verify agent configuration:
   better-skills config
   
2. Check install lock:
   cat ~/.config/better-skills/install-lock.json
   
3. Check agent directory:
   ls ~/.config/opencode/skills
   

​

Validation Errors

better-skills validate ./my-skill
# Fix errors shown
better-skills validate ./my-skill

​

Stale Skills After Deletion

better-skills sync
# Output: removed 2 skill(s) no longer on server

​

Next Steps