Skill Authoring Guide

Relevant source files

The following files were used as context for generating this wiki page:

• schemas/skill.schema.json
• packages/core/src/methodology/packs/meta/skill-authoring/SKILL.md
• packages/core/src/skills.ts
• packages/cli/src/commands/create.ts
• packages/core/src/methodology/validator.ts
• packages/core/src/skill-translator.ts

Introduction

Skill Authoring is the process of creating portable, reusable instruction sets that teach AI coding agents how to perform specific tasks, such as enforcing security patterns or following framework-specific best practices. Within the SkillKit ecosystem, a "Skill" is primarily defined by a SKILL.md file containing structured YAML frontmatter and Markdown content that guides an agent's execution.

The core principle of skill authoring is that a skill should be the description that triggers it, not merely a summary of a workflow. This ensures that the trigger tells the agent when to use the skill, while the content provides the specific details on how to execute it. SkillKit provides the tooling to validate, translate, and sync these skills across various agents like Claude Code, Cursor, and GitHub Copilot.

Sources: packages/core/src/methodology/packs/meta/skill-authoring/SKILL.md:18-24, README.md:9-14

Skill Anatomy and Structure

A standard skill is organized within a specific directory structure and must contain a SKILL.md file. Optionally, it can include directories for references/, scripts/, and assets/ to support more complex workflows.

The SKILL.md File

The SKILL.md file consists of two main parts: the YAML Frontmatter (metadata) and the Markdown Body (instructions).

Frontmatter Specification

The frontmatter defines the identity and activation rules for the skill. According to the project's JSON schema and authoring guidelines, certain fields are mandatory for validation and cross-agent compatibility.

Field	Type	Required	Description
name	string	Yes	Unique identifier (lowercase alphanumeric with hyphens).
description	string	Yes	Brief explanation of what the skill does (used for triggers).
version	string	Yes	Semantic versioning (e.g., 1.0.0).
triggers	array	Rec.	Phrases that activate the skill in natural language.
tags	array	Rec.	Categorization tags for discovery.
allowed-tools	string	No	Space-delimited list of pre-approved tools for the skill.
compatibility	string	No	Environment requirements (e.g., Node.js version).

Sources: schemas/skill.schema.json:8-63, packages/core/src/methodology/packs/meta/skill-authoring/SKILL.md:65-76

Authoring Best Practices

Writing Effective Triggers

Triggers should reflect natural language phrases a user might type. Authors should provide multiple variations to increase the likelihood of activation.

• Good Triggers: "write tests first", "tdd", "test driven development".
• Bad Triggers: "testing methodology" (vague) or "skill-123" (unnatural).

Sources: packages/core/src/methodology/packs/meta/skill-authoring/SKILL.md:78-95

Content Guidelines

Authors should use the second person, present tense, and active voice (e.g., "You are implementing...", "Write the test..."). The content should be structured with clear headers, process steps, and verification checklists.

Directive Language Levels:

• Strong: "You MUST...", "ALWAYS...", "NEVER...".
• Soft: "Prefer...", "Consider...", "When possible...".

Sources: packages/core/src/methodology/packs/meta/skill-authoring/SKILL.md:97-128

Discovery and Validation

The SkillKit system automatically discovers skills by searching for SKILL.md files in standard paths such as .claude/skills, .cursor/skills, or a root skills/ directory.

Validation Logic

The validateSkill function ensures that a skill meets structural requirements before it is synced or translated.

Technical Implementation

Parsing to Canonical Format

To support 17+ different agents, SkillKit first parses specific skill formats into a "Canonical" representation. This format preserves frontmatter and content while extracting agent-specific fields (like Claude's hooks or Cursor's globs).

export interface CrossAgentSkill {
  name: string;
  description: string;
  content: string;
  frontmatter: Record<string, unknown>;
  sourcePath: string;
  agentFields?: Record<string, unknown>;
}

Sources: packages/core/src/skill-translator.ts:50-65

Skill Creation CLI

Developers can bootstrap new skills using the CLI create command, which generates the required directory structure and a template SKILL.md.

# Basic creation
skillkit create my-new-skill

# Full structure with all optional directories
skillkit create my-new-skill --full

Sources: packages/cli/src/commands/create.ts:11-37

Conclusion

Effective skill authoring is central to the SkillKit ecosystem, enabling AI agents to operate with specialized domain knowledge across different environments. By adhering to the SKILL.md specification and utilizing provided validation tools, authors can ensure their instructions are actionable, portable, and reliable.

Sources: packages/core/src/methodology/packs/meta/skill-authoring/SKILL.md:214-230