Skills and AGENTS.md: Simplifying Rules for Stronger Instruction-Following Models

Coding agents have increasingly moved from needing repeated reminders to reliably following the rules already available to them. That is a capability improvement, but it also creates an engineering challenge: when Skills, AGENTS.md, or other guidance documents are too broad, an agent may load large amounts of irrelevant context and dutifully execute checks that the current task does not require.

Projects using models with strong instruction-following capabilities therefore need a systematic rules cleanup. The goal is not to add more instructions. It is to eliminate unnecessary triggers, define clear boundaries, and ensure that each instruction applies only when it is relevant.

1. The Core Problem: Models Improved, but Old Rules Did Not

Many teams historically placed sweeping requirements in their project’s root-level instructions:

Before every code change, read architecture.md, database.md, and deployment.md.

This approach once served a practical purpose. Earlier coding agents did not always seek out project documentation on their own, so requiring them to read it every time helped ensure they had the necessary background.

With stronger instruction following, however, the same rule can become counterproductive. Whether the task involves changing a string, adjusting a button’s styling, or fixing a typo, the agent may read all three documents in full. It may repeat the process for subsequent changes.

This creates several problems:

1. Irrelevant information consumes context capacity.
   Architecture, database, and deployment details unrelated to the task compete with useful code, error logs, and business constraints.

2. Execution becomes slower and more expensive.
   Repeated document reads, checks, and summaries add processing steps and increase the amount of text handled.

3. Task boundaries become less clear.
   The model may treat recommendations in a document as mandatory requirements for the current task, leading to unnecessary refactoring or additional checks.

4. Conflicting rules become more disruptive.
   When documents contain incompatible requirements, the model may try to satisfy all of them, repeatedly ask for clarification, pause execution, or decline to continue.

The issue is not simply that the model is “too cautious.” The project’s instructions have not kept pace with its capabilities.

2. Design Skills Around Tasks, Not Technical Domains

A Skill is a collection of operating instructions, checks, and reference material for a particular task. Its defining question should not be “Which technical domain does this cover?” but “Which specific task should activate it?”

Broad Triggers Lead to False Positives

Consider this common but risky description:

Use when working with databases, queries, models, or persistence.

It appears comprehensive, but terms such as “database,” “model,” and “query” cover a wide range of work.

An agent might incorrectly activate the Skill when:

• Updating a page that displays data.
• Changing the sort order of query results.
• Modifying a data structure used only for presentation.
• Fixing mock objects in tests.
• Adjusting a routine filter in the data access layer.
• Updating a business model class unrelated to the database.

Once activated, the Skill may load migration requirements, release checks, rollback procedures, and historical reference material. None of that may help with the actual task, yet it increases the complexity of the agent’s decisions.

Describe Concrete Actions Instead

A narrower trigger would be:

Use only when adding or modifying database migrations, or reviewing the migration release process.

This wording provides three benefits:

• A clear target: Migration files and their release process.
• Recognizable actions: Adding, modifying, and reviewing.
• Separation from adjacent work: Routine queries, business models, and UI logic do not automatically activate the Skill.

The general principle is:

Skill triggers should describe the action being performed, rather than the technical terms a task might involve.

Add Exclusions Where They Prevent Common Mistakes

For frequently misclassified tasks, a short exclusion can help:

Use when adding, modifying, or reviewing migration files and their release process.
Do not use this Skill for changes limited to queries, business models, test data, or UI presentation logic.

More exclusions are not always better. Their purpose is to address recurring false positives, not enumerate every possible situation. A long exclusion list can itself become an unnecessary context burden.

3. Use AGENTS.md as an Entry Point, Not a Project Encyclopedia

AGENTS.md works best as a navigation layer for agents, not as a single repository for all development knowledge.

A useful entry-point file generally needs to answer five questions:

1. How is the project organized?
2. Which rules apply to every task?
3. Which documents should be read only for specific tasks?
4. What basic validation is required after code changes?
5. Which operations require confirmation first?

For example, replace a blanket requirement to read every document with task-based guidance:

Read architecture.md when changing architectural boundaries.
Read database.md when modifying data structures or migrations.
Read deployment.md when preparing builds, releases, or environment changes.
Routine UI fixes, localized logic changes, and copy edits do not require these documents.

This creates a simple context-routing table:

Current task	Documentation to read
Change service boundaries	architecture.md
Modify data structures or migrations	database.md
Prepare a build or release	deployment.md
Fix a routine UI issue	No additional documentation required
Fix localized logic	Follow the relevant directory rules

The core idea is simple: load documentation because the task requires it, not merely because it exists in the project.

4. Layer Rules Instead of Treating Everything as Equally Applicable

Project instructions can be organized into three layers.

Layer 1: Global Invariants

These rules should hold regardless of the task. Examples include:

• Do not commit plaintext credentials.
• Do not delete user data.
• Do not edit generated files.
• Do not bypass existing security checks.
• Ensure formatting checks pass after changes.

Global rules should be few, explicit, and genuinely applicable across tasks.

Layer 2: Directory or Module Rules

These instructions apply only to a particular part of the codebase. For example:

• A service directory must follow a defined dependency direction.
• A module must not access underlying storage directly.
• A category of files must use a consistent error-handling approach.

Keep directory-level rules close to the code they govern rather than forcing every module to share one oversized instruction document.

Layer 3: Task-Specific Skills

These activate only for particular actions, such as:

• Data migrations.
• API compatibility reviews.
• Release preparation.
• Performance analysis.
• Security reviews.
• Large-scale refactoring.

With this structure, the agent can start with a small set of stable rules and load specialized guidance only when needed, reducing context noise.

5. Remove Duplicate Rules and Conflicting Versions

Duplicate instructions are common in large projects. A root-level file might require full tests for every change, a subdirectory file might call for only targeted tests after page changes, and a Skill might require static checks first.

When all of these instructions apply, the agent may struggle to determine:

• Whether the full test suite is mandatory.
• Whether targeted tests can replace the full suite.
• Whether static checks should run before or after editing.
• Which source takes precedence.

A better approach is to assign clear responsibilities:

Global rule: After changes, run validation appropriate to the scope of the change.
Directory rule: For the page module, prioritize local checks and relevant tests.
Release Skill: Run the full build, pre-deployment checks, and rollback validation only when preparing a release.

This preserves safeguards without imposing a heavyweight workflow on every small change.

6. Do Not Write Recommendations as Mandatory Commands

Instructions should distinguish three levels of obligation:

• Must: A requirement whose violation could create security, data, or compatibility problems.
• Should: The recommended approach, with room for reasonable exceptions.
• May: Optional guidance that does not need to be followed every time.

If every statement uses “must,” the model may treat best practices, historical lessons, and hard constraints as equally binding. Even simple tasks can then accumulate unnecessary steps.

For example:

You must read all design documents before making any change.

Can become:

When changing architectural boundaries, you must read the architecture documentation.
For other tasks, consult relevant documents only as needed.

The closer a rule is to an actual risk, the stronger its requirement should be. Guidance based mainly on experience should leave room for judgment.

7. Validate Rules with Representative Tasks

Reading instructions is not enough to determine whether they work. Test them against typical tasks, including:

1. Changing text on a page.
2. Fixing a localized logic error.
3. Adjusting a query.
4. Adding a data migration.
5. Changing a call boundary between services.
6. Preparing a release.
7. Making a change involving sensitive data.

Observe whether the agent:

• Reads irrelevant documentation.
• Activates the wrong Skill.
• Skips required checks.
• Repeatedly asks questions because rules conflict.
• Makes changes outside the task’s scope.
• Treats recommendations as mandatory requirements.

If a simple copy edit activates several complex workflows, the rules are probably too broad. If adding a migration does not load the required data-change guidance, the triggers are too narrow.

8. A Practical Rules-Cleanup Workflow

Use the following process to refactor an existing project’s instructions.

Step 1: Inventory All Instruction Sources

List instructions in root files, subdirectories, Skills, script documentation, and team documents. Identify each source’s scope and precedence.

Step 2: Remove Duplication

Keep one authoritative source for each rule. Other documents should reference it or provide a short reminder rather than reproduce the full text.

Step 3: Narrow the Triggers

Replace “when working in this domain” with “when performing this specific action.” Prefer concrete verbs such as add, modify, delete, migrate, release, and review.

Step 4: Define Context Routing

Specify which documents belong to which tasks. Add a small number of exclusions for common false positives.

Step 5: Distinguish Rule Strength

Clearly separate global constraints, module constraints, and task-level recommendations so that not every instruction appears to carry the same weight.

Step 6: Run Regression Tests with Real Tasks

Test small changes, medium-sized changes, and high-risk changes. Confirm that the rules neither block routine work unnecessarily nor omit essential checks.

Conclusion

Stronger instruction-following models do not mean projects need more rules. They make precise, restrained, and well-structured rules more important.

Skills should activate for concrete tasks, not broad technical vocabulary. AGENTS.md should provide navigation and context routing rather than become a knowledge repository that agents must repeatedly read in full. Global, module-level, and task-specific instructions should be managed separately, with supporting documentation loaded according to the task.

A well-configured agent does not need to know everything at once. It needs the right information at the right time. Cleaning up project instructions can reduce false triggers, shorten execution paths, lower context noise, and produce more consistent code changes.