skill-writing

Automate creation and improvement of agent SKILL.md documentation.

3.5k|155|Updated Mar 12, 2026
One-click install
npx skills add https://github.com/millionco/expect --skill skill-writing-millionco
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: skill-writing
Source: https://github.com/millionco/expect/tree/main/.agents/skills/skill-writing
Command: npx skills add https://github.com/millionco/expect --skill skill-writing-millionco

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This skill provides a structured framework to craft and improve SKILL.md files for agent skills, ensuring consistent frontmatter, clear triggering descriptions, and testable instructions.

Core Features & Use Cases

  • Establish frontmatter with a mandatory name and description to enable discovery and loading.
  • Enforce a three-part description structure (What problem does it solve?, Core Features & Use Cases, Quick Start) to guide activation and usage.
  • Promote an identity-first, instruction-led design with explicit mandatory behaviors, checklists, and anti-pattern guidance.
  • Support a canonical Quick Start sentence that can be executed by an agent to load the skill in context.

Quick Start

Create a new skill by adding a SKILL.md with proper frontmatter and a concise description, then write a RED phase test to validate the skill.

Frequently Asked Questions about skill-writing

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

FAQPage Schema
How do I write an agent instruction SKILL.md file that triggers reliably?▼

To write an agent instruction SKILL.md file that triggers reliably, establish a YAML frontmatter with a mandatory name and description, then use an identity-first design with explicit mandatory behaviors and a single natural-language Quick Start sentence.

Why does my agent ignore instructions in the documentation?▼

Your agent ignores instructions in the documentation when the SKILL.md structure lacks a validated YAML frontmatter, a three-part description, or a code-free Quick Start sentence. Refactoring the prompt structure to enforce these mandatory sections ensures consistent activation.

What is the required structure for a SKILL.md frontmatter description?▼

The required structure for a SKILL.md frontmatter description is a three-part framework addressing what problem the skill solves, core features and use cases, and a Quick Start. This structure guides proper agent activation and skill discovery.

How to create a new skill using test-driven development for documentation?▼

To create a new skill using test-driven development for documentation, add a SKILL.md with proper frontmatter and a concise description, then write a RED phase test to validate the skill's behavior before finalizing the instructions.

Can I include code blocks in the Quick Start section of agent skills?▼

No, you cannot include code blocks in the Quick Start section of agent skills. The Quick Start must be a single natural-language sentence that an agent can execute to load the skill in context without parsing code.

What is the best way to validate frontmatter in skill development?▼

The best way to validate frontmatter in skill development is to ensure the SKILL.md file exists with a YAML frontmatter containing the mandatory name and description fields, enforcing the required three-part description structure for reliable discovery and loading.