Skills

Skills are reusable knowledge bundles that extend what the AI can do. Each skill contains instructions, optional scripts, reference documents, and assets that help the AI perform specialized tasks.

What Are Skills?

Think of skills as teaching the AI new capabilities:

Instructions — Step-by-step guidance for specific tasks
Scripts — Executable code the AI can run
References — Documentation and examples to follow
Assets — Templates, configs, and other resources

Skills follow the open Agent Skills specification, making them portable across compatible tools.

Skills vs Custom Agents

Feature	Skills	Custom Agents
Purpose	Add specialized knowledge	Create AI personas
Contains	Instructions, scripts, references	System prompt, tool access
Scope	Available to all agents	Single agent configuration
Invocation	Automatic when relevant	Manual mode switch
Best for	Domain expertise, workflows	Role-specific behavior

Use together: Create a "Code Reviewer" agent that uses your "security-audit" and "performance-check" skills.

Creating a Skill

Open Skills Settings

Go to Settings → Skills tab.

Click "Create Skill"

Fill in the skill details:

Field	Description	Example
Name	Lowercase with hyphens	`api-designer`
Description	What the skill does	"Designs RESTful APIs following best practices"
Scope	Where it's available	Global (everywhere) or Project (current only)
Instructions	Detailed markdown guidance	See below

Write instructions

Provide clear, detailed instructions in markdown:

# API Designer Skill

Use this skill when designing RESTful APIs.

## When to Use
- User asks to design an API
- User needs endpoint structure
- User wants API documentation

## Guidelines
1. Follow REST conventions
2. Use consistent naming (kebab-case for URLs)
3. Include proper HTTP methods
4. Define clear request/response schemas

## Example
For a user management API:
- GET /users - List all users
- POST /users - Create user
- GET /users/{id} - Get specific user

Save and use

Click Create. The skill is immediately available to the AI in all conversations.

Skill Structure

A skill is a folder containing a SKILL.md file and optional subdirectories:

my-skill/
├── SKILL.md           # Required - metadata and instructions
├── scripts/           # Optional - executable code
│   ├── analyze.py
│   └── validate.js
├── references/        # Optional - documentation
│   ├── guidelines.md
│   └── examples.md
└── assets/            # Optional - templates and resources
    ├── template.html
    └── config.yaml

SKILL.md Format

---
name: my-skill
description: Brief description of what this skill does
license: MIT
compatibility: Requires Python 3.8+
metadata:
  author: Your Name
  version: "1.0"
---

# Skill Instructions

Detailed markdown instructions for the AI...

## When to Use
- Situation 1
- Situation 2

## How to Use
1. Step one
2. Step two
3. Step three

## Examples
...

Naming Rules

Lowercase letters, numbers, and hyphens only
1-64 characters
Cannot start or end with a hyphen
Must match the folder name

The skill name must exactly match the folder name. A skill named api-designer must be in a folder called api-designer/.

Adding Scripts

Scripts let the AI execute code as part of the skill workflow.

Create the scripts folder

Inside your skill folder, create a scripts/ directory.

Add your scripts

Add any executable files:

Python scripts (.py)
JavaScript files (.js)
Shell scripts (.sh)
Any other executable

Reference in instructions

Tell the AI when and how to use the scripts:

## Running Analysis

To analyze code quality, run:
python scripts/analyze.py --file <path>

Adding References

References provide documentation the AI can consult.

references/
├── coding-standards.md    # Team coding guidelines
├── api-spec.md            # API specifications
└── troubleshooting.md     # Common issues and solutions

Reference these in your instructions:

## Guidelines

Follow the coding standards in `references/coding-standards.md`.

When encountering errors, consult `references/troubleshooting.md`.

Adding Assets

Assets are templates, configurations, and other resources.

assets/
├── component-template.tsx   # React component template
├── test-template.spec.ts    # Test file template
└── config.example.json      # Configuration example

The AI can read and use these as starting points:

## Creating Components

Use the template in `assets/component-template.tsx` as a starting point.

Using Skills

Once created, skills are automatically available in all conversations. Simply ask the AI naturally:

You: Design a REST API for a blog platform

AI: [Recognizes api-designer skill is relevant]
    I'll design a RESTful API following best practices...

You: Use the code-review skill to check this file

AI: [Loads code-review skill instructions]
    I'll review this code following the skill guidelines...

The AI automatically:

Recognizes which skills are relevant
Loads the full instructions when needed
Follows the skill's guidance
Uses scripts and references as specified

Skill Directories

Sidekick reads skills from the following directories:

Global Skills

Available in all projects. Place skills in any of these locations:

Directory
`~/.sidekick/skills/`
`~/.cursor/skills/`
`~/.claude/skills/`
`~/.codex/skills/`

Project Skills

Available only in the current project. Place skills in any of these locations within your project root:

Directory
`.sidekick/skills/`
`.cursor/skills/`
`.claude/skills/`
`.codex/skills/`

Sidekick automatically discovers skills from all these directories, making your skills cross-compatible with other tools.

Managing Skills

View All Skills

Go to Settings → Skills to see all discovered skills with:

Name and description
Scope (Global/Project) and source
Indicators for scripts, references, and assets

Edit a Skill

Find the skill in Settings → Skills
Click the Edit (pencil) icon
Modify the description or instructions
Click Update

Or click Open Folder to edit files directly.

Delete a Skill

Find the skill in Settings → Skills
Click the Delete (trash) icon
Confirm deletion

Deleting a skill removes the entire folder and all its contents.

---
name: code-review
description: Reviews code for quality, security, and best practices
---

# Code Review Skill

## When to Use
- User asks for code review
- User wants feedback on implementation
- User asks about code quality

## Review Checklist
1. **Security**: Check for vulnerabilities (injection, XSS, etc.)
2. **Performance**: Identify inefficient patterns
3. **Readability**: Assess naming and structure
4. **Testing**: Verify test coverage
5. **Documentation**: Check for clear comments

## Output Format
Provide feedback as:
- Critical issues (must fix)
- Suggestions (should consider)
- Positive observations (done well)

Documentation Generator Skill

---
name: doc-generator
description: Generates documentation from code
compatibility: Works with TypeScript, JavaScript, Python
---

# Documentation Generator

## When to Use
- User asks to document code
- User needs README generation
- User wants API documentation

## Process
1. Read the source files
2. Identify exports, functions, classes
3. Extract JSDoc/docstrings if present
4. Generate markdown documentation

## Templates
Use templates in `assets/` for consistent formatting:
- `assets/readme-template.md` - README structure
- `assets/api-template.md` - API documentation

Test Writer Skill

---
name: test-writer
description: Writes comprehensive unit and integration tests
---

# Test Writer Skill

## When to Use
- User asks for tests
- User wants test coverage
- User needs test examples

## Guidelines
1. Follow existing test patterns in the project
2. Test happy path and edge cases
3. Use descriptive test names
4. Mock external dependencies

## Scripts
Run `scripts/analyze-coverage.sh` to check current coverage before writing new tests.

Best Practices

Write Clear Instructions

Be specific about when to use the skill
Provide step-by-step guidance
Include examples of expected behavior

Keep Skills Focused

One skill = one capability
Don't create "do everything" skills
Combine multiple skills for complex tasks

Use All Components

Scripts for automation
References for detailed documentation
Assets for templates and examples

Organize by Project

Global skills for universal workflows
Project skills for project-specific patterns