Skip to main content

​
What Are Skills?

Skills are specialized instructions that extend Claude’s capabilities for specific tasks. They provide focused guidance that helps the agent perform domain-specific work more effectively.
Skills use the exact same SKILL.md format as the Claude Code SDK - making skills fully compatible between systems.

​
Key Features

Slash Commands

Invoke skills instantly with commands like /commit or /review-pr

Auto-Triggering

Skills activate automatically based on file patterns (globs)

Tool Permissions

Pre-approve specific tools to run without prompting

SDK Compatible

Same format as Claude Code SDK for seamless portability

​
How Skills Work

When you invoke a skill, it injects specialized instructions into Claude’s context. This helps the agent:
  • Follow project-specific conventions
  • Enforce team coding standards
  • Apply consistent patterns across tasks
  • Access domain-specific knowledge

​
Skill Structure

Each skill is stored as a directory containing: 
~/.craft-agent/workspaces/{workspaceId}/skills/{slug}/
├── SKILL.md          # Required: Skill definition
├── icon.svg          # Recommended: Visual identifier
└── (other files)     # Optional: Additional resources

​
Storage Hierarchy

Skills follow a three-tier precedence system:
1

Project Skills (Highest Priority)

Located in {project}/.agents/skills/ - specific to the current codebase
2

Workspace Skills (Medium Priority)

Located in ~/.craft-agent/workspaces/{id}/skills/ - scoped to workspace
3

Global Skills (Lowest Priority)

Located in ~/.agents/skills/ - available across all workspaces
When multiple skills share the same slug, the higher-priority version takes precedence. This lets you override built-in skills with custom implementations.

​
Invoking Skills

​
Via Slash Commands

Type a forward slash followed by the skill name: 
/commit
/review-pr
/test

​
Via @Mentions

Reference a skill directly in your message: 
@commit Create a commit with these changes
@review-pr Check this pull request for issues

​
Via File Patterns

Skills with globs patterns activate automatically when working with matching files: 
---
name: "Test Helper"
globs: ["*.test.ts", "**/__tests__/**"]
---

​
Skill Metadata

Every skill requires frontmatter with key information:
FieldRequiredDescription
nameYesDisplay name shown in UI
descriptionYesBrief explanation of purpose
globsNoFile patterns that trigger the skill
alwaysAllowNoTools to auto-approve
requiredSourcesNoSources to enable on invocation

​
Example Metadata

---
name: "Commit Helper"
description: "Create well-formatted git commit messages"
globs: ["*.ts", "*.tsx"]
alwaysAllow: ["Bash"]
requiredSources:
  - github
---

​
Required Sources

The requiredSources field automatically enables specific sources when the skill is invoked: 
---
name: "Linear Triage"
requiredSources:
  - linear
---
When a user mentions this skill, the Linear source activates automatically - no manual toggle needed.
Sources must exist in the workspace and be authenticated. Unauthenticated or missing sources are silently skipped.

​
Overriding Built-in Skills

You can customize any built-in SDK skill by creating a workspace or project skill with the same slug:
1

Create Directory

Make a folder matching the built-in skill’s slug
mkdir -p ~/.craft-agent/workspaces/{ws}/skills/commit
2

Write SKILL.md

Define your custom instructions with the same frontmatter format
3

Add Icon

Include a visual identifier for the UI
Your custom skill will be used instead of the SDK version.

​
Best Practices

Provide clear, concrete instructions that Claude can follow immediately. Avoid vague guidance.
Show the expected output format or behavior with real examples.
Explicitly state what the skill should NOT do to prevent scope creep.
One skill should handle one specific task or domain. Split complex workflows into multiple skills.
Use relevant icons to make skills easily identifiable in the UI.

​
Next Steps

Creating Skills

Learn how to build custom skills from scratch

Importing Skills

Import existing skills from Claude Code

Build docs developers (and LLMs) love

Get started for freeTalk to us