A single GitHub thread from TypeScript educator Matt Pocock put the .claude/skills pattern on the map, and developers have been copying the structure into their own repos ever since. The idea is deceptively simple: store reusable, scoped instructions as plain text files that Claude Code can pull in on demand, rather than jamming everything into one massive system prompt.
Why the skills pattern matters
Claude Code already reads a CLAUDE.md file at the root of a project to understand its context. The skills extension takes that one step further. Instead of one monolithic instruction file, a .claude/skills/ directory holds individual markdown files, each describing a specific repeatable task. A developer invoking use skill: blog-humanizer gets a focused, deterministic set of instructions rather than hoping the model extracts the right guidance from hundreds of lines of general context.
The practical effect is closer to a documented SOP than a prompt hack. Skills are version-controlled, readable by humans, and composable. A new contractor can open the directory and understand exactly how the team uses the tool, without sitting through an onboarding call.
What real skill files look like
The Tuscan Agency stack, which runs on Next.js, Vercel, Supabase, and Make.com, maintains a shared skills registry at ~/claude/shared/skills/ with individual files for recurring content and automation tasks. Three examples illustrate how narrow and specific these files get in practice.
- article-uplift. An SEO uplift plan scoped specifically to tuscanagency.com. Rather than giving Claude generic SEO advice to recite, the file defines the exact signals to check, the output format expected, and the site's indexing context. The result is a repeatable audit, not a one-off conversation.
- blog-humanizer. A post-generation pass that strips AI-slop patterns from drafts before they publish. The skill knows the agency's forbidden phrases, voice rules, and editorial guardrails. Running it is a single invocation, not a manual proofreading session.
- find-image. A universal image finder wired into the blog drafting pipeline. The skill routes lookup by entity type, falls through to a Picsum fallback when external calls are blocked by firewall rules, and tracks used images in a dedup file so the same photo does not appear twice across posts.
Each file is a few dozen lines of plain markdown. There is no proprietary format, no SDK dependency, and no runtime to maintain.
Skills versus CLAUDE.md: what goes where
A CLAUDE.md file is for persistent project context: stack, conventions, credentials paths, team norms. Skills are for discrete, invocable tasks. The distinction matters because context window size is finite and attention is not evenly distributed across thousands of tokens. Loading a targeted skill at the moment it is needed is more reliable than burying the same instructions in a 2,000-line root file.
The Pocock thread that sparked the Hacker News discussion framed it as the difference between a generalist assistant and a specialist: the same model, sharpened by what it is handed. Several developers in the thread noted that skills also make it easier to test and iterate on prompting strategies in isolation, since each file has a clear scope and a clear owner.
Cross-client reuse and the graduation model
One pattern that emerges at the agency level is a two-tier registry: project-local skills that are specific to one client or repo, and shared skills that any project can reference. When a local skill proves useful across more than one engagement, it gets promoted to the shared library, a process some teams call graduation.
This mirrors how good software libraries grow. A utility written for one codebase gets extracted and generalized once the second use case appears. The same logic applies to AI instruction files. A blog-humanizer written for one agency site is almost immediately useful for the next one. A find-image skill built around one CMS's routing logic can be adapted in an afternoon.
The graduation model also enforces a useful discipline: skills in the shared registry have to be general enough to work without project-specific assumptions baked in, which pushes teams toward cleaner, more reusable instruction design.
Getting started: three files worth writing first
For any agency or development team that ships content or runs automation, three skills tend to have the highest immediate return.
- A review skill. Define your editorial or code review rules once, invoke them on every draft or PR. This is the lowest-effort, highest-consistency win available.
- A formatting or cleanup skill. Whether that is stripping AI patterns from prose or normalizing component structure in a codebase, a cleanup pass you can invoke in one line saves meaningful time across a month of output.
- A context-injection skill. For recurring client work, a skill that loads the relevant background (stack, brand voice, constraints) without repeating it in every conversation keeps sessions focused and reduces mistakes from missing context.
The .claude/skills pattern costs nothing to adopt and requires no tooling beyond a text editor and a Git repo. The teams reporting the most traction are the ones who treat skill files as living documentation: written once, updated when the process changes, and referenced consistently rather than re-explained from scratch each session.
