skill-authoring

Validate SKILL.md frontmatter and body against the agentskills.io spec.

3|5|Updated Mar 19, 2026

Search Tags:#markdown #specification #activation #triggers #frontmatter #agentskills #skill-authoring

Ready to run

npx skills add https://github.com/ronniegeraghty/hyoka --skill skill-authoring-ronniegeraghty

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: skill-authoring
Source: https://github.com/ronniegeraghty/hyoka/tree/main/.squad/skills/skill-authoring
Command: npx skills add https://github.com/ronniegeraghty/hyoka --skill skill-authoring-ronniegeraghty

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Crafting SKILL.md files that conform to the agentskills.io spec and reliably trigger when relevant is essential for discovery and activation. This guide helps authors create skills under skills/, .squad/skills/, or anywhere a SKILL.md is written, especially when a skill exists but never gets used due to vague or non-triggering descriptions.

Core Features & Use Cases

Enforces a matching frontmatter name with the parent directory to guarantee discoverability.
Defines a clear, imperative body structure (scope, hard rules, examples, anti-patterns) to maximize reliable activation.
Provides best practices for testing activation prompts and avoiding common pitfalls that block execution.

Quick Start

Create a SKILL.md with a frontmatter that includes name and description matching the directory, and write a concise body that follows the spec to activate when relevant.

Frequently Asked Questions about skill-authoring

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I write a SKILL.md frontmatter that reliably triggers agent activation?▼

To ensure reliable SKILL.md frontmatter activation, you must provide a matching name and description in the frontmatter, aligning the name with the parent directory to guarantee agent discoverability.

Why does my agent skill never activate or get used despite being deployed?▼

Your agent skill never activates because the SKILL.md file likely contains vague descriptions or non-spec fields like applyTo, which block execution and prevent the triggers from firing when relevant.

What is the required body structure for a markdown skill specification?▼

The required body structure for a markdown skill specification includes clearly defined scope, hard rules, examples, and anti-patterns, ensuring the imperative instructions maximize reliable activation when triggered.

How do I fix a SKILL.md file that uses non-spec fields like applyTo?▼

To fix a SKILL.md file using non-spec fields like applyTo, remove the invalid fields and ensure the frontmatter and body meet the agentskills.io spec by defining matching name, description, scope, and hard rules.

What are the best practices for testing agent skill activation prompts?▼

Best practices for testing agent skill activation prompts involve validating the imperative body structure and avoiding common pitfalls, ensuring the frontmatter name and description match the directory to fire triggers reliably.

Can I author agent skills outside the standard skills directory?▼

Yes, you can author agent skills outside the standard skills directory by writing a SKILL.md file in locations like .squad/skills/, ensuring the frontmatter and body conform to the agentskills.io specification for proper activation.