This post assumes familiarity with AI coding agents (Cursor, Claude Code, Windsurf, etc.), basic prompt engineering concepts, and rules files (Cursor’s .cursor/rules/ or Claude Code’s CLAUDE.md).
If you’re new to agent-assisted development, start with your tool’s getting-started docs first. If you haven’t used rules before, read the Cursor rules docs or Claude Code’s memory docs before continuing. Understanding rules is essential context for why skills exist.
The problem: Rules that become operating manuals
Every team’s rules file follows the same trajectory. It starts with a few sensible guardrails:
- “Ask before destructive actions”
- “Don’t add new dependencies without approval”
Then someone adds a checklist for billing code. Another person adds migration procedures. A third contributes API design templates. Six months later, your “rules” section is a 5,000-token operating manual that loads on every single agent interaction.
What goes wrong:
- The base prompt gets bloated. Every conversation pays the token cost of every workflow, even ones that never fire.
- Important policies get buried. “Never delete production databases” sits next to “For billing code, check idempotency keys”; the agent treats them with equal weight.
- Specialized workflows can’t be reused. That carefully written migration review checklist is locked inside one project’s rules file.
- Maintenance is painful. Changing a single procedure means editing a giant block of text and hoping nothing else breaks.
- Debugging gets harder. When the agent misbehaves, tracing the cause through a wall of interleaved concerns is tedious.
Rules are meant to be guardrails: short, always-on policies that shape behavior across all tasks. When you overload them with task-specific procedures, you’re using the wrong tool for the job.
Read more: React Best Practices: Separation of Concerns & Code Optimization
What are agent skills?
A skill is a self-contained folder that packages a specific workflow or expertise area:
my-skill/
├── SKILL.md # Required: instructions + metadata
├── scripts/ # Optional: executable code
├── references/ # Optional: documentation
└── assets/ # Optional: templates, resourcesCode language: PHP (php)The SKILL.md file is the entry point. Its frontmatter contains a name and description; the body contains the actual instructions.
Here’s a real example – a skill that applies Dependency Inversion to a module:
---
name: dependency-inversion
description:
Refactor a module to follow the Dependency Inversion Principle by extracting
interfaces, inverting concrete dependencies, and wiring via injection. Use
when the user asks to decouple modules, invert dependencies, extract an
interface, apply SOLID principles, or improve testability of tightly coupled
code.
---
Decouples modules by replacing direct imports of concrete implementations with
injected abstractions, improving testability and swappability.
## Dependency Inversion Progress:
- [ ] Step 1: Identify concrete dependencies in the target module
- [ ] Step 2: Extract an interface (port) for each dependency
- [ ] Step 3: Update the module to depend on the interface, not the concrete
- [ ] Step 4: Create an adapter implementing the interface for the original concrete
- [ ] Step 5: Wire the adapter via constructor or factory injection
Code language: CSS (css)Skills use progressive disclosure to manage context in three stages:
- Discovery. At startup, agents load only the name and description of each available skill. A few tokens per skill and enough to know when one applies.
- Activation. When a task matches a skill’s description, the agent reads the full SKILL.md into context.
- Execution. The agent follows the instructions, loading referenced files or running bundled scripts as needed.
A project can have dozens of skills installed. The agent only pays the token cost for the ones it uses in a given conversation.
Before and after
Here’s a pattern that comes up constantly:
Before, everything lives in rules:
- “Always ask before risky actions”
- “Don’t add new dependencies without approval”
- “For billing code, inspect idempotency”
- “For migrations, check rollback paths”
All four statements load on every prompt, every time. The last two are irrelevant unless the developer is actively working on billing or migrations.
After – keep rules short, move expertise into skills:
Rules (always loaded):
- Ask before risky actions
- Don’t add new dependencies without approval
Skills (loaded on demand):
- billing-review – idempotency checks, payment edge cases
- migration-review – rollback paths, data integrity verification
The rules stay focused on universal policies. The specialized knowledge activates only when it’s needed.
Real Numbers
One real-world React project restructured from rules-only to rules-plus-skills and measured the token impact on prompt startup:
| Configuration | Component | Tokens |
| Before | overview.md (always-on rule) | 1,636 |
| patterns.md (always-on rule) | 3,137 | |
| structure.md (always-on rule) | 2,348 | |
| Total | 7,121 | |
| After | project.md (always-on rule) | 1,911 |
| feature-flags (skill frontmatter) | 71 | |
| feature-screen-creator (skill frontmatter) | 61 | |
| react-component (skill frontmatter) | 59 | |
| redux-state-management (skill frontmatter) | 67 | |
| unit-tests (skill frontmatter) | 44 | |
| Total | 2,213 |
That’s a reduction of 4,908 tokens at startup – 69% less context consumed before the agent even begins working. The full skill instructions still exist and still get used. They don’t load until the agent needs them.
Skills vs rules: what is the difference?
Skills and rules solve different problems. Rules are always-on guardrails: broad policies that shape the agent’s behavior across every task, no matter what you’re working on. Skills are task-focused packages of procedures and examples that the agent loads only when a request matches them.
| Dimension | Rules | Skills |
| Primary purpose | Shape behavior | Teach a workflow |
| Scope | Broad and cross-task | Narrower and task-focused |
| When active | Always on | Activated when relevant |
| Typical content | Policies, priorities, tone, safety | Procedures, examples, references, templates |
| Best use | Guardrails and consistency | Reusable specialized know-how |
Use rules for universal policies that should govern every interaction.
- “Ask before destructive actions.”
- “Use conventional commits.”
- “Prefer composition over inheritance.”
Use skills for task-specific workflows that only matter in certain contexts.
- “How to write a Playwright e2e test.”
- “How to scaffold a new API endpoint.”
- “How to review billing code for payment edge cases.”
Read more: Machine Learning Explained: What It Is, How It Works, and Why It Matters for Business
How do agent skills fit alongside MCPs and subagents?
Skills aren’t the only way to extend agent capabilities. Two other patterns, MCP servers and subagents, solve different problems: skills teach the agent how to do the work, MCPs give it access to external systems, and subagents delegate subtasks to separate worker instances that run independently.
MCP (Model Context Protocol)
MCP gives agents a standardized way to connect to external tools, data sources, and applications. It’s a USB port for agents to access live systems.
| Dimension | Skills | MCPs |
| Main role | Teach the agent how to work | Let the agent access systems |
| Contains | Instructions, workflows, expertise | Reusable connectivity |
| Context usage | Only when skill is loaded | Only when tool is used |
| Example | “How to review a PR” | “GitHub MCP server with PR APIs” |
Skills and MCPs complement each other. A skill teaches the agent how to use the tools an MCP provides. The skill says “here’s the workflow for reviewing a PR.” The MCP provides the GitHub API access to fetch diffs and post comments.
Worth noting: MCP tool responses consume token limits. Large payloads from MCP calls fill the context window fast, which makes the lean-context argument for skills even stronger.
Subagents
Subagents are specialized worker instances that handle subtasks independently, often in parallel.
| Dimension | Skills | Subagents |
| Main role | Provide expertise or workflow | Provide delegation and parallelism |
| Form | Knowledge/instruction package | Additional worker instance |
| Solves | “How should this task be done?” | “Who should do this subtask?” |
| Example | “Security review checklist” | “Spawn a security-review worker and a test-fix worker” |
Skills tell an agent what to do. Subagents handle who does it. A subagent might load a skill to learn how to perform its delegated task.
Choosing the right tool
| Mechanism | When to use it | Example |
| Rules | Universal guardrails that must always be active | “Never delete production databases.” |
| Skills | Reusable task workflows, coding standards, project conventions | “How to write a Playwright e2e test.” |
| MCPs | Live connections to external APIs, databases, or closed systems | “Query JIRA for the latest bug reports.” |
| Subagents | Heavy lifting and parallel tasks to save the main agent’s context window | “Scan 100 log files for a specific memory leak.” |
These mechanisms layer together. Rules for safety guardrails, skills for team workflows, MCPs for tool access, subagents for parallelizable work.
Why do agent skills matter for teams?
Token savings matter. The organizational payoff matters more. Skills turn team knowledge into portable, versioned artifacts that any agent can pick up and execute.
When a senior engineer writes a security-review skill, every developer on the team gets the same review checklist – new hire or veteran. The knowledge doesn’t live in someone’s head or a Confluence page that nobody reads. It lives where the agent uses it.
How do you share skills across teams?
Skills are folders. Distribute them with tools developers already have. Agent runtimes that support skills recognize multiple installation scopes:
| Scope | Location | Who benefits | Example |
| Project | .cursor/skills/ or .claude/skills/ in the repo | Everyone on the project | migration-review for a specific database schema |
| User | ~/.cursor/skills/ or ~/.claude/skills/ | You, across all projects | technical-blog-writing for your personal workflow |
| Team / Org | Shared via Git or a registry | Everyone in the organization | api-design encoding your company’s API standards |
Project-scoped skills get committed to the repo and travel with it. User-scoped skills are personal – your preferred code style, your writing workflow.
For team distribution, the simplest approach is a shared Git repo. Point a directory in your project at it via submodule, and updates come in when you pull:
git submodule add https://github.com/your-org/shared-skills .claude/skills/shared
A practical starting point
Where to begin:
- Audit your rules file. Anything task-specific is a skill candidate.
- Start with one high-value skill. Pick the workflow your team repeats most often – test writing, PR review, service scaffolding.
- Put it in the repo. Project-scoped skills require zero infrastructure. Commit the folder, and every team member’s agent picks it up automatically.
- Iterate based on usage. Watch how the agent activates the skill. Refine the description if it triggers too often or not enough. Tighten the instructions when the agent misses steps.
- Promote to share. Once a skill proves itself in one project, move it to a shared repository or registry for broader use.
What are the limitations of agent skills?
Agent skills come with trade-offs. A skill only activates when its description matches how developers actually phrase their requests, and like documentation it drifts out of date. Runtime support is still uneven, and on a small project the organizational overhead can outweigh the token savings.
- Discovery depends on description quality. If a skill’s description doesn’t match how developers phrase their requests, the agent won’t activate it. Writing good trigger descriptions takes iteration.
- Skills are another thing to maintain. They drift out of date like documentation does. A stale skill that teaches the wrong workflow is worse than no skill at all.
- Not every agent runtime supports them yet. Skills as a pattern are gaining traction but aren’t universally standardized. Check your tool’s docs for current support.
- Overhead for small projects. If your rules file is 500 tokens and covers everything you need, extracting skills adds organizational complexity without meaningful token savings.
Conclusion
If your rules file is starting to feel messy, you already know. You’ve been scrolling past sections thinking “this doesn’t belong here.” Trust that instinct. Pull it out into a skill folder. Give it a name and description. See what happens.
Further Reading
- Agent Skills Specs – the spec itself
- The Complete Guide to Building Skills for Claude (PDF) – Anthropic’s comprehensive guide
- Claude Code skills documentation – Claude Code-specific implementation details
- Cursor skills documentation – IDE-specific implementation details
- Skills.sh – browse and discover community skills
