Claude Code Skills: A Practical Guide to Building Reusable AI Workflows

You use Claude Code every day — chatting, writing code, editing files. But do you find yourself repeating the same instructions every time you start a new session? Skills are Claude Code's "reusable instruction sets" that let you package your recurring workflows into one-click automation systems. This guide walks you through understanding Skills to designing a complete workflow, using our own production system as a real-world example.

TL;DR

• Skills are reusable instruction sets written in Markdown that turn Claude Code from a "chat assistant" into a "workflow automation engine"
• Understanding the division of labor between CLAUDE.md (always-loaded rules) vs Skills (on-demand workflows) vs Hooks (auto-triggered scripts) is the foundation of good workflow design
• A SKILL.md only needs frontmatter (description) plus markdown instructions, ideally under 500 lines
• Real-world case study: Shareuhack runs 13 Skills powering a complete content pipeline from ideation to publishing
• Watch out for context budget limits (2% of the context window) — more Skills isn't always better

Why You Need Skills: From "Copy-Pasting Instructions" to "One-Click Workflows"

If any of these sound familiar, you need Skills:

• Every new session starts with pasting the same "please follow this format..." instructions
• You explain the same workflow (writing articles, code review, compiling reports) from scratch every time
• Different team members give Claude inconsistent instructions, producing inconsistent results

The core problem Skills solve is simple: package your recurring instructions into reusable modules. Write them once, then trigger with /skill-name — no need to re-teach Claude every time.

Think of Skills as SOP manuals you write for Claude. You wouldn't verbally explain a process to a new employee on their first day and expect them to remember everything — you'd give them a document. Skills are that document.

Work types that benefit from Skills:

• Processes with fixed steps: code review checklists, article writing workflows, PR templates
• Tasks requiring specific output formats: commit message formatting, report templates, changelog generation
• Multi-stage workflows: research → outline → draft → review, each stage with different rules and deliverables

Skills vs CLAUDE.md vs Hooks: A Decision Framework for the Three-Layer System

Claude Code has three customization mechanisms, and mixing them up is the most common mistake. According to the official documentation, here's how they divide responsibilities:

What you're defining	Where it goes	How it loads	Best for
Rules for every conversation	CLAUDE.md	Auto-loaded every session	Brand voice, forbidden patterns, project conventions
Complete workflow for a specific task	Skills (SKILL.md)	Loaded when Claude deems it relevant, or manually triggered	Writing articles, code review, research reports
Checks that must run automatically every time	Hooks (.claude/hooks/)	Event-driven auto-execution	Lint, format, commit message validation

CLAUDE.md is your "always-in-effect company policy." It loads at the start of every session and permanently occupies context. Use it for concise, universally applicable rules like "always respond in English" or "never use this API pattern."

Skills are your "procedure manuals." At startup, only the description (a one-liner summary) enters the context. Claude loads the full content only when it determines the current task is relevant. You can also trigger manually with /skill-name. This design avoids wasting tokens.

Hooks are your "automated security gates." They execute shell commands or HTTP requests based on events (like tool calls or notifications) with matcher conditions, without requiring Claude's judgment. Example: automatically running a linter before every commit.

Common mistakes:

• Stuffing everything into CLAUDE.md: Your code review workflow is 200 lines, but 90% of conversations don't need it. Putting it in CLAUDE.md wastes those tokens in every conversation. Make it a Skill instead.
• Writing global rules as Skills: A rule like "all code must use TypeScript" won't necessarily load every time if it's a Skill. Put it in CLAUDE.md.

Decision principle: Ask yourself, "Is this rule needed in every conversation?" If yes, put it in CLAUDE.md. If only needed for specific tasks, make it a Skill. If it must run automatically without conditions, use Hooks.

How to Write a SKILL.md: Structure Breakdown and Design Principles

According to the official documentation, a SKILL.md has two parts:

---
description: "Perform code review, checking code quality, security, and performance"
---

# Code Review Skill

## Step 1: Read Changes
Read the git diff to understand the scope and purpose of changes.

## Step 2: Quality Check
Check each of the following items...

YAML Frontmatter (between the --- markers) tells Claude what this Skill does. All fields are optional, but description is strongly recommended — it's what Claude uses to decide whether to load the Skill.

Markdown Body is the full instruction set Claude follows after loading the Skill.

Key Advanced Frontmatter Fields

Field	Purpose	Example
description	How Claude decides whether to load it (recommended)	"Research a topic and produce a Research Brief"
user-invocable	Whether users can trigger it manually with /command	true
allowed-tools	Restrict which tools the Skill can use	["Read", "Grep", "WebSearch"]
model	Specify the execution model	"claude-sonnet-4-6"
agent	Specify subagent type with context: fork	"research"

The Progressive Disclosure Pattern

Official best practices recommend keeping SKILL.md under 500 lines. For longer content, split detailed references into separate files:

.claude/skills/
  my-skill/
    SKILL.md          ← Main instructions (under 500 lines)
    templates/         ← Template files
    reference.md       ← Detailed reference material

Use Read instructions in SKILL.md to guide Claude to load separate files only when needed, rather than loading everything at once. This is Progressive Disclosure: provide core instructions first, expand into details when necessary.

Real-World Example: The brainstorming Skill from obra/superpowers

Let's look at a widely-used Skill from the real world. obra/superpowers is an open-source collection of Claude Code Skills. Its brainstorming Skill demonstrates excellent design:

---
name: brainstorming
description: "You MUST use this before any creative work - creating features,
  building components, adding functionality, or modifying behavior. Explores
  user intent, requirements and design before implementation."
---

# Brainstorming Ideas Into Designs

## Overview
Help turn ideas into fully formed designs and specs through natural
collaborative dialogue. Start by understanding the current project context,
then ask questions one at a time to refine the idea.

## Checklist
1. **Explore project context** — check files, docs, recent commits
2. **Ask clarifying questions** — one at a time, understand purpose/constraints
3. **Propose 2-3 approaches** — with trade-offs and your recommendation
4. **Present design** — get user approval after each section
5. **Write design doc** — save to docs/plans/
6. **Transition to implementation** — invoke writing-plans skill

This Skill demonstrates several good design principles:

• Clear, assertive description: Uses "You MUST use this before any creative work" to ensure Claude loads it in relevant contexts
• Hard Gate: Explicitly forbids writing any code before the design is approved
• Checklist-driven: Step-by-step execution with clear deliverables at each step
• Chains to the next Skill: Automatically transitions to the writing-plans Skill on completion, forming a pipeline

You can clone this repo directly into ~/.claude/skills/ for immediate use, or reference its structure to design your own Skills.

Real-World Case Study: Shareuhack's 13-Skill Content Pipeline

Theory is nice, but let's look at a system that's actually running in production. Shareuhack (the site you're reading right now) uses Claude Code Skills to power a complete content pipeline, with AI agents collaborating from topic selection through publishing.

Architecture Overview

Global rules in CLAUDE.md: Brand voice (authoritative yet practical), frontmatter format specs, absolute prohibitions (no fabrication, no GitHub alerts). These are needed in every conversation, so they go in the always-loaded CLAUDE.md.

One Skill per stage:

/ideate → /research → /setup-notebook → /architect → /write → /content-review → /translate

Each Skill handles one stage: /ideate does quick screening (decide in under 3 minutes if an idea is worth pursuing), /research launches a subagent for deep market research, /architect designs the article outline, /write produces the draft from the outline, /content-review runs a dual-perspective review with a 40-point scoring system, and /translate handles multilingual localization.

Three Key Design Decisions

1. Every Skill has a HITL (Human-in-the-Loop) checkpoint

Each Skill pauses after completion, waiting for user confirmation before proceeding to the next stage. This isn't a technical limitation — it's intentional. From experience, when AI runs the entire pipeline automatically without intervention, the final output quality is noticeably lower than when a human reviews and adjusts at each stage.

## HITL Rules
Must stop after completion, display summary, and wait for user response:
- Enter `yes` → proceed to next stage
- Enter `revise: [details]` → adjust and re-confirm
- Enter `no` → pause

2. Subagents isolate WebSearch noise

Skills like /research and /write that need external information don't search directly in the main conversation. Instead, they spawn an independent subagent for WebSearch, passing only structured summaries back to the main conversation. This keeps the main context clean from search result noise.

3. Skills communicate through pipeline files

Each article has a content/pipeline/[slug].md file. Each Skill appends its output to this file after execution. The next Skill reads the same file to pick up where the previous stage left off. This is more reliable than passing data through context, since context disappears when a session ends, but pipeline files persist.

Context Budget Management

The descriptions of all 13 Skills combined must stay within the context budget. According to the official documentation, Skills get 2% of the context window, with a fallback cap of 16,000 characters. In practice:

• Keep each Skill's description to 1-2 sentences (roughly 50-100 characters)
• Periodically check with /context to see if any Skills are being excluded
• Consider removing or merging rarely-used Skills

Results

This system took us from "spending 3 hours manually guiding AI per article" to "running the pipeline in about 1 hour for publish-ready drafts." More importantly, quality became consistent. Regardless of who launches the pipeline, output goes through the same quality gates.

Risk Disclosure and Caveats

Skills aren't a silver bullet. Here are the limitations you need to know:

Skill loading is non-deterministic. Claude decides whether to load a Skill based on how relevant it seems to the current task. If your description is too vague or the conversation doesn't match the Skill's description well enough, Claude may skip it. Mitigation: write clear, specific descriptions, and set user-invocable: true so you can trigger manually with /command.

Context budget has a ceiling. When you have too many Skills, some will be excluded from the context. Use the /context command to check which ones got excluded. To adjust the budget cap, set the SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable.

Maintenance cost is real. Skills aren't write-once-and-forget. As projects evolve, tools update, and processes change, Skills go stale. Our approach: do a monthly Skills review to check which ones no longer match reality.

Security requires attention. Skills can restrict which tools Claude can use during execution via the allowed-tools field. If your Skill involves sensitive operations (like deployment or file deletion), explicitly limit the available tools.

Not everything needs to be a Skill. If you're only doing a task once, just explain it in the conversation. The ROI of Skills comes from repeated use. A rough heuristic: if you expect to run the same workflow more than 3 times, it's worth making a Skill.

Conclusion

Skills transform Claude Code from "a chat tool that needs manual guidance every time" into "a workflow engine you can launch with one click." The core concept is simple: write your workflow in Markdown, and let Claude execute it.

Your suggested first step: Identify one workflow you repeat most often (code review, writing weekly reports, organizing meeting notes) and spend 10 minutes writing a SKILL.md. Don't aim for perfection — start with the simplest version and refine it after a few uses.

If you want to build more complex automation systems, combine Skills with Hooks for event-driven checks, or use Subagents to orchestrate collaboration between Skills. Those advanced topics are yours to explore.