Agent Skill vs Rules: Policy, Workflow, and Reuse

Rules define the operating environment for an agent. An agent skill defines a reusable workflow for a specific job.

Rules say what should stay true across many tasks: coding standards, safety boundaries, project conventions, and team preferences. Skills say how to do a repeatable piece of work: investigate a failing CI job, migrate one component API, review a pull request for security risk, or turn support tickets into release notes.

If you are still defining the broader term, start with What Is an Agent Skill?. This article is about the boundary that matters once your repo has both persistent instructions and reusable task procedures.

Cursor's rules documentation describes rules as persistent instructions that can live at user, project, team, file-pattern, or AGENTS.md levels. VS Code's custom instructions documentation uses similar language for GitHub Copilot: always-on instructions belong in files like .github/copilot-instructions.md or AGENTS.md, while file-based instructions apply to specific paths. OpenAI's Codex docs say Codex reads AGENTS.md before work begins so global and project-specific expectations are available from the start.

That makes rules the right home for policies and context that should shape almost every agent session.

Good rule material includes:

• coding standards that apply across a repo
• safety constraints
• file ownership boundaries
• commands that must or must not be used
• style conventions
• global review expectations
• setup and verification commands that every change should respect

Example rules:

Never overwrite user changes. Re-read a file immediately before editing it.
Use npm commands for dependency updates instead of editing lockfiles by hand.
API routes must validate input with Zod before touching application logic.
Run npm test before final handoff when code behavior changes.

Those rules should apply whether the agent is fixing a typo, editing a React component, reviewing a route handler, or updating docs. They are not a complete workflow; they are the floor every workflow stands on.

OpenAI's Codex skills documentation describes a skill as a directory with a required SKILL.md plus optional scripts/, references/, and assets/. Anthropic's engineering writeup on Agent Skills explains the same progressive-disclosure model: the agent starts with skill metadata, loads the full SKILL.md when relevant, and can then read deeper references only as needed. Cursor's Agent Skills docs, GitHub's Copilot skills docs, and VS Code's Agent Skills docs all use the same basic idea: skills package specialized workflows that can include instructions, examples, scripts, and resources.

Skills are useful when the agent should enter a named procedure with a beginning, middle, end, and evidence trail.

Good skill material includes:

• one named workflow
• task-specific sources
• examples and templates
• step order
• quality checklist
• completion evidence
• stop and escalation rules
• scripts for deterministic checks

Example skill:

Use this skill to review a draft SDK tutorial before publication. Verify setup,
API version, command safety, copy-paste path, expected output, troubleshooting,
and links. Return blocking issues first with exact section references.

That is not a global rule. It is a repeatable editorial workflow.

Dimension	Rules	Agent skill
Scope	User, team, repo, AGENTS.md, or file pattern	Specific repeatable job
Purpose	Set constraints and context	Guide execution from trigger to evidence
Loaded when	Persistent, inherited, or path-scoped	Invoked manually or selected when relevant
Best owner	Repo owner, platform team, team lead	Workflow owner or domain expert
Best content	Standards, boundaries, preferences, canonical commands	Procedure, examples, references, scripts, output format
Change risk	Can affect many tasks	Usually affects one workflow
Failure mode	Context bloat or ignored guidance	Wrong trigger, stale procedure, unsafe script
Evidence	Compliance with constraints	Completed output plus verification

GitHub states the distinction directly in its Copilot skills docs: custom instructions are for simple guidance relevant to almost every task, while skills are for detailed instructions Copilot should access only when relevant. That is the cleanest practical test.

Different tools use different names, but the boundary is stable.

In Cursor, .cursor/rules/*.mdc, team rules, user rules, and AGENTS.md carry standing guidance. .cursor/skills/ or .agents/skills/ carries reusable task workflows. Cursor also documents a /migrate-to-skills helper that converts some dynamic rules and slash commands into skills, which is a strong signal that not every long rule belongs in the rule layer.

In GitHub Copilot and VS Code, .github/copilot-instructions.md, .github/instructions/*.instructions.md, organization instructions, and AGENTS.md are the instruction layer. Skills can live in locations such as .github/skills, .claude/skills, or .agents/skills, depending on which client and portability target you care about. The public awesome-copilot repository shows the ecosystem splitting into instructions, agents, skills, hooks, and workflows rather than treating one Markdown file as the whole customization surface.

In Codex, AGENTS.md is the project instruction file, while Codex skills are separate packages that can be explicitly invoked or selected when the task matches the skill description. In Claude, custom skills follow the SKILL.md package pattern and can bundle references or scripts. The names vary, but the useful design remains the same: keep permanent constraints in rules, and put repeated jobs in skills.

Rules for a technical enablement repo might say:

• use the company's terminology glossary
• keep tutorials under 20 minutes
• cite source files for API behavior
• do not publish commands that expose secrets
• preserve existing user edits

A write-migration-tutorial skill would go further:

• identify source and target versions
• list breaking changes
• create before/after code samples
• add verification commands
• include rollback notes
• run link checks
• produce a review checklist

The rule layer keeps the environment consistent. The skill layer makes the job repeatable.

This matters because the same repo might need several workflows that share the same rules. A docs review skill, migration tutorial skill, release-note skill, and SDK example QA skill should all obey terminology, secret-handling, and source-citation rules. They should not all be pasted into one giant AGENTS.md file.

For a deeper authoring pattern, How to Write an Agent Skill That Actually Works covers trigger design, source order, stop rules, and verification.

A Cursor project rule can say:

When editing API routes, validate request input with Zod.
Prefer existing route helpers from `src/server/http.ts`.
Do not change auth behavior without reading `docs/auth.md`.

Those rules are useful in any API-route task. A security-route-review skill should be more procedural:

Use when reviewing changed API routes for security risk.

1. Read the diff and the nearest AGENTS.md or Cursor rules.
2. Identify new trust boundaries, request inputs, and side effects.
3. Check authentication, authorization, validation, rate limits, logging, and secret exposure.
4. Return findings first, ordered by severity, with file paths and evidence.
5. Stop if production credentials or generated vendor files are involved.

The rule says what must stay true. The skill says how to perform a review another engineer can inspect.

The AGENTS.md format is useful because it gives coding agents a predictable place for setup commands, code style, tests, and project conventions. A good AGENTS.md for a monorepo might say:

Use pnpm.
Run pnpm test --filter <package> for focused package tests.
Never edit generated GraphQL types directly.
Prefer nested package docs over root-level assumptions.

A release-note-from-diff skill should not live entirely in that file. It can define a narrower job:

• inspect merged PR titles and user-facing diffs
• ignore internal refactors unless they change behavior
• group changes into Added, Changed, Fixed, and Migration Notes
• link customer-facing docs when they exist
• ask for product-owner review if billing, auth, or data retention changed

The release skill benefits from the repo rules, but it should be versioned and tested as its own workflow. If the release process changes, you can update that skill without changing every agent session in the repository.

Put something in rules when:

• it should apply across many tasks
• violating it is unacceptable regardless of workflow
• it is tied to a repo, team, or environment
• it is short enough to remain always relevant
• it should be enforced even when no skill is active
• it explains a durable convention better than a one-off process

Put something in a skill when:

• it belongs to one repeatable task
• it needs examples or references
• it has a defined output shape
• it has workflow-specific stop rules
• it should be measured as a workflow outcome
• it can benefit from scripts, templates, fixtures, or sample reports

If you are deciding between a skill and a plain prompt, Agent Skill vs Instructions covers that smaller boundary. A one-off instruction can stay in chat. A repeated, evidence-producing workflow deserves a skill.

Teams often start by adding every useful instruction to rules. That works briefly, then the rule file becomes overloaded. The agent has to carry unrelated workflows into every task.

The symptom is easy to spot: the rule file contains sections like "How to write launch notes," "How to triage support tickets," "How to review Terraform," and "How to prepare a demo script." Those are skills, not global rules.

Another symptom is that the rules become so broad that the agent can see them but still fail to apply them. A Cursor forum thread about rules being skipped included the useful diagnosis that rules in context do not guarantee perfect adherence, especially when irrelevant rules compete with relevant ones. A Reddit discussion about .mdc rules versus AGENTS.md reached a similar practical point: use tool-native rules and skills where they help, but keep a clear source of truth instead of spreading advanced prompts across random docs.

That is not an argument against rules. It is an argument for making rules short, durable, and easy to verify.

When a rules file gets too broad:

1. Keep global constraints in rules.
2. Move named procedures into separate skills.
3. Put long examples in references/ instead of the main rule file.
4. Turn deterministic checks into scripts when exact execution matters.
5. Add completion evidence to each skill.
6. Remove duplicated workflow steps from the rule file.
7. Test important skills with explicit invocation before trusting automatic selection.

This makes the agent environment easier to reason about. It also makes each workflow easier to test and improve.

Rules have the lowest friction. They are already present when the agent starts, so they are good for constraints you never want to remember manually. The tradeoff is context pressure. A 3,000-word rule file that covers every team habit can make every task heavier while still not proving the agent completed the right workflow.

Skills have better focus. They can contain deeper procedure, examples, and scripts without loading all of that material into every task. The tradeoff is invocation. Automatic skill selection depends on a clear name and description, and a Cursor community thread about using Agent Skills shows why manual invocation can be more reliable for critical workflows. If a workflow must run, make it easy to call directly with a slash command or explicit skill mention.

Skills also create a maintenance surface. A stale rule is annoying; a stale skill can confidently run the wrong release, migration, or compliance procedure. Keep skills close to canonical docs, link to source files instead of copying long policy text, and use skill testing before publishing workflows other people will rely on.

Finally, skills can include scripts. That is a strength when the script performs a repeatable check, but it means third-party skills deserve code review. Treat a downloaded skill with a scripts/ directory like any other executable dependency.

Rules are persistent constraints. Skills are reusable workflows. Use rules to keep the agent aligned with the repo, team, and safety model. Use skills when the agent needs a named procedure with sources, steps, examples, scripts, stop rules, and proof.

The simplest operating model is this: if the instruction should be true even when no special workflow is active, put it in rules. If the instruction describes a job that starts and finishes, put it in a skill.