Skip to main content

​
Compatibility with Claude Code

Craft Agent uses the exact same SKILL.md format as the Claude Code SDK. This means any skill written for Claude Code works in Craft Agent without modification.
Skills are fully portable between Claude Code and Craft Agent - same frontmatter fields, same content structure, same behavior.

​
What’s Identical

File Format

SKILL.md with YAML frontmatter + Markdown content

Frontmatter Fields

name, description, globs, alwaysAllow, requiredSources

Content Structure

Markdown instructions that guide Claude’s behavior

Tool Permissions

Same alwaysAllow behavior for pre-approving tools

​
What Craft Agent Adds

1

Visual Icons

Display custom icons in the UI for easy identification
2

Workspace Organization

Skills are scoped to workspaces for better organization
3

UI Management

Browse, edit, and validate skills through the interface
4

Three-Tier System

Project > Workspace > Global skill precedence

​
Importing from Claude Code

​
Method 1: Copy Skill Directory

The simplest approach is to copy the entire skill folder:
1

Locate the Claude Code skill

Find your skill in ~/.agents/skills/{slug}/
2

Copy to Craft Agent

cp -r ~/.agents/skills/my-skill ~/.craft-agent/workspaces/{ws}/skills/
3

Verify import

Check that the skill appears in your workspace

​
Method 2: Copy SKILL.md Only

If you only need the skill definition:
1

Create destination directory

mkdir -p ~/.craft-agent/workspaces/{ws}/skills/my-skill
2

Copy SKILL.md

cp ~/.agents/skills/my-skill/SKILL.md ~/.craft-agent/workspaces/{ws}/skills/my-skill/
3

Add an icon

Include an icon.svg or icon.png for visual identification

​
Migration Checklist

When importing skills from Claude Code, verify these elements:
Ensure all required fields are present:
---
name: "Skill Name"              # Required
description: "Brief description" # Required
globs: ["*.ts"]                 # Optional
alwaysAllow: ["Bash"]           # Optional
requiredSources: ["github"]     # Optional
---
Verify the directory structure:
~/.craft-agent/workspaces/{ws}/skills/{slug}/
├── SKILL.md          # Copied from Claude Code
├── icon.svg          # Add for Craft Agent UI
└── (other files)     # Any additional resources
Claude Code skills may not have icons. Add one for better UX:
  • Find a relevant icon from Heroicons or Feather Icons
  • Save as icon.svg, icon.png, icon.jpg, or icon.jpeg
  • Place in the skill directory
If using requiredSources, ensure those sources exist in your workspace:
  • Check source is configured in Craft Agent
  • Verify authentication is complete
  • Unauthenticated sources are silently skipped

​
Skill Precedence System

Craft Agent extends Claude Code’s skill system with a three-tier hierarchy:
1

Global Skills (Lowest Priority)

Located in ~/.agents/skills/ - shared across all workspacesUse for: Universal skills that apply everywhere
2

Workspace Skills (Medium Priority)

Located in ~/.craft-agent/workspaces/{id}/skills/ - scoped to workspaceUse for: Team or project-specific customizations
3

Project Skills (Highest Priority)

Located in {project}/.agents/skills/ - specific to codebaseUse for: Repository-specific conventions
When multiple skills share the same slug, the higher-priority version takes precedence. This lets you override global skills with workspace or project-specific versions.

​
Example: Importing a Commit Skill

Let’s walk through importing a commit message skill from Claude Code:
1

Check the original skill

cat ~/.agents/skills/commit/SKILL.md

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

# Commit Message Guidelines
...
2

Copy to workspace

cp -r ~/.agents/skills/commit ~/.craft-agent/workspaces/{ws}/skills/
3

Add an icon

Download a git commit icon and save it:
# Save icon to skill directory
cp ~/Downloads/commit-icon.svg ~/.craft-agent/workspaces/{ws}/skills/commit/icon.svg
4

Validate the import

skill_validate({ skillSlug: "commit" })
5

Test the skill

Invoke it with /commit or @commit to verify behavior

​
Overriding SDK Skills

Both Claude Code and Craft Agent have built-in SDK skills. You can override them in both systems:

​
In Claude Code

Create a skill with the same slug: 
mkdir -p ~/.agents/skills/commit
# Write custom SKILL.md

​
In Craft Agent

Same approach, but with workspace or project scope: 
# Workspace-level override
mkdir -p ~/.craft-agent/workspaces/{ws}/skills/commit

# Project-level override (highest priority)
mkdir -p {project}/.agents/skills/commit
Craft Agent checks project skills first, then workspace skills, then global skills, then falls back to SDK skills.

​
Bulk Import

To import all your Claude Code skills at once: 
# Copy all skills to workspace
cp -r ~/.agents/skills/* ~/.craft-agent/workspaces/{ws}/skills/

# Or symlink to keep them in sync
ln -s ~/.agents/skills/* ~/.craft-agent/workspaces/{ws}/skills/
If symlinking, changes in Claude Code will affect Craft Agent and vice versa. Use copying for independent versions.

​
Adding Icons to Imported Skills

Imported skills may not have icons. Here’s how to add them efficiently:
1

Identify skills without icons

for skill in ~/.craft-agent/workspaces/{ws}/skills/*/; do
  if ! ls "$skill"icon.* 2>/dev/null; then
    echo "Missing icon: $(basename "$skill")"
  fi
done
2

Find appropriate icons

Visit icon libraries:
3

Download and save icons

Save each icon as icon.svg in the respective skill directory
4

Validate all skills

skill_validate({ skillSlug: "skill-1" })
skill_validate({ skillSlug: "skill-2" })
# ... repeat for each skill

​
Exporting from Craft Agent

You can also export Craft Agent skills to use in Claude Code:
1

Copy skill to global directory

cp -r ~/.craft-agent/workspaces/{ws}/skills/my-skill ~/.agents/skills/
2

Remove Craft Agent-specific files (optional)

Claude Code doesn’t use icons, so you can remove them:
rm ~/.agents/skills/my-skill/icon.*
3

Test in Claude Code

Launch Claude Code and verify the skill works

​
Troubleshooting Imports

  • Check the skill directory exists in the correct location
  • Verify SKILL.md is present and readable
  • Run skill_validate to check for errors
  • Restart Craft Agent to reload skills
  • Ensure YAML syntax is correct (proper indentation, quotes)
  • Check for required fields: name and description
  • Validate array formats: globs: ["*.ts"] not globs: *.ts
  • Confirm icon filename is exactly icon.svg, icon.png, icon.jpg, or icon.jpeg
  • Check file is not corrupted (open in image viewer)
  • For SVG, validate XML structure
  • Verify sources exist in workspace configuration
  • Check sources are authenticated
  • Ensure source slugs match exactly (case-sensitive)
  • The SKILL.md format is identical, but MCP tool availability may differ
  • Check that required tools are available in Craft Agent
  • Verify alwaysAllow permissions match your needs

​
Best Practices

Import to workspace level for team-specific skills
Use project level for repository-specific conventions
Add icons to all imported skills for better UX
Validate after every import with skill_validate
Test imported skills before sharing with team
Document any Craft Agent-specific customizations
Keep a backup of original Claude Code skills

​
Next Steps

Skills Overview

Learn more about how skills work

Creating Skills

Build custom skills from scratch

Build docs developers (and LLMs) love

Get started for freeTalk to us