Agent Skills: Stop Stuffing Workflows Into Your Rules File

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:

1. 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.
2. Activation. When a task matches a skill’s description, the agent reads the full SKILL.md into context.
3. 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

A pattern that comes up constantly. Check:

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: When to use which

Skills and rules solve different problems:

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

Where 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.

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 this matters 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.

Sharing 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:

1. Audit your rules file. Anything task-specific is a skill candidate.
2. Start with one high-value skill. Pick the workflow your team repeats most often – test writing, PR review, service scaffolding.
3. Put it in the repo. Project-scoped skills require zero infrastructure. Commit the folder, and every team member’s agent picks it up automatically.
4. 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.
5. Promote to share. Once a skill proves itself in one project, move it to a shared repository or registry for broader use.

Trade-offs and limitations

Agent skills may have some limitations, as:

• 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