By the end of this lesson, you'll know how to organize a skill file into five clearly defined sections — and understand why separation of concerns matters as much for skills as it does for code.
After this lesson, every skill file you write will start from a consistent skeleton that separates what a skill is from how it works.
A skill file is not a prompt template. It's a modular extension that encapsulates domain-specific knowledge, workflows, and tool integrations. Without clear architecture, skills become brittle monoliths that are hard to test, version, or compose with other skills.
The research paper analyzed over 4,476 public repositories and found that well-structured skill files correlate with a 20% reduction in development time and 15–30% improvement in token efficiency. The structure itself communicates intent — both to the LLM consuming the skill and to the humans maintaining it.
Every skill file should separate concerns into these five areas:
The identity card. Contains name, version (semver), author, dependencies, and compatibility requirements. This is what registries index and what governance systems audit.
skill:
metadata:
name: "data-analysis-skill"
version: "1.2.0"
author: "platform-team"
dependencies: ["pandas", "numpy"]
compatibility:
min_framework: "0.9.0"
models: ["claude-3.5-sonnet", "claude-4"]Input/output contracts using JSON Schema or TypeScript types. These make a skill composable — other skills and orchestrators can validate payloads before invocation.
interface:
input_schema:
type: "object"
properties:
data_source: { type: "string", description: "Path or URL to data" }
analysis_type: { type: "string", enum: ["summary", "correlation", "anomaly"] }
required: ["data_source"]
output_schema:
type: "object"
properties:
result: { type: "string" }
confidence: { type: "number", minimum: 0, maximum: 1 }Prompt templates, reasoning chains, and code snippets. This is the domain expertise — what makes this skill valuable. Separate from the plumbing.
Step sequences, tool invocations, error handling paths. Describes the process the skill follows, including branching logic and fallback behaviors.
Environment-specific values that change between deployments. Never hard-coded — always externalized.
The AWS governance guide emphasizes that agent registries index skills by their metadata — name, version, dependencies, permissions, and ownership. If your metadata section is incomplete, your skill becomes invisible to governance systems and undiscoverable by other teams.
This five-section structure maps cleanly onto MCP (Model Context Protocol) server architecture. MCP servers define resources (data exposed to agents), tools (functions agents can call), and prompts (templates for interactions). When you structure a skill file well, it becomes trivially portable to an MCP server:
| Skill Section | MCP Equivalent |
|---|---|
| Metadata | Server manifest |
| Interfaces | Tool input schemas |
| Core Logic | Prompt definitions |
| Workflows | Tool implementations |
| Configuration | Server configuration |
A skill's retry logic with exponential backoff belongs in which section?
Why should API endpoints live in Configuration rather than Core Logic?
What makes a skill "discoverable" in an enterprise agent registry?
Pick one of your existing skills (or a steering file in ~/.kiro/skills/). Map its contents to the five sections. What's missing? Most skills have strong Core Logic but weak Metadata and Interfaces — that's the gap to fill first.
Read Lilian Weng's LLM Powered Autonomous Agents for the foundational model of Planning + Memory + Tool Use that these architecture patterns serve.