Skills Configuration Guide

This guide explains how to create and configure skills in Vorno.

CLI-first workflow (recommended): Use vorno-cli skill ... commands instead of editing SKILL.md files directly.

• vorno-cli skill --help
• Canonical command reference: vorno-cli.md

What Are Skills?

Skills are specialized instructions that extend Claude’s capabilities for specific tasks. They use the exact same SKILL.md format as the Claude Code SDK - making skills fully compatible between systems.

Key points:

• Skills are invoked via slash commands (e.g., /commit, /review-pr)
• Skills can be automatically triggered by file patterns (globs)
• Skills can pre-approve specific tools to run without prompting
• The SKILL.md format is identical to what Claude Code uses internally

Same Format as Claude Code SDK

Vorno uses the identical SKILL.md format as the Claude Code SDK. This means:

1. Format compatibility: Any skill written for Claude Code works in Vorno
2. Same frontmatter fields: name, description, globs, alwaysAllow, requiredSources
3. Same content structure: Markdown body with instructions for Claude

What Vorno adds:

• Visual icons: Display custom icons in the UI for each skill
• Workspace organization: Skills are scoped to workspaces
• UI management: Browse, edit, and validate skills through the interface

Skill Precedence

When a skill is invoked (e.g., /commit):

1. Workspace skill checked first - If ~/.craft-agent/workspaces/{id}/skills/commit/SKILL.md exists, it’s used
2. SDK skill as fallback - If no workspace skill exists, the built-in SDK skill is used

This allows you to:

• Override SDK skills - Create a workspace skill with the same slug to replace built-in behavior
• Extend SDK skills - Reference SDK behavior in your custom skill and add workspace-specific instructions
• Create new skills - Add entirely new skills not in the SDK

Skill Storage

Skills are stored as folders:

~/.craft-agent/workspaces/{workspaceId}/skills/{slug}/
├── SKILL.md          # Required: Skill definition (same format as Claude Code SDK)
├── icon.svg          # Recommended: Skill icon for UI display
├── icon.png          # Alternative: PNG icon
└── (other files)     # Optional: Additional resources

SKILL.md Format

The format is identical to Claude Code SDK skills:

---
name: "Skill Display Name"
description: "Brief description shown in skill list"
globs: ["*.ts", "*.tsx"]     # Optional: file patterns that trigger skill
alwaysAllow: ["Bash"]        # Optional: tools to always allow
requiredSources:             # Optional: sources to auto-enable on invocation
  - linear
---

# Skill Instructions

Your skill content goes here. This is injected into Claude's context
when the skill is active.

## Guidelines

- Specific instructions for Claude
- Best practices to follow
- Things to avoid

## Examples

Show Claude how to perform the task correctly.

Metadata Fields

name (required)

Display name for the skill. Shown in the UI and skill list.

description (required)

Brief description (1-2 sentences) explaining what the skill does.

globs (optional)

Array of glob patterns. When a file matching these patterns is being worked on, the skill may be automatically suggested or activated.

globs:
  - "*.test.ts"           # Test files
  - "*.spec.tsx"          # React test files
  - "**/__tests__/**"     # Test directories

alwaysAllow (optional)

Array of tool names that are automatically allowed when this skill is active. Useful for skills that require specific tools without prompting.

alwaysAllow:
  - "Bash"                # Allow bash commands
  - "Write"               # Allow file writes

requiredSources (optional)

Array of source slugs to auto-enable when this skill is invoked. When a user mentions the skill, the listed sources are enabled for the session before the agent starts — so tools from those sources are available from the first turn.

Sources must exist in the workspace and be authenticated. Unauthenticated or missing sources are silently skipped (the existing runtime auto-enable handles them as a fallback).

requiredSources:
  - linear               # Auto-enable Linear source
  - github               # Auto-enable GitHub source

Creating a Skill

1. Create the skill directory

mkdir -p ~/.craft-agent/workspaces/{ws}/skills/my-skill

2. Write SKILL.md

---
name: "Code Review"
description: "Review code changes for quality, security, and best practices"
globs: ["*.ts", "*.tsx", "*.js", "*.jsx"]
---

# Code Review Skill

When reviewing code, focus on:

## Quality Checks
- Consistent code style
- Clear naming conventions
- Appropriate abstractions

## Security Checks
- Input validation
- Authentication/authorization
- Sensitive data handling

## Best Practices
- Error handling
- Performance considerations
- Test coverage

3. Add an icon (IMPORTANT)

Every skill should have a visually relevant icon. This helps users quickly identify skills in the UI.

Icon requirements:

• Filename: Must be icon.svg, icon.png, icon.jpg, or icon.jpeg
• Format: SVG preferred (scalable, crisp at all sizes)
• Size: For PNG/JPG, use at least 64x64 pixels

How to get an icon:

1. Search online icon libraries:

   • Heroicons - MIT licensed
   • Feather Icons - MIT licensed
   • Simple Icons - Brand icons (git, npm, etc.)

2. Use WebFetch to download:

   # Find an appropriate icon URL and download it
   WebFetch to get SVG content, then save to icon.svg

3. Match the skill’s purpose:

   • Git/commit skill → git icon or commit icon
   • Test skill → checkmark or test tube icon
   • Deploy skill → rocket or cloud icon
   • Review skill → magnifying glass or eye icon

4. Validate the skill

IMPORTANT: Always validate after creating or editing a skill:

skill_validate({ skillSlug: "my-skill" })

This validates:

• Slug format (lowercase, alphanumeric, hyphens only)
• SKILL.md exists and is readable
• YAML frontmatter is valid
• Required fields present (name, description)
• Content is non-empty
• Icon format (if present)

Example Skills

Commit Message Skill

---
name: "Commit"
description: "Create well-formatted git commit messages"
alwaysAllow: ["Bash"]
---

# Commit Message Guidelines

When creating commits:

1. **Format**: Use conventional commits
   - `feat:` New feature
   - `fix:` Bug fix
   - `docs:` Documentation
   - `refactor:` Code refactoring
   - `test:` Adding tests

2. **Style**:
   - Keep subject line under 72 characters
   - Use imperative mood ("Add feature" not "Added feature")
   - Explain why, not what (the diff shows what)

3. **Co-authorship**:
   Always include: `Co-Authored-By: Claude <noreply@anthropic.com>`

Recommended icon: Git commit icon from Heroicons or Simple Icons

Team Standards Skill

---
name: "Team Standards"
description: "Enforce team coding conventions and patterns"
globs: ["src/**/*.ts", "src/**/*.tsx"]
---

# Team Coding Standards

## File Organization
- One component per file
- Co-locate tests with source files
- Use barrel exports (index.ts)

## Naming Conventions
- Components: PascalCase
- Hooks: camelCase with `use` prefix
- Constants: SCREAMING_SNAKE_CASE

## Import Order
1. External packages
2. Internal packages (@company/*)
3. Relative imports

Recommended icon: Clipboard list or checklist icon

Skill with Required Sources

---
name: "Linear Triage"
description: "Triage and prioritize Linear issues"
requiredSources:
  - linear
---

# Linear Triage

When triaging issues:
1. List unassigned issues from the current sprint
2. Categorize by severity
3. Suggest assignees based on expertise

Recommended icon: Kanban board or list icon

When this skill is invoked, the linear source is automatically enabled for the session — no manual toggle needed.

Overriding SDK Skills

To customize a built-in SDK skill like /commit:

1. Create ~/.craft-agent/workspaces/{ws}/skills/commit/SKILL.md
2. Write your custom instructions
3. Add an icon
4. Run skill_validate({ skillSlug: "commit" })

Your skill will be used instead of the SDK’s built-in version.

This is useful for:

• Adding team-specific commit message formats
• Enforcing project-specific coding standards
• Customizing review criteria for your codebase

Best Practices

1. Be specific: Give Claude clear, actionable instructions
2. Include examples: Show the expected output format
3. Set boundaries: Explain what NOT to do
4. Keep focused: One skill = one specific task or domain
5. Add a relevant icon: Makes skills easily identifiable in the UI
6. Always validate: Run skill_validate after creating or editing

Troubleshooting

Skill not loading:

• Check slug format (lowercase, alphanumeric, hyphens only)
• Verify SKILL.md exists and is readable
• Run skill_validate for detailed errors

Skill not triggering:

• Check glob patterns match your files
• Verify skill is in correct workspace

Icon not showing:

• Use supported formats: svg, png, jpg, jpeg
• File must be named icon.{ext} (not my-icon.svg)
• Check icon file is not corrupted
• For SVG, ensure valid XML structure