Skip to main content

​
Getting Started

Creating a custom skill involves three main steps:
1

Create the skill directory

Organize your skill in a dedicated folder
2

Write SKILL.md with frontmatter and instructions

Define metadata and provide guidance for Claude
3

Add an icon for visual identification

Include a visual indicator for the UI

​
File Structure

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

​
Skill Slug Requirements

  • Lowercase letters, numbers, and hyphens only
  • Must start with a letter
  • No spaces or special characters
  • Examples: commit, code-review, api-docs

​
SKILL.md Format

The SKILL.md file uses YAML frontmatter followed by Markdown content: 
---
name: "Display Name"
description: "Brief description for skill list"
globs: ["*.ts", "*.tsx"]     # Optional
alwaysAllow: ["Bash"]        # Optional
requiredSources:             # Optional
  - github
  - linear
---

# Skill Instructions

Your skill content goes here...

​
Frontmatter Fields

Display name shown in the UI and skill list.
name: "Code Review Helper"
Brief 1-2 sentence explanation of what the skill does.
description: "Review code changes for quality, security, and best practices"
Array of glob patterns. When files matching these patterns are being worked on, the skill may be automatically suggested.
globs:
  - "*.test.ts"           # Test files
  - "*.spec.tsx"          # React test files
  - "**/__tests__/**"     # Test directories
Array of tool names that are automatically allowed when this skill is active. Useful for skills that require specific tools without prompting.
alwaysAllow:
  - "Bash"                # Allow bash commands
  - "Write"               # Allow file writes
Array of source slugs to auto-enable when this skill is invoked. Sources must exist in the workspace and be authenticated.
requiredSources:
  - linear               # Auto-enable Linear source
  - github               # Auto-enable GitHub source

​
Writing Effective Instructions

​
Structure Your Content

Organize instructions with clear headings and sections: 
# Skill Name

## Purpose
Briefly explain what this skill helps accomplish.

## Guidelines
- Specific instruction 1
- Specific instruction 2
- Things to check for

## Examples
Show concrete examples of correct behavior.

## Avoid
List things the skill should NOT do.

​
Be Specific and Actionable

## Code Review

Check the code for issues and suggest improvements.

​
Include Examples

Show Claude exactly what you expect: 
## Commit Message Format

Use conventional commits:

**Good:**
feat(auth): add OAuth2 provider support Implements Google and GitHub OAuth flows with token refresh. Co-Authored-By: Claude 

**Bad:**
fixed stuff

​
Set Clear Boundaries

Explicitly state what the skill should NOT do: 
## Boundaries

- DO NOT modify database migrations
- DO NOT change API contracts without documentation
- DO NOT remove existing tests

​
Adding Icons

Every skill should have a visually relevant icon for easy identification.

​
Icon Requirements

  • Filename: Must be icon.svg, icon.png, icon.jpg, or icon.jpeg
  • Format: SVG preferred (scalable, crisp at all sizes)
  • Size: For PNG/JPG, use at least 64x64 pixels

​
Finding Icons

Heroicons

MIT licensed, clean UI icons

Feather Icons

Simple, consistent icon set

Simple Icons

Brand icons (Git, npm, etc.)

​
Icon Selection Guide

Skill TypeSuggested Icons
Git/CommitGit logo, commit symbol
TestingCheckmark, test tube, beaker
DeploymentRocket, cloud, server
Code ReviewMagnifying glass, eye, checklist
DocumentationBook, file text, document
SecurityShield, lock, key

​
Example Skills

​
Commit Message Skill

---
name: "Commit"
description: "Create well-formatted git commit messages"
alwaysAllow: ["Bash"]
---

# Commit Message Guidelines

When creating commits:

## Format
Use conventional commits:
- `feat:` New feature
- `fix:` Bug fix
- `docs:` Documentation
- `refactor:` Code refactoring
- `test:` Adding tests

## Style
- Keep subject line under 72 characters
- Use imperative mood ("Add feature" not "Added feature")
- Explain why, not what (the diff shows what)

## Co-authorship
Always include: `Co-Authored-By: Claude <[email protected]>`

​
Team Standards Skill

---
name: "Team Standards"
description: "Enforce team coding conventions and patterns"
globs: ["src/**/*.ts", "src/**/*.tsx"]
---

# Team Coding Standards

## File Organization
- One component per file
- Co-locate tests with source files
- Use barrel exports (index.ts)

## Naming Conventions
- Components: PascalCase
- Hooks: camelCase with `use` prefix
- Constants: SCREAMING_SNAKE_CASE

## Import Order
1. External packages
2. Internal packages (@company/*)
3. Relative imports

## Avoid
- Default exports (use named exports)
- Inline styles (use CSS modules)
- Magic numbers (define as constants)

​
API Documentation Skill

---
name: "API Docs"
description: "Generate consistent API documentation"
globs: ["**/api/**/*.ts", "**/routes/**/*.ts"]
---

# API Documentation Guidelines

## Endpoint Documentation

For each endpoint, include:

### Required Sections
- **Description**: What the endpoint does
- **Authentication**: Required auth level
- **Parameters**: All query/path/body params
- **Response**: Success response format
- **Errors**: Possible error codes

### Example
```typescript
/**
 * Get user profile
 * 
 * @auth Bearer token required
 * @param {string} userId - User ID (path parameter)
 * @returns {User} User profile object
 * @throws {404} User not found
 * @throws {401} Unauthorized
 */

​
Validating Skills

Always validate after creating or editing a skill to catch errors early.
Use the validation tool to check your skill: 
skill_validate({ skillSlug: "my-skill" })

​
What Gets Validated

  • Slug format (lowercase, alphanumeric, hyphens only)
  • SKILL.md exists and is readable
  • YAML frontmatter is valid
  • Required fields present (name, description)
  • Content is non-empty
  • Icon format (if present)

​
Testing Your Skill

1

Invoke the skill

Use /your-skill or @your-skill to activate it
2

Verify behavior

Check that Claude follows your instructions
3

Iterate and refine

Update SKILL.md based on actual usage
4

Re-validate

Run skill_validate after each change

​
Best Practices Checklist

Keep instructions specific and actionable
Include concrete examples of expected output
Set clear boundaries (what NOT to do)
Use a focused scope (one task per skill)
Add a visually relevant icon
Validate after creation or edits
Test with real scenarios
Update based on feedback

​
Troubleshooting

  • Check slug format (lowercase, alphanumeric, hyphens only)
  • Verify SKILL.md exists and is readable
  • Run skill_validate for detailed errors
  • Check file permissions (should be readable)
  • Verify glob patterns match your files
  • Check if skill is in correct workspace
  • Ensure file paths are relative to project root
  • Use supported formats: svg, png, jpg, jpeg
  • File must be named icon.{ext} (not my-icon.svg)
  • Check icon file is not corrupted
  • For SVG, ensure valid XML structure
  • Make instructions more specific
  • Add concrete examples
  • Break complex tasks into steps
  • Set explicit boundaries

​
Next Steps

Import from Claude Code

Learn how to import existing skills from Claude Code SDK

Build docs developers (and LLMs) love

Get started for freeTalk to us