Skip to main content

Skills System

CrewX supports Claude Code skills format - a standardized way to package and share AI capabilities across agents and projects.

Overview​

Skills are reusable AI expertise that you can:

  • Share across multiple agents
  • Port from Claude Code without modification
  • Test across different AI providers (Claude, Gemini, Copilot, Codex)
  • Version and distribute independently

100% Claude Code Compatible​

CrewX uses the exact same skills format as Claude Code:

  • Same file structure - SKILL.md with YAML frontmatter
  • Same metadata fields - name, description, version, dependencies
  • Same content format - Markdown with role, task, and instructions sections
  • Zero modification - Drop Claude skills into ./skills/ and they work

This means: ✅ Use Claude Code skills library ✅ Share skills between Claude Code and CrewX ✅ Skills work in both environments

Quick Start​

1. Create a Skill​

Create skills/hello/SKILL.md:

---
name: hello
description: Simple greeting demo skill for verifying the CrewX skills pipeline
version: 0.0.1
---

# Hello Skill

Use this skill whenever you want to confirm that CrewX skill loading works end-to-end or you simply need a friendly greeting.

## Capabilities
- Explain how the hello skill works and where its script lives (`skills/hello/hello.js`)
- Optionally run the script to generate a greeting
- Always mention that the response is powered by the CrewX hello skill so testers can verify it

## How to Use
1. If you need a quick greeting, you can run:
   ```bash
   node skills/hello/hello.js <name>

The name argument is optional; it defaults to "CrewX user" 2. Quote the script output (or reproduce it) in your reply so humans can see the result 3. Add any extra helpful context, but keep the message short and friendly

Response Template​

When responding with this skill, include:

  • Hello, <name>! This message is generated by the CrewX hello skill script.
  • Replace <name> with the target person's name or "CrewX user" if unspecified
  • Optionally mention how to rerun the script

This lightweight skill is only meant for validation, so stay concise and cheerful.


### 2. Configure Skills in crewx.yaml

```yaml
# Project-wide skill configuration
skills:
  paths:
    - ./skills              # Custom skill directories
    - ./company-skills      # Team-shared skills
  # By default, ALL skills are auto-loaded (autoload: true by default)
  # Use 'include' OR 'exclude' to control which skills are loaded:

  # Option 1: Explicitly include only these skills (overrides autoload)
  include:
    - hello
    - code-reviewer

  # Option 2: Autoload all except these (works with autoload)
  exclude:
    - deprecated-skill
    - experimental-skill

  # Option 3: Disable autoload entirely (no skills loaded unless in 'include')
  autoload: false

# Add skills to specific agents
agents:
  - id: "senior_dev"
    provider: "cli/claude"
    skills:
      include:
        - code-reviewer
        - api-designer
    inline:
      prompt: |
        You are a senior developer with specialized skills.

3. Test the Skill​

# Test with Claude
crewx query "@senior_dev review this code"

# Test across multiple providers
CREWX_CONFIG=crewx.skills.yaml crewx query "@skill_tester_claude test hello skill"
CREWX_CONFIG=crewx.skills.yaml crewx query "@skill_tester_gemini test hello skill"
CREWX_CONFIG=crewx.skills.yaml crewx query "@skill_tester_copilot test hello skill"
CREWX_CONFIG=crewx.skills.yaml crewx query "@skill_tester_codex test hello skill"

Skill Metadata​

Required Fields​

---
name: skill-name          # Kebab-case identifier
description: Brief desc   # 10-200 characters
version: 1.0.0           # Semantic versioning
---

Optional Fields​

---
name: advanced-skill
description: Advanced skill with dependencies
version: 2.1.0
dependencies:              # Other skills this skill needs
  - base-skill
  - helper-skill
runtime:                   # Runtime requirements
  node: ">=18.0.0"
  python: ">=3.9"
visibility: public         # public | private | internal
---

Skills Configuration​

Project-Level Configuration​

Control skill loading at the project level:

skills:
  paths:
    - ./skills            # Primary skills directory
    - ./team-skills       # Shared team skills
    - ../common-skills    # Organization-wide skills

  # By default, autoload is TRUE - all skills in paths are loaded
  # You have three options to control which skills are loaded:

  # Option 1: Load ALL skills (default behavior, no config needed)
  # Just specify paths, autoload defaults to true

  # Option 2: Load ONLY specific skills (most efficient for token usage)
  include:
    - skill-one
    - skill-two
  # When 'include' is specified, only these skills load (autoload is ignored)

  # Option 3: Load ALL EXCEPT certain skills
  exclude:
    - deprecated-skill
    - experimental-skill
  # Works with autoload: true (default), excludes specific skills

  # Option 4: Disable all auto-loading
  autoload: false
  # Only skills in 'include' will be loaded (if any)

Configuration Priority:

  1. If include is set → Load ONLY those skills (most efficient)
  2. If exclude is set → Load ALL except excluded skills
  3. If neither → Load ALL skills (default: autoload: true)
  4. If autoload: false and no include → Load NOTHING

Agent-Level Configuration​

Each agent can have its own skill configuration:

agents:
  - id: "code_reviewer"
    provider: "cli/claude"
    skills:
      include:            # Agent-specific skills
        - code-review
        - security-audit
        - performance-check

Progressive Disclosure​

CrewX implements progressive skill loading for performance:

  1. Metadata Loading (Fast)

    • Load only YAML frontmatter
    • Agent sees skill name, description, version
    • Happens at agent initialization

  2. Content Loading (On-Demand)

    • Full markdown content loaded when needed
    • Agent reads skill details when using it
    • Reduces memory footprint
// SDK Example: Progressive loading
const skill = parseSkillManifestFromFile('skills/hello/SKILL.md', {
  loadContent: false,      // Only metadata
  validationMode: 'lenient'
});

// skill.metadata is available
// skill.content is undefined (loaded on-demand)

Multi-Provider Testing​

CrewX provides a dedicated testing configuration to verify skills work across all AI providers:

File: crewx.skills.yaml

skills:
  paths:
    - ./skills
  include:
    - hello

agents:
  - id: "skill_tester_claude"
    provider: "cli/claude"
    skills:
      include: [hello]

  - id: "skill_tester_gemini"
    provider: "cli/gemini"
    skills:
      include: [hello]

  - id: "skill_tester_copilot"
    provider: "cli/copilot"
    skills:
      include: [hello]

  - id: "skill_tester_codex"
    provider: "cli/codex"
    options:
      query: ["exec", "--experimental-json"]
    skills:
      include: [hello]

Usage:

# Test with specific provider
CREWX_CONFIG=crewx.skills.yaml crewx query "@skill_tester_claude test the hello skill"

# Test all providers in parallel
CREWX_CONFIG=crewx.skills.yaml crewx query \
  "@skill_tester_claude @skill_tester_gemini @skill_tester_copilot @skill_tester_codex \
  verify hello skill works"

Skill Directory Structure​

Recommended organization:

project/
├── skills/                      # Project skills
│   ├── hello/
│   │   ├── SKILL.md            # Skill manifest
│   │   └── hello.js            # Optional: supporting scripts
│   ├── code-reviewer/
│   │   ├── SKILL.md
│   │   └── templates/          # Optional: templates
│   │       └── review.md
│   └── api-designer/
│       └── SKILL.md
├── .claude/                     # Claude Code skills
│   └── skills/
│       └── crewx/
│           └── SKILL.md         # Works in both Claude Code & CrewX
├── crewx.yaml                   # Main config
└── crewx.skills.yaml           # Skills testing config

Best Practices​

1. Skill Design​

Keep skills focused:

# ✅ Good: Focused skill
name: code-reviewer
description: Review code for bugs, style, and best practices

# ❌ Bad: Too broad
name: do-everything
description: Handles all development tasks

Document clearly:

## How to Use
1. Read the code file first
2. Analyze for: [specific criteria]
3. Provide: [specific output format]

## Response Template
[Show exact format agents should follow]

2. Version Management​

Use semantic versioning:

  • Major (1.0.0 → 2.0.0): Breaking changes to skill interface
  • Minor (1.0.0 → 1.1.0): New capabilities, backward compatible
  • Patch (1.0.0 → 1.0.1): Bug fixes, clarifications

3. Skill Dependencies​

Declare dependencies explicitly:

---
name: api-tester
version: 1.0.0
dependencies:
  - api-designer    # Needs API design patterns
  - validator       # Needs validation rules
---

4. Testing Strategy​

Test skills across providers before deployment:

# 1. Create skill
vim skills/new-skill/SKILL.md

# 2. Add to test config
vim crewx.skills.yaml

# 3. Test all providers
CREWX_CONFIG=crewx.skills.yaml crewx query \
  "@skill_tester_claude @skill_tester_gemini test new-skill"

# 4. Deploy to production config
vim crewx.yaml

Integration with Claude Code​

Sharing Skills Between Environments​

Scenario: Use same skill in Claude Code IDE and CrewX CLI

# Directory structure
project/
├── .claude/skills/          # Claude Code reads from here
│   └── shared/
│       └── SKILL.md
├── skills/                  # CrewX reads from here
│   └── shared -> ../.claude/skills/shared  # Symlink
└── crewx.yaml

# CrewX config
skills:
  paths:
    - ./skills
    - ./.claude/skills       # Also search Claude Code skills

Result: One skill, works in both Claude Code and CrewX

Migrating from Claude Code​

Zero-effort migration:

  1. Skills already in .claude/skills/? They work immediately:
# crewx.yaml
skills:
  paths:
    - ./.claude/skills       # Use Claude Code skills as-is
  1. Want to keep them separate? Copy to ./skills/:
cp -r .claude/skills/* skills/
  1. No format changes needed - CrewX uses the same format

Advanced: Skill Runtime (SDK)​

For developers building on CrewX:

import {
  parseSkillManifestFromFile,
  SkillParserOptions
} from '@sowonai/crewx-sdk';

// Load skill metadata only (fast)
const skill = parseSkillManifestFromFile('skills/hello/SKILL.md', {
  loadContent: false,
  validationMode: 'lenient'
});

console.log(skill.metadata.name);        // 'hello'
console.log(skill.metadata.description); // 'Simple greeting...'
console.log(skill.content);              // undefined (not loaded)

// Load full content when needed
const fullSkill = parseSkillManifestFromFile('skills/hello/SKILL.md', {
  loadContent: true,
  validationMode: 'strict',
  resolveDependencies: true
});

console.log(fullSkill.content.raw);      // Full markdown content

Troubleshooting​

Skill Not Loading​

# Check if skill is found
crewx agent info @your_agent

# Enable debug logging
LOG_LEVEL=debug crewx query "@your_agent test"

# Verify skill file format
cat skills/your-skill/SKILL.md

Common issues:

  • Missing YAML frontmatter (--- delimiters)
  • Invalid skill name (use kebab-case: my-skill)
  • File not in configured paths
  • Agent config doesn't include the skill

Skill Version Conflicts​

When multiple versions exist:

skills:
  paths:
    - ./skills/v2        # Searched first
    - ./skills/v1        # Fallback

CrewX uses first match - order your paths accordingly.

Cross-Provider Compatibility​

Some features work differently across providers:

FeatureClaudeGeminiCopilotCodex
File read✅✅✅✅
Script execution⚠️ Needs approval⚠️ Needs approval⚠️ Needs approval✅ With exec
Tool use✅✅✅✅

Design skills to work with read-only operations for maximum compatibility.

Examples​

See working examples:

Schema Reference​

Full schema: packages/sdk/schema/skills-config.json

TypeScript types: packages/sdk/src/schema/skills.types.ts

Questions? Check CLI Guide or open an issue on GitHub.