Managing Skills

A Skill is a capability description and usage guide written for agents. This guide explains how to install, manage, and use Skills in tasks.

What is a Skill?

A Skill is not a tool itself, but rather documentation and best practices about tools. It contains:

• Capability description: What this Skill does
• Usage guide: When agents should use it and how to use it most effectively
• Reference materials: API documentation, example code, common errors and solutions

For example, a “Docker Operations” Skill tells an agent how to:

• Build images, run containers, view logs
• Handle common Docker errors
• Follow Dockerfile best practices

When you create a task, you select a Profile, and the agent automatically gets all Skills associated with that Profile.

Skill directory structure

Each Skill is a directory with a standardized structure:

skills/
  docker-ops/              # Skill ID (directory name)
    SKILL.md               # Skill metadata + content
    references/            # Optional reference materials directory
      api.md               # Reference documentation
      examples.md

SKILL.md file format

SKILL.md contains YAML frontmatter and Markdown body:

---
name: docker-ops
description: Guide to Docker image, container, and network management
license: MIT
metadata:
  disabled: false
  contentOverrideMode: replace
---

## Overview

This Skill guides agents how to use Docker for common tasks...

## Core concepts

- **Image**: Read-only template containing application and dependencies
- **Container**: Running instance of an image

## Usage guide

### Build images

...

Frontmatter fields

contentOverrideMode explanation:

• replace (default): Use content from the highest priority layer, ignore lower layers
• merge: Chain fallback by priority (fall back to lower layer if not present in higher layer)

Install Skills

Skills can come from three sources:

1. Built-in Skills

Sink includes some commonly used Skills. These are automatically available without additional installation.

2. Sync from official repository

Sync pre-downloaded Skills from the ~/.agents/skills/ directory:

sink skill sync

This command will:

• Scan all Skill directories under ~/.agents/skills/
• Create symlinks in the skills/ subdirectory in your Sink configuration directory pointing to ~/.agents/skills/

Prerequisite: You need to download Skill folders to ~/.agents/skills/ beforehand.

3. Add Skills manually

Create Skill folders directly in your configuration directory:

User-level installation

Place Skills in the user-level configuration directory:

mkdir -p ~/.sink/skills/my-custom-skill
cat > ~/.sink/skills/my-custom-skill/SKILL.md << 'SKILL'
---
name: my-custom-skill
description: Custom tutorial
metadata:
  disabled: false
---

## Overview
This is a custom Skill I wrote for agents...
SKILL

This Skill will be available to all workspaces.

Workspace-level installation

Place Skills in the workspace configuration directory to apply only to that workspace:

mkdir -p /path/to/my-project/sink/skills/project-specific-skill
cat > /path/to/my-project/sink/skills/project-specific-skill/SKILL.md << 'SKILL'
---
name: project-specific-skill
description: Available only in this project
metadata:
  disabled: false
---

## Project background
Describe project-specific practices and conventions in this Skill...
SKILL

4. Add reference materials

Create a references/ subdirectory in the Skill directory to store additional documentation:

mkdir -p ~/.sink/skills/docker-ops/references
cat > ~/.sink/skills/docker-ops/references/api.md << 'REF'
# Docker API Reference

## Common commands

- `docker build` - Build image
- `docker run` - Run container
...
REF

View installed Skills

List all currently available Skills:

sink skill list

Output will show:

• Skill ID (directory name)
• Display name (from frontmatter)
• Description
• Source (builtin / user / workspace)
• Enable status

Associate Skills with Profiles

Skills are linked to agents through Profiles. Once a task is created, the agent automatically gets all Skills associated with that Profile.

Edit a Profile

Open the Profile file (Markdown format) and specify Skills in the frontmatter:

---
name: code-reviewer
description: Code quality analysis and review
runtime: claude-code
skills:
  - web-search
  - code-analysis
  - test-runner
mcpServers:
  - filesystem
---

You are an experienced code reviewer specializing in software quality...

Skills field

The skills field supports two syntaxes:

Simple list (whitelist):

skills:
  - web-search
  - docker-ops

Only Skills in the list are available.

Selector syntax (include/exclude):

skills:
  include:
    - web-search
    - docker-ops
  exclude:
    - experimental-skill

Or exclude only:

skills:
  exclude:
    - experimental-skill

Disable Skills

Temporary disable

Modify the Skill’s frontmatter and set metadata.disabled to true:

---
name: web-search
metadata:
  disabled: true
---

After disabling, the Skill will be removed from the available Skills list for all Profiles.

Exclude from specific Profiles

If you don’t want to disable globally but only exclude from certain Profiles:

Use exclude in the Profile’s skills field:

skills:
  exclude:
    - web-search

Best practices

Write clear Skills

1. Clear titles: Skill names should intuitively reflect their purpose

   name: error-fixing-and-debugging
   

2. Include specific examples: Good Skills include code examples and common errors

   ## Common errors
   
   ### Error: Connection refused
   
   **Cause**: Service not started
   **Solution**: Run `docker run -d my-service`
   

3. Organize reference materials: Complex Skills should organize documentation in categorized references/ directory

Sharing and version management

1. Store Skills in version control (Git)
2. Use semantic versioning (e.g., v1.0.0) to tag releases
3. Explicitly document dependent Skill versions in Profiles (if needed)

Difference between Skills and MCP Servers

• Skill = Guide and best practices documentation
• MCP Server = Actual tool and capability implementation

Agents rely on MCP Servers to execute operations, and on Skills to understand “when to use” and “how to use well.” The two are complementary.

Troubleshooting

Skill not showing in Profile

Checklist:

1. Is the Skill disabled?

   # Check metadata.disabled in SKILL.md
   

2. Is the Skill ID correct?

   sink skill list  # View actual Skill IDs
   

3. Is the Skill reference in the Profile spelled correctly?

   skills:
     - correct-skill-id # Must match skill list output
   

Multi-layer Skill conflicts

If you define the same Skill ID in both user and workspace layers and see unexpected content, check:

# View effective configuration (merged)
cat <workspace>/.sink/.settings.snapshot.json

# View raw files
cat ~/.sink/skills/my-skill/SKILL.md
cat <workspace>/.sink/skills/my-skill/SKILL.md

Priority is workspace > user > builtin.

Next steps

• Learn how to Manage Profiles to associate Skills with agents
• See Configure MCP Servers to add actual tools to agents
• Create your first Task and have agents use the Skills you configured