Specification Reference

File Format

Every Agent Skill is defined by a SKILL.md file containing YAML frontmatter followed by a Markdown body.

---
name: my-skill
description: What this does. Use when the user asks for X.
---

# My Skill

## Instructions

1. Step one
2. Step two

The frontmatter is delimited by --- on its own line. The parser uses this regex:

/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/

Frontmatter Fields

Example: full frontmatter

---
name: data-validation
description: >
  Validate CSV and JSON data files against schemas.
  Use when the user asks to check data quality.
license: Apache-2.0
compatibility: Requires Python 3.11+ and uv
metadata:
  author: skillscraft
  version: "1.0"
  category: data
allowed-tools: Bash Read
---

Name Rules

The name field is validated against this regex:

/^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,62}[a-z0-9]?$/

Rules:

• 1–64 characters
• Lowercase letters, digits, and hyphens only
• Must start and end with a letter or digit
• No consecutive hyphens (my--skill is invalid)
• Must match the parent directory name

Directory Structure

my-skill/
├── SKILL.md          # Required — metadata + instructions
├── scripts/          # Optional — executable code (any language)
│   ├── analyze.py
│   └── report.js
├── references/       # Optional — detailed documentation
│   └── GUIDE.md
└── assets/           # Optional — templates, configs, resources
    └── config.json

Validation Rules

The validator checks strict spec compliance. All errors must be fixed; warnings are advisory.

Lint Rules

The linter goes beyond spec compliance to check best practices. Best-practice checks that go beyond spec compliance.

Extended Specification

Optional, 100% backward-compatible extensions for enterprise features. Defined in @skillscraft/spec.

Security Manifest

Declare what capabilities a skill needs. Agents can use this to gate permissions.

interface SecurityManifest {
  capabilities: CapabilityDeclaration[];
  requiresNetwork?: boolean;
  modifiesFiles?: boolean;
  executesCommands?: boolean;
  fileSystemScope?: "skill-directory" | "workspace" | "system";
}

interface CapabilityDeclaration {
  capability: string;  // e.g., "file:read", "shell:execute"
  reason: string;
  optional?: boolean;
}

Test Scenarios

Structured test cases for evaluating skill behavior.

interface TestScenario {
  name: string;
  description: string;
  cases: TestCase[];
}

interface TestCase {
  name: string;
  input: string;      // Prompt to test with
  assertions: TestAssertion[];
  expectedBehavior?: string;
}

interface TestAssertion {
  type: "contains" | "not-contains" | "matches-regex"
      | "file-created" | "file-modified"
      | "command-executed" | "custom";
  value: string;
  description?: string;
}

Tool Binding

Declare tool dependencies with version requirements.

interface ToolBinding {
  dependencies: ToolDependency[];
}

interface ToolDependency {
  tool: string;       // e.g., "Bash", "Read", "Bash(git:*)"
  required: boolean;
  purpose: string;
  minVersion?: string;
}

Skill Composition

Define relationships between skills.

interface SkillComposition {
  dependencies: SkillDependency[];
  conflicts?: string[];
  executionOrder?: "before" | "after" | "independent";
}

interface SkillDependency {
  skillName: string;
  reason: string;
  optional?: boolean;
}

Constants