skill-writing-guide

Guide authoring of Claude Code Skill units with SKILL.md structure.

148|30|Updated Mar 26, 2026

Search Tags:#documentation #workflow automation #claude code #skill design #yaml frontmatter #prompting

Ready to run

npx skills add https://github.com/aspi6246/Claude-Code-Skills-for-Academics --skill skill-writing-guide-aspi6246

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: skill-writing-guide
Source: https://github.com/aspi6246/Claude-Code-Skills-for-Academics/tree/main/skill-writing-guide
Command: npx skills add https://github.com/aspi6246/Claude-Code-Skills-for-Academics --skill skill-writing-guide-aspi6246

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps you write, refine, and operationalize new Claude Code skills so they are discoverable, reliably triggered, and correctly structured for reuse.

Core Features & Use Cases

Skill structure guidance: Establishes the required root folder naming and mandatory SKILL.md entry point for consistent installation and activation.
Discovery-focused YAML frontmatter: Provides rules for writing an effective name and especially a high-signal description that Claude can match to user intents.
Operational instruction best practices: Recommends concrete examples, “what not to do” constraints, and splitting work into separate skills when workflows overlap.
Iteration workflow: Encourages a test-then-improve loop across multiple realistic prompts so the skill becomes stable over time.

Quick Start

Create a new folder for your workflow and write a SKILL.md file with a clear name and an explicit, package/tool-aware description that matches how users would naturally ask for it.

Frequently Asked Questions about skill-writing-guide

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

FAQPage Schema

How do I create a reusable Claude Code skill from a workflow?▼

To create a reusable Claude Code skill, establish a root folder and write a SKILL.md file containing YAML frontmatter with a clear name and description, alongside a body with actionable conventions and examples.

What makes a Claude skill discoverable and reliably triggered?▼

Claude skill discoverability relies on writing a high-signal description in the YAML frontmatter that matches natural user intents, ensuring Claude can accurately map phrases to the skill's core task.

How do I write YAML frontmatter for Claude Code skills?▼

Write YAML frontmatter for Claude Code skills by defining a concise name and an explicit, tool-aware description that reflects how users naturally ask for the workflow, ensuring proper matching and activation.

What is the best way to structure operational instructions in a SKILL.md file?▼

The best way to structure operational instructions is to include concrete examples, define what not to do constraints, and split overlapping workflows into separate skills to maintain clarity and reliable execution.

When should I split overlapping workflows into separate Claude skills?▼

You should split overlapping workflows into separate Claude skills when their operational instructions conflict or dilute the matching intent, ensuring each SKILL.md remains focused and reliably triggered.