What is the difference between an executable and a reference skill?

Executable skills include scripts that perform operations and require detailed usage notes, while reference skills document patterns or conventions without executable code.

How do I choose which documentation pattern to use?

If your skill includes shell scripts or automated operations, use the Executable pattern; if it describes a coding style or logic pattern, use the Reference pattern.

Why does documentation structure matter for Claude Code?

Consistent structure allows Claude to reliably parse capabilities and helps developers find operational information like exit codes and troubleshooting steps quickly.

What are the required sections for a reference skill?

A reference skill typically requires five sections: Overview, When to Use, Pattern/Procedure, Examples, and References.

Markdown Skill Structure Guide

Name: Markdown Skill Structure Guide
Author: manifoldlogic

bymanifoldlogic

0•

Learning & Documentation

Standardizes SKILL.md documentation patterns to ensure consistent, discoverable, and usable Claude Code plugin capabilities.

This skill provides a comprehensive framework for documenting Claude Code plugins, defining two distinct patterns based on the skill's purpose. It guides developers through creating robust documentation for executable scripts using a 12-section pattern, or lightweight reference documentation using a 5-section pattern. By establishing these standards, it ensures that both AI agents and human developers can easily navigate, understand, and implement domain-specific guidance within the Claude Code ecosystem.

Key Features

01Decision logic for selecting the appropriate documentation depth

020 GitHub stars

03Detailed validation checklists for documentation quality

04Pre-defined frontmatter requirements for skill metadata tracking

05Standardized templates for Executable and Reference skills

06Best practices for documenting script options, exit codes, and troubleshooting

Use Cases

01Onboarding developers to the Claude Code plugin contribution workflow

02Standardizing plugin documentation across large development teams

03Auditing existing skills for documentation completeness and consistency

Key Features

01Decision logic for selecting the appropriate documentation depth

020 GitHub stars

03Detailed validation checklists for documentation quality

04Pre-defined frontmatter requirements for skill metadata tracking

05Standardized templates for Executable and Reference skills

06Best practices for documenting script options, exit codes, and troubleshooting

Use Cases

01Onboarding developers to the Claude Code plugin contribution workflow

02Standardizing plugin documentation across large development teams

03Auditing existing skills for documentation completeness and consistency