How Skills Are Managed and Created in Craft Agents: A Complete Guide

Craft Agents uses a three-tier storage system—global, workspace, and project—to manage skills defined in SKILL.md files, where project-level configurations automatically override workspace and global defaults.

Craft Agents extends Claude's capabilities through a custom skill architecture that lets you inject specialized instructions and behaviors. Understanding how skills are managed and created in Craft Agents enables you to customize agent behavior across different scopes, from system-wide defaults to project-specific overrides.

The Three-Tier Skill Storage Architecture

Craft Agents implements a layered storage system defined in packages/shared/src/skills/storage.ts. The architecture follows strict precedence rules that determine which skills take effect when conflicts arise.

Global Skills (Lowest Priority)

Global skills reside in ~/.agents/skills/ and serve as system-wide defaults. These skills apply to all workspaces and projects unless overridden by higher-priority tiers. The constant GLOBAL_AGENT_SKILLS_DIR defines this path in the source code.

Workspace Skills (Medium Priority)

Workspace skills are stored in either ~/.craft-agent/workspaces/{workspaceId}/skills/ or <workspaceRoot>/skills/ (resolved via getWorkspaceSkillsPath). These skills apply to all projects within a specific workspace, allowing team-wide standards or organization-specific workflows.

Project Skills (Highest Priority)

Project skills live in {projectRoot}/.agents/skills/ and are defined by the constant PROJECT_AGENT_SKILLS_DIR. These take precedence over all other tiers, enabling repository-specific customizations that override broader configurations.

How Skill Precedence Works

When the agent loads skills via loadAllSkills (see packages/shared/src/skills/storage.ts lines 16-47), it merges skills from all three tiers. Later tiers overwrite earlier ones, creating a cascading configuration where project > workspace > global. This mechanism allows you to extend or replace built-in SDK skills by creating a local skill with the same slug.

Creating a Skill in Craft Agents

A skill is fundamentally a folder containing at least a SKILL.md file written in the Claude Code SDK front-matter format.

Skill Definition Format (SKILL.md)

The SKILL.md file requires name and description fields in its YAML front matter. Optional fields include globs (file patterns), alwaysAllow (auto-approved tools), and requiredSources (context requirements). The parser parseSkillFile in packages/shared/src/skills/storage.ts (lines 65-92) validates this structure.

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

# Commit Skill

When creating a commit, enforce conventional-commit style...

Place an icon file (icon.svg, icon.png, etc.) next to SKILL.md to display in the UI. The SkillAvatar component in apps/electron/src/renderer/components/ui/skill-avatar.tsx renders these icons.

Step-by-Step Creation Process

1. Create the folder in your desired tier (e.g., ~/.craft-agent/workspaces/<ws>/skills/my-skill/)

2. Add SKILL.md with the front-matter format above

3. Add an icon (icon.svg recommended for scalability)

4. Validate the skill using the internal validation system

mkdir -p ~/.craft-agent/workspaces/12345/skills/commit
cat > ~/.craft-agent/workspaces/12345/skills/commit/SKILL.md <<'EOF'
---
name: "Commit"
description: "Create conventional commit messages"
alwaysAllow: ["Bash"]
---

# Commit Skill

Enforce conventional-commit format in messages.
EOF
cp my-commit-icon.svg ~/.craft-agent/workspaces/12345/skills/commit/icon.svg

Skill Validation

The skill_validate tool triggers handleSkillValidate in packages/session-tools-core/src/handlers/skill-validate.ts (lines 28-65). This handler resolves the skill path across all tiers, reads the file, and executes front-matter validation including slug format checks and required field verification.

import { handleSkillValidate } from '@craft-agent/session-tools-core/handlers/skill-validate';

await handleSkillValidate(ctx, { skillSlug: 'commit' });
// Returns a formatted validation result or an error message.

If the workingDirectory cannot be resolved, only workspace and global skills are checked, with a warning added to the output.

Runtime Loading and Caching

When a session initializes, the system calls loadAllSkills from @craft-agent/shared/skills to discover applicable skills:

import { loadAllSkills } from '@craft-agent/shared/skills';

const workspaceRoot = '/home/user/.craft-agent/workspaces/12345';
const projectRoot   = '/home/user/projects/my-app';

const allSkills = loadAllSkills(workspaceRoot, projectRoot);
// Returns an array of LoadedSkill objects ready for the UI.

To optimize performance, loadAllSkills caches results for five minutes (see packages/shared/src/skills/storage.ts lines 94-104), avoiding repeated filesystem scans during active sessions.

The Electron frontend communicates with the server core via RPC. The registerSkillsHandlers function in packages/server-core/src/handlers/rpc/skills.ts registers channels for listing, opening, and deleting skills:

const skills = await rpc.call(RPC_CHANNELS.skills.GET, workspaceId, projectRoot);
// Returns merged skill list for the UI.

Overriding Built-In Skills

Because of the tiered precedence system, creating a workspace or project skill with the same slug as a built-in SDK skill automatically replaces the latter. This pattern is documented in apps/electron/resources/docs/skills.md (lines 32-42) and enables complete customization of default behaviors without modifying core code.

Summary

• Craft Agents organizes skills in three tiers: global (~/.agents/skills/), workspace (~/.craft-agent/workspaces/{id}/skills/), and project ({projectRoot}/.agents/skills/)
• Project skills override workspace and global skills when slugs conflict
• Skills are defined in SKILL.md files using Claude Code SDK front-matter with required name and description fields
• The loadAllSkills function in packages/shared/src/skills/storage.ts handles discovery and caching with a five-minute TTL
• Validation occurs through handleSkillValidate in packages/session-tools-core/src/handlers/skill-validate.ts
• Icons are displayed via the SkillAvatar component in the Electron frontend

Frequently Asked Questions

How do I create a global skill that applies to all projects?

Create a folder in ~/.agents/skills/ containing a SKILL.md file with your instructions. Global skills apply to all workspaces and projects unless overridden by workspace or project-level skills with the same name.

What happens if two skills have the same name in different tiers?

The system follows strict precedence: project skills override workspace skills, which override global skills. The loadAllSkills function merges all tiers and lets later tiers overwrite earlier ones, ensuring project-specific configurations always take priority.

How do I validate that my SKILL.md syntax is correct?

Use the internal skill_validate tool which calls handleSkillValidate in packages/session-tools-core/src/handlers/skill-validate.ts. This validates front-matter syntax, checks for required fields like name and description, and verifies the slug format. If running outside a project directory, only global and workspace skills are checked.

Can I replace a built-in SDK skill with my own version?

Yes. Create a skill with the same slug at the workspace or project level. Due to the tiered precedence system (project > workspace > global), your custom skill will override the built-in version. This is the recommended method for customizing default behaviors without modifying the core SDK.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}