How to write Claude Code Skills: official rules and real examples

If you keep pasting the same checklist into Claude Code chats, context bloats and team reproducibility drops. Installing every popular .claude/skills pack by star count creates a different failure mode: unexpected auto-invocation and command-name collisions.

📑Table of Contents

Evidence and scope
Why “how to write a good Skill” is an operational question
Official skill boundaries — location, invocation, configuration
Official best practices — description, freedom, progressive disclosure
Public examples compared — daily crystallization vs SDLC packs
48-hour install checklist and stop conditions
FAQ
Summary and next actions

This article is a practical decision guide for Claude Code Skills (SKILL.md): when to extract a skill, how to write it, and how to evaluate third-party packs before install.

Evidence and scope

Evidence comes from these independent sources:

Bookmark popularity is discovery context only—not factual proof. Here we focus on official boundaries, design contrasts, and a 48-hour checklist.

Why “how to write a good Skill” is an operational question

Reader pain vs discovery signals

The real pain is not “missing famous packs.” It is:

repeated paste of procedures
bloated CLAUDE.md sections
skills that fire when they should not

Public “skill rushes” and star counts are discovery signals, not design quality.

Official timing and CLAUDE.md contrast

Official guidance: create a skill when you keep pasting the same instructions, checklist, or multi-step procedure—or when a CLAUDE.md section has grown into a procedure rather than a fact.

CLAUDE.md is always on
skill bodies load when used

Moving long reference material into skills keeps unused cost near zero.

Commands vs skills, and the first goal

Custom commands under .claude/commands/ continue to work, while skills add supporting files, invocation control, and automatic loading. Skills are not merely renamed commands; they are discoverable procedures that expand only when needed.

Reader implication: first goal is not “install everything famous.” Extract one repeated team procedure into a single skill candidate.

Official skill boundaries — location, invocation, configuration

Before polishing prose, lock where it lives, who can call it, and what auto-invocation is allowed.

Location hierarchy

Scope	Example path	Typical use
Personal	`~/.claude/skills/<name>/SKILL.md`	Cross-project personal workflows
Project	`.claude/skills/<name>/SKILL.md`	Repo conventions and team procedures
Plugin / Enterprise managed	managed distribution	Org standards and controlled rollout

On name collisions, priority is enterprise > personal > project; any of these can override a bundled skill. Monorepos may use nested .claude/skills/ directories, with qualified names such as apps/web:deploy when needed.

Source: Claude Code Skills (as of July 2026)

Invocation and frontmatter

Two main invocation paths:

Explicit /skill-name
Model auto-load when description matches the conversation

For side effects (deploy, commit, production config), set disable-model-invocation: true so only users trigger the skill. Background knowledge skills can use user-invocable: false to hide from the / menu.

Useful frontmatter levers include:

description
allowed-tools
paths
context: fork
hooks

Dynamic context injection with `!command`` can run commands such asgit diff` before the skill body loads.

Implication: disable auto-invocation for high-risk skills, and inventory personal vs project name collisions before install.

Official best practices — description, freedom, progressive disclosure

A good skill is not a long essay. It is discoverability plus token economy.

Description is the discovery surface

name: max 64 characters; lowercase, numbers, hyphens; reserved words claude / anthropic forbidden
description: required-like field, max 1024 characters; third person; what + when
Avoid vague lines such as “Helps with documents”, “Processes data”, “Does stuff with files”
Prefer gerund names (processing-pdfs); avoid helper / utils

Metadata is cheap to list at session start; the skill body is loaded when relevant. Weak descriptions fail to trigger; procedure dumps in description tempt the model to skip the body.

Degrees of freedom

Match instruction rigidity to task fragility:

High: code review-style judgment with multiple valid approaches
Medium: template plus parameters
Low: brittle ordered operations such as migrations

Progressive disclosure

Keep SKILL.md body under 500 lines when practical
Split details into supporting files; keep references one level deep
Treat SKILL.md as TOC + overview; load scripts and examples on demand

Source: Skill authoring best practices (as of July 2026)

Official checklists also push multi-model testing (Haiku / Sonnet / Opus) and checks such as:

concrete examples
consistent terminology
honest dependencies
verification steps for high-impact actions
multiple evals
real usage scenarios

Implication: write description first; keep the body as a map plus the branches you actually need.

Public examples compared — daily crystallization vs SDLC packs

Two public packs often appear in the same conversation, but they optimize different goals. Do not install both as full routers at once.

Comparison matrix

Dimension	Daily crystallization (mattpocock/skills-style)	SDLC pack (addyosmani/agent-skills-style)
Focus	Real engineer daily workflows	Define→Ship coverage via skill packs
Invocation design	Explicit user vs model separation	Many skills + eval harness for trigger quality
Signature ideas	writing-great-skills / grilling loops	Common Rationalizations, Red Flags, Verification
Growth signals	deprecated / in-progress visibility	eval cases, CI deterministic tiers
Install risk	Adopting strong personal philosophy unfiltered	Command collisions / dual routers with other packs

Source context

Sources: mattpocock/skills, addyosmani/agent-skills (public pages observed July 2026)

Daily crystallization (mattpocock/skills-style)

mattpocock/skills positions itself as “Skills for Real Engineers. Straight from my .claude directory.”

Look for:

user/model separation
meta skills such as writing-great-skills
visible deprecate/in-progress paths

SDLC pack (addyosmani/agent-skills-style)

addyosmani/agent-skills positions itself as “Production-grade engineering skills for AI coding agents.”

Typical emphasis includes:

multi-agent layouts
eval runners
process safeguards such as rationalization tables

For a deeper product-facing take on that pack, see Agent Skills overview on devgent.

Patterns that transfer

Star counts move daily and are discovery-only. Patterns that transfer across both packs:

Win on description quality
Do not put everything in SKILL.md
Choose user vs model invocation deliberately
Block shortcut rationalizations and unverified steps

Implication: read one skill that matches your workflow, check name collisions, then cherry-pick—do not bulk-merge philosophies.

48-hour install checklist and stop conditions

Turn the guidance into tickets you can finish in 48 hours. Success is intentional triggering + reproducible steps, not skill count.

Checklist

Pick a candidate: a procedure pasted weekly, or a CLAUDE.md process section
Choose location: personal for cross-project habits; project for repo conventions
Write description: third person, what + when; avoid vague “documents/data/files” lines
Choose invocation: side effects → disable-model-invocation: true; exploratory helpers may be model-invoked

Validate the implementation

Keep body lean: under 500 lines; one-level supporting files only
Test both paths: explicit /name and natural-language triggers on the models you actually use
Third-party packs: trust check → read SKILL.md/scripts → install one skill only
Collision control: avoid dual routers; simultaneous full installs of two pack families are a stop candidate

Security checks before third-party packs

Anthropic Engineering notes that skills may bundle instructions and scripts, and that untrusted sources can enable data theft or environment compromise. Even popular repos deserve inspection:

Is the publisher trusted under your org policy?
What is the scope of allowed-tools, shell, and network access?
Do scripts stay least-privilege and avoid exfiltrating secrets?
Any personal vs project name collisions?
Install one skill first and watch for unintended auto-invocation

Source: Equipping agents with Agent Skills (as of July 2026)

Stop conditions

Installing by star count without reading SKILL.md
Leaving deploy-like skills model-invocable
Ambiguous descriptions with unclear trigger conditions
Unassessed overwrite of an existing same-name skill

By the end of 48 hours, the reader should be able to: (a) pick one repeated procedure as a Skill candidate, (b) write a description with what+when, (c) decide user-invoked vs model-invoked, and (d) if installing a public pack, read SKILL.md and try only one skill. Only after (a)–(c) plus a successful explicit /name invocation should public packs enter the plan.

FAQ

Can CLAUDE.md replace Skills entirely?

As always-on procedures grow, they consume context and add noise. Official guidance treats procedure-heavy CLAUDE.md sections as skill extraction candidates (Claude Code Skills).

Can description hold the full procedure?

Include what + when, but dumping the full procedure risks skipping the body. Put details in SKILL.md and one-level references (best practices).

Is it safe to install an entire famous GitHub skills repo?

Only after trust checks and content review. Dual full routers raise collision and philosophy-mix risk. Install one skill at a time (Anthropic Engineering).

How should I choose user-invoked vs model-invoked?

Irreversible or side-effecting work: user-only (disable-model-invocation). Exploratory helpers: description-driven auto-invocation may be fine (Claude Code Skills).

Summary and next actions

Three takeaways:

Skills offload procedure bloat from CLAUDE.md and load steps only when needed
Quality hinges on description (what+when), freedom level, and 500-line / one-level progressive disclosure
Public packs are teaching materials first; install with security review and collision checks, one skill at a time

Your 48-hour pilot

Within 48 hours, take these four contracted next actions:

(a) Pick one repeated procedure as a Skill candidate (something you paste weekly, or a CLAUDE.md process section)
(b) Write a description with what+when (third person; avoid vague “documents/data/files” lines)
(c) Decide user-invoked vs model-invoked (side effects → disable-model-invocation: true)
(d) If installing a public pack, read SKILL.md and try only one skill (after trust and collision checks)

Validate before expanding

Run checklist items 1–6 to finish (a)–(c) plus a successful explicit /name invocation, then consider (d). Start with one self-authored skill and keep the install surface small until intentional triggering and reproducible steps are proven.

Continue with the Agent Skills overview for SDLC-pack decisions.

Related articles:

Related new article:

Codex Plugin for Claude Code Review and Rescue Setup – This published update adds current operational context for How to write Claude Code Skills: official rules and real examples.
Keystroke n8n Alternative for Claude Code and Cursor: Setup and Fit Check – This published update adds current operational context for How to write Claude Code Skills: official rules and real examples.
1Password for Claude zero-exposure: login and OTP without sharing secrets – This published update adds current operational context for How to write Claude Code Skills: official rules and real examples.
Ledger Agent Stack for AI Agents: Propose-Only Wallets with Hardware Approval – This published update adds current operational context for How to write Claude Code Skills: official rules and real examples.
Claude Code Setup plugin: codebase-aware hooks, MCP, skills recommendations – This published update adds current operational context for How to write Claude Code Skills: official rules and real examples.
Docker Sandboxes (sbx) Guide: Run Claude Code Safely in a microVM – This published update adds current operational context for How to write Claude Code Skills: official rules and real examples.
Adversarial Verification for Claude Agents: Practical Checklist – This published update adds current operational context for How to write Claude Code Skills: official rules and real examples.
Role-Based Model Routing for Claude Agent Teams (2026) – This published update adds current operational context for How to write Claude Code Skills: official rules and real examples.
Graph vs Loop Engineering: Adoption Checklist (2026) – This published update adds current operational context for How to write Claude Code Skills: official rules and real examples.
Claude Cowork Record a Skill: Plans, Steps, Privacy Limits – This published update adds current operational context for How to write Claude Code Skills: official rules and real examples.

Author

krona23

Over 20 years in the IT industry, serving as Division Head and CTO at multiple companies running large-scale web services in Japan. Experienced across Windows, iOS, Android, and web development. Currently focused on AI-native transformation. At DevGENT, sharing practical guides on AI code editors, automation tools, and LLMs in three languages.

DevGENT about →

📚 Read Next