Skip to content

agent-skill-specification.md

Latest commit

 

History

History
46 lines (32 loc) · 1.63 KB

agent-skill-specification.md

File metadata and controls

46 lines (32 loc) · 1.63 KB
Raw

Specification — Agent Skill Package Format (v1.0)

This specification defines the canonical directory structure, frontmatter metadata schema, trigger rules, and resolution order for Agent Skill packages.

1. Directory Structure

An Agent Skill MUST be contained within a dedicated directory containing a mandatory SKILL.md file:

skills/<skill-name>/
├── SKILL.md          # Mandatory main instruction file
├── scripts/           # Optional helper scripts and utilities
├── examples/          # Optional reference implementations
└── references/        # Optional deep technical documentation

2. SKILL.md Header Schema (YAML Frontmatter)

Every SKILL.md file MUST begin with valid YAML frontmatter containing name and description:

---
name: kitwork-routing
description: Use when adding or changing Kitwork filesystem routes, router.kitwork.js, parameters, or views.
---

Frontmatter Fields

Field Type Required Description
name String Yes Unique hyphenated identifier (e.g. kitwork-routing)
description String Yes Trigger condition describing when the agent should load this skill

3. Skill Resolution & Trigger Matching

  1. The agent host maintains an in-memory index of available skill name and description pairs.
  2. When evaluating a task, the agent compares the task intent against skill descriptions.
  3. Upon a trigger match, the agent reads SKILL.md content into context.
  4. Body content MUST remain under 500 lines. Extended documentation MUST be stored in references/ subdirectories.