Introduction to Agent Skills

Teach Claude Once, Use It Everywhere: A Practical Guide to Building, Configuring, and Sharing Skills in Claude Code

Photo by Igor Omilaev on Unsplash

If you’ve ever found yourself re-explaining the same workflow, formatting rule, or company convention to Claude in every new session, this article is for you. Agent Skills solve exactly that problem they let you package reusable instructions into a simple markdown file that Claude automatically discovers and applies at the right moment, without you having to repeat yourself.

Enjoyed this article? Follow me and reach out : I share practical breakdowns like this one regularly. Connect with me on LinkedIn or drop me an email if you’d like to discuss AI tooling, Claude Code, or building better developer workflows together.

What Are Agent Skills, Really?

Think of a Skill as an onboarding document you’d hand to a new team member except instead of a person, it’s Claude reading it. A Skill is a folder containing at minimum a SKILL.md file, written in plain markdown with a small YAML header on top. That header carries two required pieces of metadata: a name and a description. Everything else in the file is instructions, examples, and guidelines written in natural language.

What makes Skills powerful isn’t the format it’s when they get used. Claude doesn’t wait for you to invoke a Skill manually. Instead, at startup, Claude preloads just the name and description of every installed Skill into its system prompt. When your request matches what a Skill is meant for, Claude reads the full SKILL.md file into context and follows it. If your task doesn't need that Skill, its full content never loads at all.

This pattern is called progressive disclosure, and it’s the core design principle behind the whole system. Rather than dumping every possible instruction into Claude’s context window upfront, Skills load in layers:

1. Metadata (name + description) always present, tiny footprint
2. Instructions (the body of SKILL.md) loaded only when the Skill is triggered
3. Bundled resources (scripts, templates, reference docs) loaded only when Claude decides it actually needs them

Because of this staged loading, a Skill’s bundled content can be effectively unbounded in size. You could build a Skill with dozens of reference files and helper scripts, and Claude would still only pull in the specific pieces relevant to the task at hand keeping your context window lean no matter how much expertise the Skill contains.

How Skills Differ from CLAUDE.md, Hooks, and Subagents

If you’ve used Claude Code for a while, you’re probably already familiar with a few other customization tools, and it’s worth being clear about where each one fits:

• CLAUDE.md gives Claude persistent, always-loaded context about your project conventions, architecture notes, things it should always know.
• Hooks let you intercept and control tool execution programmatically, regardless of what the user asked.
• Subagents are separate, filesystem-based agents with their own configuration, useful for delegating whole subtasks.
• Skills sit in between: they’re conditionally loaded expertise, triggered automatically by relevance rather than always-on or manually invoked.

Skills are the right tool when you have a specific, repeatable task filling out a particular kind of PDF, following your team’s PR review checklist, generating reports in a house style that doesn’t need to be top-of-mind for every single interaction, but should surface reliably the moment it’s relevant.

Building Your First Skill

Creating a Skill starts with a directory and a single file:

.claude/skills/
└── pdf-processing/
    └── SKILL.md

The SKILL.md file begins with YAML frontmatter:

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents.
---

Below the frontmatter, you write the actual instructions in markdown the steps Claude should follow, examples of correct usage, and any edge cases worth flagging. The description field deserves special attention: it’s the only thing Claude sees before deciding whether to load your Skill, so it needs to be specific and packed with the keywords a real user request would contain. A vague description means your Skill might simply never trigger.

For genuinely complex domains, you’re not limited to a single file. A Skill directory can include supporting materials a FORMS.md for edge cases, helper scripts, reference templates and Claude will decide on its own which of these to read based on what the task actually requires. This is progressive disclosure in action: Claude might read your top-level instructions and stop there, or it might dig into a bundled script if the task calls for it.

Where Skills Live and Who Can See Them

Claude Code loads Skills from a few different filesystem locations, and where you put a Skill determines who benefits from it:

• Project Skills (.claude/skills/) committed to your repository and shared with your entire team through version control. Anyone who clones the repo and works with Claude Code gets these automatically.
• User Skills (~/.claude/skills/) personal, available to you across every project you work on, but not shared with teammates.
• Plugin Skills — bundled inside installed Claude Code plugins, letting you distribute Skills as part of a larger packaged toolset.

This layered system means you can start by prototyping a Skill privately in your user directory, then promote it to a project Skill once it’s proven useful, and eventually package it into a plugin for wider distribution all without changing the underlying SKILL.md format.

Configuring Tool Access

Skills can be scoped down to specific tools using the allowed-tools frontmatter field, which restricts what a given Skill is permitted to do when it's active useful if a Skill only needs to read files, for example, and shouldn't be running arbitrary shell commands. It's worth knowing that this field is specific to the Claude Code CLI; if you're working through the Agent SDK instead, tool access is controlled centrally through your SDK configuration rather than per-Skill.

It’s also worth understanding a subtlety here: enabling or disabling which Skills are visible to Claude acts as a context filter, not a security sandbox. An unlisted Skill won’t appear in Claude’s available options and won’t be invoked but its files still exist on disk and remain reachable through general-purpose tools like Read or Bash. If you’re managing sensitive Skills, plan your access controls accordingly rather than relying on visibility alone.

Sharing and Distributing Skills

Once a Skill earns its place in your workflow, sharing it is straightforward:

• Commit it to your repository as a project Skill so your whole team picks it up automatically through normal git workflows.
• Package it as a plugin to distribute Skills more broadly, including to people outside your immediate team or organization.
• Deploy it organization-wide through enterprise managed settings, giving every developer in a company access to a standardized set of Skills without manual setup.

Anthropic also maintains a public repository of example and pre-built Skills covering common document tasks like PowerPoint, Excel, Word, and PDF handling which you can install directly as a Claude Code plugin marketplace and use as reference material for authoring your own.

A Word on Trust

Because Skills can instruct Claude to invoke tools running bash commands, executing code, reading and writing files they carry real capability, not just conversational instructions. Treat installing a Skill the way you’d treat installing any other piece of software: only pull Skills from sources you trust, and if you’re evaluating one from an unfamiliar source, read through its bundled files first, paying attention to any scripts, dependencies, or instructions that reach out to external network resources.

Getting Started

The fastest path in is small: pick one repetitive task you find yourself explaining to Claude over and over, write a SKILL.md for it with a sharp, keyword-rich description, and drop it in .claude/skills/. Watch how reliably it triggers, refine the description if it doesn't, and only then think about scripts, bundled resources, or team-wide distribution. Skills reward iteration the best ones tend to start narrow and grow only as real usage proves they need to.

📬 Let’s stay connected. If this was useful, follow me for more deep dives into Claude Code, agentic workflows, and practical AI engineering and feel free to reach out directly via LinkedIn or email with questions, feedback, or ideas for what to cover next.

MUSTAPHA AIT IGUNAOUN