Skip to content

SPECIFICATION.md

Latest commit

 

History

History
146 lines (102 loc) · 7.74 KB

SPECIFICATION.md

File metadata and controls

146 lines (102 loc) · 7.74 KB
Raw

Agent Skill Specification

A personal, opinionated variant of the Agent Skills specification. The upstream format requires YAML frontmatter for metadata. This variant deliberately omits frontmatter entirely, and all metadata and instructions live inside a single XML-mixed <skill> element in the Markdown body.

Directory Structure

A skill is a directory whose name matches the root tag's name attribute and contains, at minimum, a SKILL.md file:

skill-name/
├── assets/           # Optional: static resources (templates, images, lookup tables, schemas)
├── references/       # Optional: on-demand documentation loaded only when needed
├── scripts/          # Optional: self-contained executable code the agent can run
└── SKILL.md          # Required: XML-mixed body, no frontmatter

SKILL.md Format

The first non-empty line of the file is the opening <skill ...> tag. Nothing sits outside <skill> … </skill>.

Root Element

The entire document is wrapped in a single <skill> element. Metadata that upstream places in frontmatter is expressed here as XML attributes on the root tag.

<skill name="skill-name">
...
</skill>

Root Attributes

Attribute Required Type Constraints
name Yes string 1-64 chars. Lowercase a-z, 0-9, and hyphens -. Must not start/end with - or contain --. Must match the parent directory name.
self-invoked No boolean "true" if the skill may auto-activate based on <purpose> matching. "false" if it only runs when explicitly invoked by the user. Default: "true".
license No string License name (e.g. "MIT", "Apache-2.0", "Proprietary") or reference to a bundled file (e.g. "LICENSE.txt").
compatibility No string 1-500 chars. Environment requirements (product, packages, network access, etc.). Include only when the skill has non-obvious dependencies.
version No string Free-form version identifier (e.g. "1.0", "2026.03").

Additional custom attributes are allowed for tooling-specific metadata. Use kebab-case and prefer short names.

Section Tags

Three section tags are required, in this exact order:

Tag Purpose
<purpose> Overall goal of the skill, stated as a single sentence.
<guidelines> Non-negotiable rules the agent must always obey.
<implementation> Concrete step-by-step blueprint, process, rules, tables, and examples.

Body Content Rules

  1. Use only the section tags above, in the order above.
  2. Write Markdown directly inside tags. Do not wrap section content in code fences.
  3. Insert a blank line after every opening tag and before every closing tag.
  4. Do not add an ## heading that repeats the tag name (e.g. no ## Purpose inside <purpose>).
  5. Use ### subheadings for nested organization within a section.

Word Count Guidance

Recommended budgets keep the <purpose> body and every hint attribute scannable rather than prose. These are authoring recommendations; the reference parser does not enforce them.

Location Recommended minimum Recommended maximum
<purpose> body (single line) 9 13
hint="..." attribute on tags 6 9

The <purpose> body should be a single declarative sentence describing the skill's overall use end-to-end. It replaces the upstream description frontmatter field.

hint is optional structurally and recommended on all three required tags.

Examples (word counts shown):

  • <purpose> body - Perform one focused task the agent can invoke on demand always. (11)
  • <purpose> body - Produce a deterministic output shaped exactly by the input contract. (10)
  • <purpose> hint - Overall goal the agent must achieve here (7)
  • <guidelines> hint - Non-negotiable rules the agent must always obey (7)
  • <implementation> hint - Concrete blueprint the agent must follow step by step (9)

Full Template

<skill name="skill-name">
<purpose hint="Overall goal the agent must achieve here">

[Single sentence, recommended 9-13 words, describing the skill's overall use.]

</purpose>
<guidelines hint="Non-negotiable rules the agent must always obey">

- [Rule 1]
- [Rule 2]
- [Rule N]

</guidelines>
<implementation hint="Concrete blueprint the agent must follow step by step">

## [Process Section Heading]

1. **Step-1** - Description
2. **Step-2** - Description

## [Rules or Tables Section]

| Column | Column |
| ------ | ------ |
| Value  | Value  |

</implementation>
</skill>

Progressive Disclosure

Discovery loads content in layers:

  1. Root attributes + <purpose> - identify the skill and describe when to activate it.
  2. Full SKILL.md body - loaded when the skill activates.
  3. Resources - files under assets/, references/, scripts/ load only when required.

Keep SKILL.md under 500 lines. Move detailed material to references/.

File References

Use relative paths from the skill root, one level deep:

See [the reference guide](references/REFERENCE.md) for details.
Run scripts/extract.py to process input.

Differences From The Upstream agentskills.io Specification

Aspect Upstream Personal Variant
Frontmatter Required (name, description, ...) Not used. File contains no frontmatter block at all.
Metadata location YAML frontmatter fields XML attributes on the <skill> root tag
Skill identity Frontmatter name field name attribute on <skill>
Auto-invocation Implicit / product-specific Explicit self-invoked boolean attribute on <skill> ("true" / "false")
Activation hints Frontmatter description field (max 1024 chars) <purpose> body, recommended 9-13 words (not parser-enforced)
License / version Frontmatter fields license / version attributes on <skill>
Body format Free-form Markdown Markdown wrapped in <skill> + three required section tags in fixed order
Section structure Author's choice Fixed: <purpose> → <guidelines> → <implementation>
Semantic hints Not defined hint="..." attribute on section tags, recommended 6-9 words