write-a-skill

Create SKILL.md files with frontmatter and optional references or scripts.

1|Updated Mar 15, 2026
One-click install
npx skills add https://github.com/mappa-ai/skills --skill write-a-skill-mappa-ai
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: write-a-skill
Source: https://github.com/mappa-ai/skills/tree/main/utils-skills/write-a-skill
Command: npx skills add https://github.com/mappa-ai/skills --skill write-a-skill-mappa-ai

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This meta-skill guides teams to craft well-structured agent skills with clear frontmatter, templates, and bundled resources, improving discoverability and maintainability.

Core Features & Use Cases

  • Provides a SKILL.md template and recommended file structure (REFERENCE.md, EXAMPLES.md, scripts/) for new skills.
  • Explains when to split content and how to bundle optional resources for deterministic tasks.
  • Serves as a practical checklist to align teams on skill quality and consistency.

Quick Start

Create a new SKILL.md for your skill following the template and add optional references or scripts as needed.

Frequently Asked Questions about write-a-skill

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

FAQPage Schema
How do I structure a new agent skill with proper frontmatter and templates?

To structure an agent skill, create a SKILL.md file with frontmatter containing a name and description, then organize optional references like REFERENCE.md and EXAMPLES.md alongside scripts for scalable skill ecosystems.

What is progressive disclosure in skill authoring and when should I split content?

Progressive disclosure in skill authoring separates core instructions in SKILL.md from detailed context in optional files, splitting content when reference materials or scripts grow too large for deterministic task execution.

How do I bundle optional resources and scripts for deterministic agent tasks?

Bundle optional resources for deterministic tasks by placing reference files and scripts in a dedicated directory alongside SKILL.md, ensuring consistent usage across the skill ecosystem for reliable execution.

What frontmatter fields are required when authoring a SKILL.md file?

Required frontmatter fields for a SKILL.md file include a name and description, ensuring the skill is discoverable and maintainable within scalable skill ecosystems.

Does my team need a checklist to align on agent skill quality and consistency?

A checklist helps teams align on agent skill quality by standardizing frontmatter, file structure, and optional resource bundling, improving discoverability and maintainability across the skill ecosystem.

When should I not use separate reference files for skill authoring?

Avoid separate reference files when a skill's logic is simple enough to fit entirely within SKILL.md, as unnecessary splitting can reduce maintainability and fragment the skill's core instructions.