Adding Custom Skills
Relevant source files
The following files were used as context for generating this wiki page:
Custom Skills in Open Claude Cowork are specialized agentic capabilities that allow the Claude model to autonomously invoke domain-specific knowledge or instructions when relevant to a user's query. These skills are implemented as filesystem-based markdown files that provide context-aware guidance to the AI agent during multi-turn conversations.
The system is designed to be plug-and-play; skills are auto-discovered from specific directories at startup and integrated into the model's toolset. When a skill is triggered, the model follows the specific instructions defined in the skill's markdown documentation to perform tasks or provide specialized expertise.
Sources: README.md:196-206, server/providers/claude-provider.js:55-60
Skill Architecture and Discovery
Skills are managed through a filesystem-based discovery mechanism. The application searches for skill definitions in two primary locations to differentiate between team-shared capabilities and personal user preferences.
Skill Locations
| Location | Path | Purpose |
|---|---|---|
| Project Skills | .claude/skills/ | Shared with team members via version control (Git). |
| User Skills | ~/.claude/skills/ | Personal skills available across all of a user's local projects. |
Sources: README.md:225-231, server/providers/claude-provider.js:59
Technical Implementation
The discovery logic is enabled in the backend via the ClaudeProvider using the Claude Agent SDK. The provider is configured to load settings from both 'user' and 'project' sources.
// Configuration in the Claude Provider
const queryOptions = {
allowedTools,
maxTurns,
mcpServers,
permissionMode: this.permissionMode,
settingSources: ['user', 'project'] // This enables filesystem-based skill loading
};
Sources: server/providers/claude-provider.js:55-60, README.md:235-238
Creating a Custom Skill
Creating a skill involves creating a specific directory structure and a SKILL.md file containing YAML frontmatter. This frontmatter is critical as it contains the description used by the model to determine when the skill should be invoked.
Step-by-Step Creation
- Directory Creation: Create a unique folder for the skill within a supported skills directory.
- Definition File: Create a
SKILL.mdfile inside that folder. - Frontmatter Configuration: Define the trigger description in YAML format at the top of the file.
---
description: Use this skill when the user asks about [your topic]
---
# Skill Name
Instructions for the agent...
Sources: README.md:213-223
Logical Flow of Skill Invocation
The following diagram illustrates how a custom skill is identified and utilized during a chat session.
The diagram shows the transition from user input to the autonomous selection of a skill based on filesystem discovery.
Sources: README.md:202-206, server/providers/claude-provider.js:55-60, server/server.js:126-140
Skill Integration in Providers
The system handles skills as a specific tool type named Skill. For a skill to be active, it must be included in the allowedTools array passed to the AI provider.
Provider Comparison
| Provider | Skill Support | Activation Method |
|---|---|---|
| Claude Provider | Native | Enabled via allowedTools: ['Skill'] and settingSources. |
| Opencode Provider | Indirect | Relies on underlying model routing; standard tools are handled via opencode.json. |
Sources: server/providers/claude-provider.js:14-17, server/server.js:139, README.md:236-238
Sequence of Tool Execution
When a skill is invoked, it follows the standard tool-use lifecycle within the streaming architecture.
This sequence highlights that skills are treated as a specialized tool interaction within the Server-Sent Events (SSE) stream.
Sources: server/providers/claude-provider.js:93-110, server/server.js:141-155, renderer/renderer.js:716-735
Existing Skill Examples
The project includes pre-configured skills that serve as templates for custom implementations.
Remotion Best Practices
Located at .claude/skills/remotion-best-practices/SKILL.md, this skill is triggered by queries regarding React-based video generation or the Remotion framework. It provides:
- Animation patterns.
- Player optimization techniques.
- Troubleshooting guides.
Sources: README.md:208-211, renderer/renderer.js:1360
Summary
Custom Skills provide a powerful extension mechanism for Open Claude Cowork by allowing developers to inject domain-specific logic into the Claude Agent SDK without modifying the core application code. By leveraging the filesystem for discovery and the Skill tool for execution, the system maintains a clean separation between the general-purpose AI agent and specialized expert knowledge.
Sources: README.md:198-206, server/providers/claude-provider.js:55-60