What is the recommended file limit for a SKILL.md file?

To maintain efficiency and preserve the context window, the main SKILL.md body should be kept under 500 lines, using progressive disclosure to point to detailed materials.

Why does this guide suggest using the gerund form for naming?

Naming skills with the gerund form (e.g., 'analyzing-data') clearly defines the active capability, making it easier for Claude to identify the correct skill for a specific task.

What are 'Degrees of Freedom' in skill authoring?

It is a strategy that matches the specificity of instructions to the task's fragility, ranging from high freedom (general text) to low freedom (specific scripts).

How do I ensure my custom skill is discoverable?

Follow the YAML frontmatter requirements, use specific keywords in the description, and adhere to the standardized naming conventions outlined in the guide.

Claude Skill Authoring Guide

Name: Claude Skill Authoring Guide
Author: sumik5

bysumik5

•

Learning & Documentation

Provides standardized guidelines and best practices for creating high-quality, token-efficient Claude Agent Skills.

The Claude Skill Authoring Guide is a comprehensive framework designed to help developers build, refine, and maintain high-performance Claude Code Skills. By emphasizing the principles of conciseness and progressive disclosure, this skill ensures that custom agent capabilities remain discoverable and efficient without exhausting the shared context window. It offers structured workflows for identifying capability gaps, implementing standardized YAML frontmatter, and organizing multi-file skill architectures to optimize Claude's reasoning and execution patterns across diverse development tasks.

Key Features

01Standardized naming conventions and YAML frontmatter requirements for better discovery.

02Step-by-step workflow for identifying, writing, and iteratively testing new skills.

03Progressive disclosure patterns to keep main skill files under 500 lines.

04Categorized 'Degrees of Freedom' to match instruction specificity to task fragility.

051 GitHub stars

06Anti-pattern detection to prevent verbosity and inconsistent terminology.

Use Cases

01Architecting new custom skills for specialized team workflows or internal APIs.

02Refactoring existing skill files to reduce token consumption and improve agent focus.

03Standardizing documentation and skill structures across large, multi-contributor repositories.

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add sumik5/dotfiles authoring-skills

For use in Claude.ai and ChatGPT

Download Skill