Section Headers Present
Each instruction file must contain markdown section headers (lines starting with #). Headers organize content into navigable sections that help agents locate relevant instructions.
CriticalcorestructureRules for Core
Filtering by
Structure
38 rulesRoot Instruction File Exists
A root instruction file must exist at the project root. This is the primary entry point for any AI coding agent.
CriticalcorestructureValid Markdown Syntax
Instruction files must contain valid markdown structure. Broken or empty markdown prevents agents from parsing content correctly and can cause instructions to be silently ignored.
CriticalcorestructureShallow Heading Hierarchy
Heading hierarchy must stay at 4 levels or fewer -- no ##### (h5) or deeper headings. Deep nesting makes content harder to scan and signals that the file should be split into smaller files.
HighcorestructureExact Filename Convention
Instruction filenames must contain only alphanumeric characters, dots, underscores, and dashes — matching the pattern ^[A-Za-z0-9._-]+$. This prevents encoding issues, shell escaping problems, and path resolution failures across platforms.
HighcorestructureIdentity Fields In Frontmatter
Frontmatter must include identity fields (id, name, or slug) to uniquely identify the instruction file. Without an identity field, the file cannot be referenced, overridden, or tracked by other rules.
HighcorestructureFrontmatter Block Present
\n<key>: <value>\n---\n lines. The block declares the file's identity (name, description) and scope (paths, loading, maintainer`) so the loader can target it correctly. ---
HighcorestructureExpected Directories Exist
Configuration files referenced by instruction files must exist on disk. The check verifies that at least one config-type file is present, serving as a gate for directory structure validation.
HighcorestructureModular File Organization
A project must contain at least 2 instruction files. Splitting instructions across multiple files keeps each file focused and prevents a single monolithic document from growing unwieldy.
HighcorestructureDescriptive Filenames
Scoped rule files must use lowercase kebab-case filenames ending in .md, .yml, or .yaml. Consistent naming lets developers predict file content from the filename and prevents platform-specific path issues.
HighcorestructureImport Targets Resolve
Import references in instruction files must resolve to existing files. Broken imports create gaps in the agent's context — the agent silently skips missing files without warning.
HighcorestructureHook Valid Event Types
Config files must contain a "hooks" key. This base rule gates hook validation — agent-specific rules (Claude, Codex, Copilot, Cursor, Gemini) supersede with checks for recognized event names per agent.
HighcorestructureHook Handler Has Type
Hook configuration must contain at least one "type" key. Without a type field, the agent cannot dispatch handlers. Agent-specific rules supersede with the valid type enum per agent.
HighcorestructureHook Command Has Field
Hook configuration must contain at least one "command" key with a non-empty string value. The check scans for "command": "..." anywhere in the config file.
HighcorestructureHook Prompt Has Field
Hook configuration must contain at least one "prompt" key with a non-empty string value. The check scans for "prompt": "..." anywhere in the config file.
HighcorestructureImport Depth Within Limit
Import chains in root instruction files should be bounded. Deep import hierarchies increase context loading time and create fragile dependency chains; a change to a deeply nested file can silently break import resolution of files several levels up. The CORE check enforces a permissive absolute ceiling (10 hops) — agents whose @<path> syntax has a documented behavior should declare a per-agent supersede stub with the actual threshold. Of the agents currently in the registry: Claude defines a 5-hop hard limit (see CLAUDE:S:0010); Cursor's @filename is single-level only (see CURSOR:S:0006); Gemini supports chained @file.md imports without a documented max and inherits the CORE ceiling; Codex and Copilot declare CORE:S:0033 in their config.yml excludes: because their instruction files do not honor any @<path> inclusion syntax.
HighcorestructureSkill No README
Skill directories MUST NOT contain a README.md file. All skill documentation belongs in SKILL.md — agents discover and load SKILL.md as the skill entry point. A separate README.md splits documentation across two files and the extra file is never loaded.
HighcorestructureSkill Description Length
The description field in SKILL.md YAML frontmatter MUST be present and concise. The Agent Skills open standard at agentskills.io caps the field at 1024 characters, and GitHub Copilot enforces the same 1024-character cap explicitly. Claude Code caps the combined description + when_to_use text at 1,536 characters in the skill listing. Codex bounds the entire skill list (not the individual description) at roughly 2% of the model context window or 8000 characters. Cursor and Gemini do not document a hard cap but follow the open standard. A description that respects 1024 characters is portable across every agent; long descriptions waste context tokens and risk truncation in the agents that enforce the tighter cap. Front-load the key use case.
HighcorestructureMarkdown Link Targets Resolve
Markdown links in instruction files must resolve to existing files. Broken targets create phantom context — the agent sees the link directive but the referenced content never loads, so the file silently underdelivers compared to what its prose promises.
HighcorestructureChild Nested Instructions
Child instruction files must extend their parent's scope without contradicting it. Contradictions between levels create confusion.
MediumcorestructureAgent Documents Filenames
Agent configuration must document which instruction filenames it checks and in what priority order.
MediumcorestructureScope Fields In Frontmatter
Scoped instruction files must declare their scope boundary in frontmatter using scope:, globs:, or applies_to: fields. Without a declared scope, the file's targeting is ambiguous and the agent cannot determine which files the instructions apply to.
MediumcorestructureSkill Entry Point Present
Every directory under a skills root (e.g. .claude/skills/<name>/) must contain a SKILL.md file. SKILL.md is the entry point the agent's skill loader uses to discover and invoke a skill — a skill directory without it is invisible to the agent.
MediumcorestructureLayered Content Structure
Instruction content must be organized with at least two top-level headings for major topics. This lets the agent quickly find relevant sections instead of scanning a flat wall of text.
MediumcorestructureSkill Directory Kebab Case
Skill files must declare a name: field in frontmatter using kebab-case format (lowercase letters and digits separated by hyphens). Consistent naming prevents path resolution errors across platforms.
MediumcorestructureSingle Topic Per Section
The instruction file must have layered structure with at least 3 headings. Sufficient heading count indicates that content is split into focused sections rather than lumped under one or two broad headings.
MediumcorestructureHook Event Handlers
Config files that define hooks or event handlers must include a heading matching Hook, Event, Trigger, or Pre-commit. Without a labeled section, trigger conditions are buried in unstructured content where they are easy to miss.
MediumcorestructureSettings Scope Declared
Configuration files must contain a heading matching scope-related terms (Settings, Scope, or Configuration). Declaring scope level ensures the agent knows whether settings apply project-wide, per-user, or are system-managed.
MediumcorestructureAgent Memory Directory
Agent memory must be stored in a dedicated directory, separate from instruction content.
MediumcorestructureRules Directory Structure
When scoped rule files exist, they must reside in the expected directory for the agent (e.g., .claude/rules/). This ensures the agent discovers and loads rules correctly at session start.
MediumcorestructureImport References Resolve
Every @path import reference in an instruction file must resolve to an existing file. Broken import references create phantom context — the agent sees the import directive but the referenced content never loads, causing silent gaps in its instruction set.
MediumcorestructureSkill File Length
Skill entry point files must stay under 500 lines. Agents load the full SKILL.md body into context on activation. Long skill files consume context budget and displace conversation history. Move detailed reference material to separate files in the skill directory.
MediumcorestructureSkill Name Matches Directory
The name field in SKILL.md YAML frontmatter MUST match the containing directory name in kebab-case. Skill loaders use the directory name for discovery and the frontmatter name for display — a mismatch causes the skill to be invocable under one name but displayed under another.
MediumcorestructureSubdirectory Instruction Files
Subdirectory instruction files must contain directive content -- actionable instructions the agent can follow. Files without directives or constraints waste the agent's context window without providing guidance.
MediumcorestructurePath Scope Declared
Path-scoped instruction files must declare which paths they apply to via a frontmatter key. Without a scope declaration, the file loads for all contexts instead of being scoped to specific files.
MediumcorestructureHeading As Instruction
Headings should organize content into sections, not carry instructions. The model processes heading content the same as body content, but instructions in headings are structurally fragile — they get lost when files are reorganized, and they can't carry the detail an instruction needs.
MediumcorestructureSelf Contained Skills
Skill files must include headings matching Input, Process, Output, and Constraints. A self-contained skill gives the agent everything it needs to execute the task without hunting through other files.
LowcorestructureLocal Override File
A local override file, when present, should contain at least 20 characters of substantive content. Override files allow user-specific customizations without modifying committed instruction files. The override file is optional — not all projects need user-specific overrides.
LowcorestructureCoherence
42 rulesSpecificity Gap
Instructions must name concrete constructs -- backtick-wrapped tokens, file paths, function names, CLI commands -- instead of abstract concepts. Abstract instructions are dramatically less effective because the model cannot distinguish them from general knowledge.
CriticalcorecoherenceTopic Scatter
Instruction files must focus on 1-2 topics. Instructions spanning multiple unrelated topics compete for attention, degrading compliance on all topics -- while same-topic instructions reinforce each other.
CriticalcorecoherenceSame-Topic Reinforcement and Conflict
Multiple instructions on the same topic must agree in direction. Conflicting instructions on the same topic destroy compliance catastrophically -- the model cannot follow both and may follow neither.
CriticalcorecoherenceSecurity Requirements
The instruction file must contain a section with a heading matching security-related terms (Security, Boundaries, Sensitive, or Access). Without documented security requirements, the agent has no guidance on sensitive files, access restrictions, or security patterns.
HighcorecoherenceCoding Conventions
The instruction file must specify coding conventions — formatting tools, linting rules, and style preferences. Without these, the agent produces code that doesn't match the project's standards.
HighcorecoherenceProject Description Present
The root instruction file must describe the project — what it does and who it's for. This anchors the agent's understanding of context and purpose.
HighcorecoherenceAgent Role Defined
The instruction file must define the agent's role and primary function. Without a clear identity, the agent defaults to generic behavior that doesn't match the project's needs.
HighcorecoherenceNo Inline Style Rules
Instruction files must not use agent-specific rendering directives like inline styles or scripts.
HighcorecoherenceExplicit Prohibitions
Instruction files must contain at least one constraint atom — a sentence that tells the agent what NOT to do. Without explicit prohibitions, the agent defaults to its training priors, which may include destructive actions like force-pushing, deleting files, or modifying sensitive configurations.
HighcorecoherenceDomain Terminology Used
Instruction files must include a section with a heading matching "Terminology", "Glossary", "Terms", or "Domain" that defines project-specific vocabulary. Defining terms prevents the agent from misinterpreting domain-specific words that have different common meanings.
HighcorecoherenceOutput Format Specified
Instruction files must contain a heading referencing Output, Format, or Display. Specifying expected output formats tells the agent what shape its responses should take.
HighcorecoherenceCross Agent Compatibility
Multi-agent projects must have compatible instruction sets — shared instructions must be agent-neutral, with agent-specific content isolated to dedicated files.
HighcorecoherenceNo Ephemeral Content
Instruction files must not contain ephemeral markers like TODO, FIXME, or WIP. These indicate incomplete content that shouldn't be committed.
HighcorecoherenceNo Auto Generated Boilerplate
Instruction content must be human-authored, not auto-generated boilerplate. Generated content lacks the project-specific context that makes instructions useful.
HighcorecoherenceAgent Neutral Main File
The main instruction file must not contain agent-specific directives. Agent-specific syntax belongs in dedicated agent files, not the shared root.
HighcorecoherenceArchitecture Overview Present
The root instruction file must describe the project's architecture. The agent needs to know where major components live to navigate the codebase and make informed changes.
HighcorecoherenceTech Stack Declared
The root instruction file must contain a heading matching technology terms (Stack, Tech, Language, Runtime, or Framework). Declaring the tech stack prevents the agent from guessing or suggesting incompatible technologies.
HighcorecoherenceDirectory Layout Documented
The main instruction file must include a section documenting the project's directory layout using a heading like "Structure", "Architecture", "Layout", or "Directory" and containing a tree listing or path references. Without a visible directory map, the agent cannot reliably locate or place files.
HighcorecoherenceCritical Instructions at Edges
Freeform instruction files must contain at least one directive instruction. Files without directives contribute no actionable guidance and cannot benefit from position-based ordering.
HighcorecoherenceNo Cross-File Duplication
Duplicated instructions across files drift into contradiction as one copy is updated and the other is not. Conflicting instructions severely degrade compliance. However, same-topic reinforcement using different wording is beneficial — distinct instructions that push in the same direction help each other.
HighcorecoherenceContent Dilution
Descriptive prose on the same topic as your instructions competes for attention. Small amounts of context help, but large amounts dilute the instruction's effect. Off-topic content is harmless regardless of volume.
HighcorecoherenceModality Weakness
Hedged instructions ("should", "try to", "consider", "prefer") couple significantly weaker than direct instructions ("do not", bare imperatives).
HighcorecoherencePosition Recency
Instructions at the end of a multi-instruction context dominate. Instructions at the beginning are dramatically weak.
HighcorecoherenceScope-Instruction Conflict
Conditional scopes must not name domains whose conventions contradict the instruction. A scope that activates domain knowledge conflicting with the directive makes the instruction less effective than having no scope at all.
HighcorecoherenceCompound Weakness
Multiple weaknesses in the same instruction compound — an instruction that is hedged AND abstract AND buried early in the file is far weaker than one with any single issue. The effect is multiplicative, not additive.
HighcorecoherenceTesting Framework Documented
The instruction file must contain a heading matching testing terms (Testing, Tests, or Test). Documenting the testing framework tells the agent which tool to use, where tests live, and how to run them.
MediumcorecoherenceWorkflow Definitions
The instruction file must contain a heading matching workflow terms (Workflow, Process, Pipeline, or Steps). Defining repeatable workflows with ordered steps helps the agent follow consistent processes for common tasks.
MediumcorecoherenceValidation Commands Present
The instruction file must contain a heading matching validation terms (Validation, Verify, QA, Lint, or Check). Documenting validation commands tells the agent which quality gates to run before committing.
MediumcorecoherenceBuild And Test Commands
The instruction file must include build and test commands that the agent can run. Without these, the agent can't verify its own changes work correctly.
MediumcorecoherenceCode Block Examples Present
The instruction file must contain fenced code blocks with concrete examples. Code blocks are the clearest way to show the agent exact syntax and patterns.
MediumcorecoherenceCommand Workflow Documented
The instruction file must document command workflows — ordered sequences of steps for common operations like building, testing, and deploying.
MediumcorecoherenceSafety Gate Directives
The instruction file must contain constraint atoms -- safety directives using keywords like NEVER, MUST NOT, or ALWAYS. Without hard boundaries, the agent has no guardrails for dangerous operations.
MediumcorecoherenceMcp Configuration Documented
The main instruction file must contain a heading referencing MCP, Server, or Tools. If the project uses MCP tools, documenting them in the main file ensures the agent discovers available servers at session start.
MediumcorecoherenceStable Content First
Separate stable instructions from frequently-changing content using distinct sections. Stable content (identity, tool names, permanent constraints) should come first. Dynamic content (session-specific guidance, mutable configuration) should come later. The last positions in a file carry the strongest attention weight — placing dynamic content toward the end means updates land in high-attention positions without disrupting stable instructions above.
MediumcorecoherenceInstruction Rationale Present
The default pattern for instructions is a directive or imperative followed by brief context within a focused length. When you need to suppress a behavior, use the golden pattern: directive first, brief positive context, then constraint last. You don't need a constraint for every directive — add constraints only when your goal is to explicitly prevent something.
MediumcorecoherenceRelevance Decay
Instructions are only effective for tasks they're semantically related to. A testing instruction has no effect on documentation tasks — the instruction must be relevant to the work at hand.
MediumcorecoherenceConditional Scope
Conditional instructions ("When X, do Y") are not uniformly weaker than unconditional ones. The "When X" scope text activates the model's knowledge about what's conventional in that domain. If the convention aligns with the instruction, the scope helps. If it conflicts, the scope actively hurts.
MediumcorecoherenceSpecificity Shields Against Competition
Directives in prose-heavy files must name specific constructs to resist topic competition. A vague directive surrounded by prose on the same topic degrades severely, while a named directive holds compliance. The naming shield protects directives you want followed. It does not protect prohibitions: naming a forbidden construct anchors it instead of shielding it, so state prohibitions as abstract categories.
MediumcorecoherenceDefault Behavior Competition
The model always has a default behavior for any task — what it does without instructions. When instructions conflict or are too weak, the model reverts to this default completely. The default is an ever-present competitor.
MediumcorecoherenceThe Ideal Instruction
An instruction competes for attention against everything else in context. The strongest instructions dominate; weak instructions are effectively invisible.
MediumcorecoherenceDescription Coherence
Files that the agent loads on demand — skills, subagents, slash commands — are dispatched by their frontmatter description: field. The agent reads the description first, decides whether the file applies, and only then loads the body. When the description names a narrower concept than the body covers, or when the description and the body are about different topics altogether, the agent never invokes the file for the cases it actually contains.
MediumcorecoherenceFlowcharts for Procedures
Instruction files with branching workflows must include mermaid flowcharts. Numbered lists that contain conditional language ("if", "when", "otherwise") without an accompanying mermaid block indicate a procedure that would be clearer as a diagram.
LowcorecoherenceDirection
3 rulesDirective Density
Instruction files must contain at least one directive atom — a sentence that tells the agent what to do using imperative or absolute modality. Files with only descriptive prose and no actionable directives have no behavioral effect on the agent.
HighcoredirectionInstruction Ordering
Within a topic, the ORDER of instructions matters. Putting the directive first, reasoning between, and the constraint last is significantly more effective than the natural human pattern of leading with prohibitions.
HighcoredirectionDirection Imbalance
Directives and constraints within the same topic must have balanced strength. When prohibitions are written more strongly than enabling instructions, the agent may suppress the intended behavior entirely rather than conditionally gating it.
MediumcoredirectionEfficiency
6 rulesInstruction File Size Limit
Individual instruction files must stay within size limits. Oversized files exceed context windows and degrade agent performance. The check enforces a maximum of 300 lines per file.
HighcoreefficiencyInstruction Elaboration
Instructions with too few tokens are effectively invisible. Instructions padded with generic filler are weaker than shorter, specific ones. The ideal instruction uses multiple DISTINCT relevant terms — each naming a different concrete aspect of the desired behavior.
HighcoreefficiencyTotal Instruction Size Limit
The always-injected ("one round") instruction footprint should stay under 100 KB (102,400 bytes). This counts what the agent loads every turn: eager instruction files (the main file + its imports + the memory index) in full, and progressive-disclosure surfaces (skills, subagents) by their name + description metadata only. On-demand rules, recalled memory entries, and skill / agent bodies load only when needed and are not counted. A bloated always-on footprint wastes context budget every turn and dilutes every instruction it carries.
MediumcoreefficiencyRelated Instructions Grouped
Related instructions must be grouped together, not scattered across the file. Co-location reduces the agent's search effort.
MediumcoreefficiencyItalic Constraints
Constraint instructions (-1 charge) should be wrapped entirely in italic markdown. Full-sentence italic signals the charge type visually, separating the constraint from the directive (+1) and reasoning (0) that precede it.
MediumcoreefficiencyFormatting Effectiveness
Use backtick for code identifiers and italic for emphasis instead of bold on terms inside constraints. Bold draws the model's attention to the wrapped term — on a constraint, that means drawing attention to the prohibited concept.
LowcoreefficiencyGovernance
8 rulesVcs Tracked
All instruction files must be tracked in git. Untracked instruction files create divergence between collaborators -- each developer's agent sees different instructions.
HighcoregovernanceNo Credentials
Instruction files must never contain credentials, API keys, or private keys. Secrets in instruction files get committed to version control.
MediumcoregovernancePermissions Ordered
Permission declarations in agent configuration must follow a deterministic order — deny rules before allow rules, specific patterns before broad wildcards. First-match-wins semantics in permission evaluation mean ordering determines which rule fires. A broad allow: Bash() before a specific deny: Bash(rm -rf ) silently permits the dangerous command.
MediumcoregovernanceForbidden Commands Defined
The main instruction file must contain at least one constraint atom that prohibits specific commands or actions. Listing forbidden operations prevents the agent from executing destructive commands like git push --force, rm -rf, or database mutations without explicit user approval.
MediumcoregovernancePermission Config Denies Sensitive
Configuration files must contain at least one constraint instruction that restricts access to sensitive files. Without an explicit denial, the agent may read or write secrets, credentials, and private keys.
MediumcoregovernanceHook Uses Project Dir Variable
Hook commands must not contain hardcoded absolute paths like /home/user/project/. The check flags "command" values that start with common Unix/macOS base directories. Agent-specific rules supersede with checks for the correct project dir variable per agent.
MediumcoregovernanceProject Config Self Contained
Project configuration must be self-contained — no dependencies on user-specific setup or external state not documented in the project.
MediumcoregovernanceMcp Config Declares Servers
Config files must contain a heading referencing MCP or mcpServers. Without declared server entries, the agent has no record of which MCP tools are available or how they are scoped.
Mediumcoregovernance