holocron/plugins/kyberforge/docs/agentskillsio/specification.md

topic, source_keys

topic	source_keys
agentskills-specification	agentskills-spec

Frontmatter fields

Field	Required	Constraints
name	Yes	1–64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen. No consecutive hyphens (--). Must match the parent directory name.
description	Yes	1–1024 characters. Describes what the skill does and when to use it.
license	No	License name or reference to a bundled license file.
compatibility	No	1–500 characters. Environment requirements: intended product, required system packages, network access needs. Most skills don't need this.
metadata	No	Arbitrary key-value map. Use for author, version, category, and any project extensions not defined by the spec.
allowed-tools	No	Space-separated string of pre-approved tools. Experimental — support varies by client.

Minimal example

---
name: skill-name
description: A description of what this skill does and when to use it.
---

Extended example

---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
  category: document
allowed-tools: Bash(python3:*) Read Write
---

name field rules

Valid: pdf-processing, data-analysis, code-review

Invalid:

• PDF-Processing — uppercase not allowed
• -pdf — cannot start with hyphen
• pdf--processing — consecutive hyphens not allowed

The name value must exactly match the parent directory name. A skill at .agents/skills/my-tool/SKILL.md must have name: my-tool.

description field guidance

The description carries the entire burden of triggering. Agents read only name and description at startup. Write it as a trigger — describe both what the skill does and when to use it.

Good:

description: >
  Analyze CSV and tabular data files — compute summary statistics,
  add derived columns, generate charts, and clean messy data. Use this
  skill when the user has a CSV, TSV, or Excel file and wants to explore,
  transform, or visualize the data, even if they don't explicitly mention
  "CSV" or "analysis."

Poor:

description: Helps with PDFs.

Hard limit: 1024 characters. Descriptions tend to grow during optimization — check length before committing.

Body content

No format restrictions. Write whatever helps agents perform the task effectively.

Recommended sections:

• Step-by-step instructions
• Examples of inputs and outputs
• Common edge cases

The agent loads the entire body once the skill is activated. Keep SKILL.md under 500 lines. Move detailed reference material to separate files in references/ or similar directories.

Optional directories

scripts/

Executable code agents can run. Scripts should be self-contained, include helpful error messages, and handle edge cases gracefully. See the scripts reference for design guidance.

references/

Additional documentation agents can read when needed. Keep files focused — agents load them on demand, so smaller files mean less context use. Common files: REFERENCE.md, FORMS.md, domain-specific files (finance.md, legal.md).

assets/

Static resources: templates, images, data files (lookup tables, schemas).

File references

Use relative paths from the skill root when referencing other files:

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

Keep references one level deep from SKILL.md. Avoid deeply nested reference chains.

Progressive disclosure levels

1. Metadata (~100 tokens): name and description — loaded at startup for all skills
2. Instructions (<5000 tokens recommended): full SKILL.md body — loaded on activation
3. Resources (as needed): files in scripts/, references/, assets/ — loaded only when required

Validation

The skills-ref reference library validates SKILL.md frontmatter and naming conventions:

skills-ref validate ./my-skill

Source: https://github.com/agentskills/agentskills/tree/main/skills-ref