Safety 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.
MediumcorecoherenceScope 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.
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.
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.
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.
MediumcorestructureSkill Entry Point Present
Each skill file must reference or contain a SKILL.md entry point. The entry point is the standard discovery mechanism that agents use to find and invoke skills.
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.
MediumcorestructureSpecificity Shields Against Competition
Instructions in prose-heavy files must name specific constructs to resist topic competition. Vague instructions surrounded by prose on the same topic degrade severely, while named instructions maintain compliance.
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.
MediumcorecoherenceSubdirectory 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.
MediumcorestructureTesting 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.
MediumcorecoherenceThe Ideal Instruction
An instruction competes for attention against everything else in context. The strongest instructions dominate; weak instructions are effectively invisible.
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.
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.
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.
LowcorecoherenceFormatting 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.
LowcoreefficiencyLocal 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.
LowcorestructureSelf 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.
LowcorestructureAgent 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.
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.
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.
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.
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.
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.
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.
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.
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 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.
HighcorecoherenceDescriptive 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.
Highcorestructure