create-skill

Creating Instruction-Only Skills

Skills are knowledge and workflow packages that teach AI clients how to accomplish tasks. Unlike tools (which execute actions) or agents (which run autonomous LLM loops), a skill provides structured instructions that the AI follows on its own. An instruction-only skill contains no tool references -- it is purely a guide.

When to Use This Skill

Must Use

• You need to package knowledge, conventions, or workflow steps as a reusable skill that AI clients can follow
• You are creating a SKILL.md catalog entry or a class/function-based skill with no tool dependencies
• You want to enforce coding standards, onboarding steps, or review criteria through structured AI guidance

Recommended

• You are building a deployment runbook, architecture decision record, or quality gate checklist
• You want to share workflow templates across teams via MCP or HTTP discovery endpoints
• You need parameterized instructions that callers can customize per invocation

Skip When

• The skill must invoke MCP tools during execution -- use create-skill-with-tools instead
• You need an autonomous agent loop rather than static instructions -- use an agent pattern instead
• The content is a one-off prompt with no reuse value -- a plain prompt template is simpler

Decision: Pick this skill when you need a reusable, instruction-only knowledge package that guides AI through a workflow without requiring tool calls.

Class-Based Pattern

Create a class extending SkillContext and decorate it with @Skill. The decorator requires name, description, and instructions.

SkillMetadata Fields

Field	Type	Required	Description
name	string	Yes	Unique skill name in kebab-case (max 64 chars)
description	string	Yes	Short description (max 1024 chars, no HTML/XML)
instructions	string | { file: string } | { url: string }	Yes	The skill content -- see instruction sources below
parameters	SkillParameter[]	No	Customization parameters for the skill
examples	SkillExample[]	No	Usage scenarios and expected outcomes
tags	string[]	No	Categorization tags for discovery
visibility	'mcp' | 'http' | 'both'	No	Where the skill is discoverable (default: 'both')
hideFromDiscovery	boolean	No	Register but hide from listing endpoints (default: false)
priority	number	No	Search ranking weight; higher = earlier (default: 0)
toolValidation	'strict' | 'warn' | 'ignore'	No	Behavior when referenced tools are missing (default: 'warn')
license	string	No	License identifier per Agent Skills spec (e.g., 'MIT')
compatibility	string	No	Environment requirements (max 500 chars)
specMetadata	Record<string, string>	No	Arbitrary key-value map (Agent Skills spec metadata field)
allowedTools	string	No	Client agent tools to pre-approve; the server ignores it
resources	SkillResources	No	Bundled dirs: { scripts?, references?, assets? }