eps1.2AI
Context Engineering - Part 2: Rules vs Skills
How to give your AI agent memory and abilities: what always applies becomes a Rule, what only applies to one task becomes a Skill.
Day to day, we need the agent to remember a few things from one session to the next. Facts like “this project uses pnpm, not npm” or “run the linter before finishing any task” have to be available all the time. There are also processes that are only used at specific moments, like “write a PRD” or “write release notes”, and that make no sense to load all the time. To cover these two needs, two important concepts show up when working with AI agents: Rules and Skills.
Before moving on, a quick reminder (the subject of part 1): the context window of the LLM (large language model, the language model behind tools like Claude, ChatGPT or Gemini) works as short-term memory. Everything in it is lost when you close the session or clear the context.
In this post, we’ll see what each one is, when to use one or the other, and how to combine them to keep the agent useful without overloading the context window.
Contents
- TL;DR
- Rules: long-term memory
- Skills: knowledge on demand
- Rules x Skills: deciding where each thing goes
- Tip: spread CLAUDE.md files across directories
- Conclusion
- References
TL;DR
- Rules: always loaded into the context. Use them for what applies to any task (stack, conventions, required commands).
- Skills: loaded on demand. Use them for specific workflows (writing a PRD, creating a component, code review).
- Quick test: if the instruction applies “even when nobody is thinking about it”, it’s a Rule. If it applies “only when I’m doing X”, it’s a Skill.
| Rules | Skills | |
|---|---|---|
| When it loads | Always | When triggered |
| Where it lives | Rules file (e.g. CLAUDE.md) | Its own folder (e.g. .claude/skills/<name>/) |
| Context cost | Constant | Only when used |
| Good for | Conventions, required commands | One-off workflows |
Rules: long-term memory
Rules are instructions injected into the system prompt (the base prompt the agent gets before every conversation). Because they’re always loaded, they work as long-term memory: they persist across sessions, across tasks, across different working days.
Each tool has its own file name for these rules:
- Claude Code:
CLAUDE.md - Cursor:
.cursor/rules - Windsurf:
.windsurf/rules - GitHub Copilot:
.github/copilot-instructions.md - Factory:
.factory/rules - Open standard adopted by several tools (Codex, Aider and others):
AGENTS.md - Gemini:
GEMINI.md
The job of Rules is to hold what’s true in your project: architecture patterns, naming conventions, commands required before pushing code, the team’s official tools. They’re instructions that must apply to any task, no matter what’s being done at the moment.
Ways to create Rules (they can be combined)
- From scratch: the team gets together, discusses what should become a rule and writes it together. This path takes longer, but it usually produces Rules that are closer to the project’s reality.
- Clone from GitHub: there are public repositories with ready-made Rules for many stacks. It’s a good starting point, as long as you read them carefully and remove everything that doesn’t apply to you. Rules that don’t match the project’s code end up as noise in the context window.
- Ask the LLM to generate them from the code: in Claude Code, the
/initcommand does exactly that. It scans the project and generates an initialCLAUDE.md. It works well on cohesive projects. On projects that changed stacks a lot over time, the LLM may reproduce contradictions from their own history, so human review is still important.
A practical suggestion: write the Rules first in the team’s language, discuss them with the people involved, refine them, and only then (if it makes sense) ask Claude to translate them into English and fill them in with examples. Keep an eye on the file size. Rules that are too long take up room in the context window that could be used for the problem you’re solving.
Beware of too many Rules
Picture this: you’re doing a front-end task and the agent loads a long Rule about SQL patterns along with it. Or the other way around, working on the database and getting React rules. In both cases, tokens are spent for nothing. Having Rules matters, but too many of them shrink the room available for what the task actually needs.
Structure of a Rule
Unlike Skills, Rules don’t require a fixed format. The agent reads the whole file as part of the system prompt, so what matters is clarity: short headings, objective lists and direct instructions.
A simple CLAUDE.md example for a Node.js project:
# Project: Orders API
REST API that manages the orders of an online store.
Stack: Node.js, Fastify and PostgreSQL.
## Code conventions
- Always use TypeScript, never plain JavaScript.
- File names in kebab-case (e.g. `order-service.ts`).
- Avoid the `any` type. When you need something flexible, prefer `unknown`.
## Before finishing a task
1. Run `pnpm lint` and fix whatever it flags.
2. Run `pnpm test` and make sure all tests pass.
3. Don't commit `.env` files.
## Available skills
- To create a new REST endpoint, load the `new-rest-endpoint` skill.
- To generate or update a README, load the `readme-generator` skill.
This example shows three common blocks in a Rule: the project’s context (what it is, what it’s for, what the stack is), the conventions that must always apply, and the commands required in specific situations. The last block applies the routing-to-Skills pattern, covered in more detail below: the Rule stays short and points to the right Skill when the knowledge is specific to a workflow.
Skills: knowledge on demand
Skills were popularized by Anthropic in Claude Code. The difference from Rules is straightforward: a Skill isn’t always loaded in the context window.
Each Skill lives in a specific folder called skills, with everything it needs to run: a SKILL.md file, template folders, reference docs and examples. When the agent starts a session, only the Skill’s header (the YAML at the top of SKILL.md, describing its name and purpose) is loaded. The full content only enters the context window when the Skill is actually triggered.
That difference changes the math significantly. You can have dozens of Skills available in a project without weighing on the context, because what’s always there is just a short description of each one. Trying the same with Rules would use up far more tokens.
Where to find ready-made Skills
There are two widely used marketplaces for downloading Skills made by the community:
https://www.skills.sh/https://skillsmp.com/
There you’ll find everything from generic Skills (generate a README, create images, front-end design) to more specific ones, like a Skill for creating PRDs (Product Requirements Documents).
In the repository that comes with this post, the prd-development Skill was installed as an example, in .agents/skills/prd-development/. Opening that folder, you can see the organized structure: a templates/ folder, a references/ folder and SKILL.md at the root.
Structure of a Skill
Every Skill needs a SKILL.md file with YAML frontmatter (a YAML header, delimited by three dashes at the top of the file). The required fields are name and description:
---
name: readme-generator
description: Creates project READMEs following the team's standard. Use when the user asks to generate, update or refine a README.
---
# README generator
## Instructions
1. Ask for the project's name and purpose.
2. Ask for the main stack.
3. Generate the README following the template in `templates/readme.md`.
## Example
See `examples/orders-api.md` for a finished README.
Claude Code’s built-in Skills
Claude Code comes with some native Skills, ready to use without installing anything:
- PowerPoint (pptx): create and edit slides, analyze presentation content.
- Excel (xlsx): create spreadsheets, analyze data and build reports with charts.
- Word (docx): create and edit documents, format text.
- PDF (pdf): generate formatted PDFs and reports.
How to install and use a Skill
To install one, just copy the Skill’s folder into .claude/skills/ (Claude Code) or .agents/skills/ (the open standard used by other agents) at the project root:
.claude/
skills/
prd-development/
SKILL.md
templates/
references/
To trigger a Skill in Claude Code, use / followed by its name:
/prd-development I want to create a PRD for a Google sign-in feature.
In Cursor, Windsurf or any other agent that supports Skills, just ask for it explicitly by name:
Create a PRD using the prd-development skill for the Google sign-in feature.
The Skill only enters the context window at that moment. Before that, only the name and description from its SKILL.md are available, so the agent knows it exists.
Rules x Skills: deciding where each thing goes
Skills don’t replace Rules. Rules are still the project’s non-negotiable instructions. Having Skills available changes how you write Rules, because it lets them stay leaner.
A few examples to make it stick:
- “Never commit .env files” (Rule)
- “After changing code, always run the linter and the tests” (Rule)
- “To write release notes, follow this format and this checklist” (Skill)
- “Code review script with a security, performance and testing checklist” (Skill)
A pattern that works well in practice is making Rules act almost as a router to Skills. Inside the project’s CLAUDE.md, for example:
- "When changing UI components, load the `ui-change` skill."
- "When creating services, load the `create-service` skill."
- "When creating specs, load the `create-spec` skill."
Tip: spread CLAUDE.md files across directories
Claude Code loads CLAUDE.md files from subdirectories on demand, only when it works with files in that directory. That lets you keep the root CLAUDE.md lean, with the project’s general context, and spread specific rules to where they actually apply:
CLAUDE.md ← overview, stack, required commands
app/services/CLAUDE.md ← service object patterns
app/workers/CLAUDE.md ← worker patterns and queue priority
spec/CLAUDE.md ← RSpec rules and test structure
Service rules take up no context while the agent is working in spec/, and vice versa. The same token-saving principle as Skills, applied to Rules. This behavior is documented in Claude Code’s official best practices.
Conclusion
Rules and Skills play complementary roles in the agent. Rules carry what’s always true in the project, what must apply to any task. Skills carry knowledge that only steps in when it’s needed, without taking up room in the context window in the meantime. Used together, they keep the context window lean and the agent focused on the problem at hand.
A practical suggestion: open your project’s CLAUDE.md or .cursor/rules and apply the test from this post. Does everything in that file need to be loaded all the time? Is there something there that would make more sense as a Skill?
In part 3, we’ll bring Rules, Skills and commands together into a full development workflow: Spec-Driven Development.