SKILL.md
A core configuration file for Agent Skills used to explicitly describe an AI Agent's workflow, reference document paths, and tool configurations. It constrains model behavior to predictable execution paths.
Core Facts
skill.md is written in Markdown format and contains metadata (skill name and description) as well as detailed execution instructions.
A complete Skill contains a Skill.md main document, a Reference folder, a Script folder, and an Assets folder.
Skills are essentially Markdown files stored in the project's .claude/ directory.
Timeline (last 90 days)
research-ledger is an MIT-licensed open-source tool in the form of a SKILL.md folder that turns an AI assistant capable of reading skills into a disciplined research partner.
Skill Constellations (2026-10-09) traced the copy-paste supply chain of agents' SKILL.md files across 2.19 million GitHub adoptions, finding that security fixes rarely propagate to downstream copies, and that star counts are a poor proxy for trustworthy provenance.
The ghealth repository comes with two SKILL.md skill files, covering configuration and login and the pitfalls of 40 data types respectively, which can be registered via npx skills add into agent frameworks that support this convention (such as Claude Code and Codex).
The SKILL.md format is becoming an open convention across agents (the Agent Skills format), and any agent that supports this format can read and invoke these Skills.
In the aggregation repository, skill descriptions are validated on every sync: double quotes are used for compatibility with strict YAML parsers, the length must not exceed 600 characters, and they must include Use when and Not for sentences as well as a Limits section.
SKILL.md files follow standard Markdown syntax and have no programming barrier for authors.
The Skill folder must contain a file named SKILL.md, and the filename cannot be changed.
To have the agent call files in additional subfolders, it must be explicitly specified in SKILL.md which file in which folder to call; otherwise the agent cannot determine this on its own.
SKILL.md typically adopts a hierarchical structure: the top layer retains only skill names and functional descriptions, and after a call is determined, detailed instructions, examples, and resource files are dynamically injected
A Skill only needs to contain a single SKILL.md file to run, and all other components (scripts, references, resources, etc.) are optional.
12 more timeline events
All Facts (20)
skill.md is written in Markdown format and contains metadata (skill name and description) as well as detailed execution instructions.
80%VerifiedA complete Skill contains a Skill.md main document, a Reference folder, a Script folder, and an Assets folder.
80%VerifiedSkills are essentially Markdown files stored in the project's .claude/ directory.
75%VerifiedThe SKILL.md metadata must include at minimum two fields: name and description.
65%VerifiedThe SKILL.md file begins with a metadata section (Frontmatter) enclosed by three dashes, which is the key to the Skill being recognized by AI tools.
65%VerifiedIn the Skill directory structure, the development process corresponds to the SKILL.md file, reference documentation corresponds to the references directory, development tools correspond to the scripts directory, and static assets correspond to the assets directory.
65%VerifiedA Skill is essentially a natural-language Prompt, placed in a special file called skill.md.
65%UnverifiedA Skill only needs to contain a single SKILL.md file to run, and all other components (scripts, references, resources, etc.) are optional.
60%UnverifiedSKILL.md is written in Markdown format, with the top of the file carrying metadata via YAML Front Matter or a header block, containing fields such as name, description, and trigger.
60%UnverifiedSkill Constellations (2026-10-09) traced the copy-paste supply chain of agents' SKILL.md files across 2.19 million GitHub adoptions, finding that security fixes rarely propagate to downstream copies, and that star counts are a poor proxy for trustworthy provenance.
50%UnverifiedThe ghealth repository comes with two SKILL.md skill files, covering configuration and login and the pitfalls of 40 data types respectively, which can be registered via npx skills add into agent frameworks that support this convention (such as Claude Code and Codex).
50%UnverifiedThe SKILL.md format is becoming an open convention across agents (the Agent Skills format), and any agent that supports this format can read and invoke these Skills.
50%UnverifiedIn the aggregation repository, skill descriptions are validated on every sync: double quotes are used for compatibility with strict YAML parsers, the length must not exceed 600 characters, and they must include Use when and Not for sentences as well as a Limits section.
50%UnverifiedSKILL.md files follow standard Markdown syntax and have no programming barrier for authors.
50%UnverifiedThe Skill folder must contain a file named SKILL.md, and the filename cannot be changed.
50%UnverifiedTo have the agent call files in additional subfolders, it must be explicitly specified in SKILL.md which file in which folder to call; otherwise the agent cannot determine this on its own.
50%UnverifiedSKILL.md typically adopts a hierarchical structure: the top layer retains only skill names and functional descriptions, and after a call is determined, detailed instructions, examples, and resource files are dynamically injected
50%UnverifiedA truly powerful Skill is often a combination of SKILL.md plus scripts, references, and template resources, with the MD file serving only as the entry point and documentation.
50%UnverifiedThe more content in the body of SKILL.md, the larger the context window consumed during invocation, which may prevent the Agent from fully recognizing and adhering to the specifications.
50%UnverifiedSKILL.md is essentially a structured system prompt that compresses the model's output space through explicit rules to achieve deterministic constraints, reducing hallucinations and error rates.
50%