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.