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

> Learn how to manage and create skills in Craft Agents using a three-tier storage system. Discover how project configurations override defaults for efficient skill management.

- Repository: [Craft Ai Agents/craft-agents-oss](https://github.com/craft-ai-agents/craft-agents-oss)
- Tags: how-to-guide
- Published: 2026-07-04

---

**Craft Agents uses a three-tier storage system—global, workspace, and project—to manage skills defined in [`SKILL.md`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/SKILL.md) file written in the Claude Code SDK front-matter format.

### Skill Definition Format (SKILL.md)

The [`SKILL.md`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/skills/storage.ts) (lines 65-92) validates this structure.

```yaml
---
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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/SKILL.md) to display in the UI. The `SkillAvatar` component in [`apps/electron/src/renderer/components/ui/skill-avatar.tsx`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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

```bash
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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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.

```typescript
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:

```typescript
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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/server-core/src/handlers/rpc/skills.ts) registers channels for listing, opening, and deleting skills:

```typescript
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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/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.