Skills System

Overview

Skills are reusable instruction sets that tell Claude Code how to behave in your projects. Create a skill once — like "always use type hints in Python" or "follow our Git branching conventions" — and it automatically applies to every session across your projects.

Creating Skills

Create skills through the Open Poet UI:

1. Navigate to the Skills panel in the sidebar.
2. Click Create New.
3. Fill in the required fields:

Skill Structure

Each skill is stored on disk as a YAML-frontmatter markdown file. When synced to a project, the file is placed at .claude/skills/<name>/SKILL.md:

---
name: python-best-practices
description: Python coding standards and type hint requirements
user-invocable: false
---

# Python Best Practices

## Instructions
- Use type hints for all function parameters and return values
- Follow PEP 8 style guidelines
- Write docstrings for public functions
- Prefer f-strings over .format() or % formatting
- Use pathlib instead of os.path for file operations

The description field in the frontmatter is auto-extracted from the first heading or the first line of the content.

Sync Policies

Each project has a skill_policy setting that determines which skills are synced:

Resolution Order

1. If skill_policy is custom: use the per-project global skill overrides.
2. If skill_policy is inherit (empty): use all globally enabled skills.
3. In both cases, any enabled project-specific skills are added.
4. Project skills override global skills with the same name.

Sync Process

Skills are synced to each project's .claude/skills/ directory so Claude Code can read them during sessions:

• Automatic sync — skills are synced when starting a new Claude Code session.
• Manual sync — use the Sync Config button in project settings.

What Happens During Sync

1. Active skills are written as markdown files to your project's .claude/skills/ directory.
2. Old or disabled skills are cleaned up automatically.
3. For remote (SSH) projects, files are synced via SFTP.

For remote projects (SSH), the sync process uses SFTP to write files to the remote server.

Project-Specific Skills

In addition to global skills, each project can define its own skills that only apply to that project:

• Created through the project's skill panel or the API.
• Follow the same format as global skills.
• Override global skills if they share the same name.
• Useful for project-specific coding conventions, framework-specific rules, or team workflows.

Skill Management

• Create, edit, delete — manage skills via the UI or through the API endpoints.
• Enable/disable — toggle skills on and off without deleting them.
• Categories — organize skills by type: coding, testing, deployment, documentation, workflow.
• Sort order — drag to reorder skills in the list.

Quick Example

Want Claude Code to always use type hints in Python? Create a skill:

1. Go to the Skills panel and click Create New.
2. Name it python-types, set category to coding.
3. Add your instructions:

# Python Type Hints

## Instructions
- Use type hints for all function parameters and return values
- Use PEP 484 syntax (not comments)
- Prefer built-in generics (list[str]) over typing module (List[str])
- Add type hints when modifying existing functions

This skill will now be synced to all your projects and applied to every Claude Code session automatically.

Best Practices

• Keep skills focused — each skill should address a single concern (e.g., "Go error handling" rather than "all Go rules").
• Use imperative language — write instructions as direct commands ("Use type hints" rather than "Type hints should be used").
• Include concrete examples — show code snippets demonstrating the desired patterns.
• Group related instructions — use markdown headings to organize instructions into logical sections.
• Start general, then specialize — begin with language-level skills, then add framework-specific ones as project skills.