AK DevCraft

Posted on Apr 13

“Skills” in Claude Aren’t About Prompts — They’re About Context Design

#claude #ai #machinelearning #tutorial

Introduction

When I first came across “Skills” in Claude Code, it looked like just another abstraction over prompts. I kept repeating the same instructions to Claude — code review rules, API patterns, formatting — across multiple sessions.

But after spending some time with it, the interesting part wasn’t what skills are, but what problem it's trying to solve.

Demo

In the demo above, a code-review skill is defined. When I ask Claude to “review modified files”, it automatically matches the request to the skill and executes it — without needing explicit invocation.

Skill GitHub Repo - .claude/skills/code-review

Context Window Challenge

One of the biggest challenges with LLM usage in real workflows is:

Context keeps growing
Instructions get repeated
Conversations lose focus over time

Most people try to fix this by writing better prompts or adding more context. However, that approach doesn’t scale. As more context/prompt is provided, more of the context window will be consumed.

Definition

First, let’s go over the official definition of Skills.

Skills are folders of instructions and resources that Claude Code can discover and use to handle tasks more accurately. Each skill lives in a SKILL.md file with at least a name and description in its frontmatter.

A little more about Skills

Skills can be created in different locations based on the user's or the project's settings. At the end of the day, skill is created at .claude/skills/code-review/SKILL.md. Only difference is where the .claude directory is created.

User's personal skill: Create .claude directory in your home directory, e.g., ~/.claude/skills/code-review/SKILL.md
Project-specific skill: create .claude directory in the root of the project, e.g., project/.claude/skills/code-review/SKILL.md

Apart from the user and project, skills can be stored at the Enterprise and plugin levels. And if you have the same skill with the same description in all locations (not a desire approach, but hypothetically), then the skill is applied based on the following precedence order:

1. Enterprise — managed settings, highest priority. All users in your organization.
2. Personal — your home directory (~/.claude/skills/<skill-name>/SKILL.md). All your projects.
3. Project — the .claude/skills/<skill-name>/SKILL.md directory inside a repository. A particular project only.
4. Plugins — installed plugins <plugin>/skills/<skill-name>/SKILL.md, lowest priority. Where the plugin is enabled.

Skills Flow Diagram

User Request
     ↓
[Skill Description Match]
     ↓
[Skill Loaded]
     ↓
[Context Applied]
     ↓
Claude Response

What Skills Actually Change

At a surface level, skills look simple:

Reusable instructions that Claude can apply

But the real shift is deeper:

Skills separate “when to use context” from “what the context is.”

That’s a big deal, instead of loading everything up front or manually injecting instructions. You define a trigger (description) and a payload (instructions).

Skills work best for specialized knowledge that applies to specific tasks:

Code review standards
Commit message formats
Debugging checklists for a project

Claude handles the rest.

When you find yourself repeating again and again, then most likely you need a skill.

The Most Important Part: Description

If there’s one thing that matters more than anything else:

Your Skills description is the entry point to your system

This is effectively a semantic matcher and routing mechanism. In practice, this means:

Two skills with similar descriptions will conflict
A vague description won’t trigger
An overly broad one will trigger at the wrong time

👉 You’re not just writing instructions — you’re designing intent matching

Skills as a Context Control Mechanism

What changed my thinking was this:

Skills are not a convenience feature
They are a context management strategy

Because they are lazy-loaded only when needed, scopes are not always present, and multiple composable components can activate together.

This directly impacts:

Response quality
Token usage
System predictability

Designing Skills (What Actually Matters)

Let's see how we can design the Skills to harvest the best out of it.

1. Skill Schema (Only Important Ones)

The skills open standard supports many fields in the SKILL.md frontmatter. However, only two fields are required:

name (required) — Identifies your skill. Use lowercase letters, numbers, and hyphens only. Maximum 64 characters. Should match your directory name.
description (required) — Tells Claude when to use the skill. Maximum 1,024 characters. This is the most important field because Claude uses it for matching.
allowed-tools (optional) — Restricts which tools Claude can use when the skill is active.
model (optional) — Specifies which Claude model to use for the skill.

2. Keep the core small

Don’t treat a skill like a knowledge dump. Keep instructions focused and push details to supporting files.
Think of this as an entry point, not an encyclopedia.

3. Use constraints intentionally

Parameters like tool restrictions aren’t just configuration. They’re guardrails.

Examples:

Read-only analysis skills
Restricted execution environments
Safer automation workflows

4. Structure for scale, not just usage

The real challenge isn’t creating a skill — it’s managing many of them.

Things that start to matter:

Naming clarity
Description uniqueness
Conflict avoidance
Ownership (personal vs project vs org)

👉 This becomes closer to system design than prompt design

Skills vs Everything Else

A common mistake is trying to use skills for everything. But each feature solves a different problem. Claude Code has several ways to customize behavior. Skills are unique because they're automatic and task-specific. Here's a quick comparison:

CLAUDE.md file is loaded into every conversation. If you want Claude to always use a certain file formatting, that goes in CLAUDE.md.
Skills load on demand when they match your request. Claude only loads the name and description initially, so they don't fill up your entire context window. Your code review checklist doesn't need to be in context when you're debugging — it loads when you actually ask for a review.
Subagents run in isolated execution contexts — use them for delegated work. Skills add knowledge to your current conversation.
Hooks are event-driven (fire on some event like file saves). Skills are request-driven (activate based on what you're asking Claude to act)
MCP servers provide external tools and integrations — a different category entirely from skills
Slash commands require you to explicitly type them. Skills don't. Claude applies them when it recognizes the situation.

How does this shift thinking

Without Skills, we were thinking in terms of:

“How do I write better prompts?”

Now it’s more like:

“How do I design context that shows up at the right time?”

That’s a different level of control.

Practical Takeaways

If you’re starting out:

Don’t create many skills — create one good one
Spend more time on the description than the instructions
Keep skills narrow and intentional
Treat conflicts as a design problem, not a bug

And most importantly:

👉 If context is growing uncontrollably, skills are probably the penetrating layer.

Conclusion

👉 “Skills are not a feature. They’re a shift in how you structure AI systems.”

But the idea behind them is bigger:

👉 Moving from prompt writing → to context system design

And that’s where LLM usage starts becoming predictable, not just powerful.

If you have reached here, then I have made a satisfactory effort to keep you reading. Please be kind enough to leave any comments or share any corrections.

DEV Community