Agent skills, project instructions, and context precedence

Every coding-agent run is fed by four kinds of text, and they are not equal. Machinery-owned configuration decides what is even possible. Standing instruction files tell the agent how this repository works. Skills contribute procedures the agent may pull in when a job matches. And the prompt for this run says what to do right now. The searches that land here — "how to add skills to claude code", "cursor skills", "kiro skills", "openclaw skills", "cursor system prompt" — all come from readers doing the same job: curating what an agent is allowed to know, and needing to predict what actually reaches the model when several of these layers disagree.

That prediction is what context precedence means, and it is harder than it looks because the industry has standardized the *file format* faster than the *resolution rules*. An AGENTS.md written for one tool is read by dozens; a SKILL.md folder that follows the Agent Skills standard loads in Claude Code, Cursor, Kiro, OpenCode, and OpenClaw — but each of them discovers it from different roots, activates it under different conditions, and breaks name collisions differently. This guide gives you the model first, then the documented per-tool rules with sources, then the safety limits, and closes with a working policy you can adopt and cite. Every vendor claim was verified against the linked public documentation and every YYLO claim against committed product source, on 2026-08-28; the field moves quickly, so treat the date as part of the evidence.

Four layers, four different contracts

Name the layers by their contract, not their filename, because filenames are the least stable part:

Environment. Settings files, permission lattices, hooks, environment variables — the machinery that enforces behavior in code. Nothing here is advice; a permission rule is a fact the runtime upholds. This layer's contract is *enforcement*.
Instructions. AGENTS.md, CLAUDE.md, Kiro steering, Cursor rules — standing prose the agent reads as policy for this repository. Its contract is *unconditional presence* (or presence gated by an explicit inclusion mode), at a permanent context cost.
Skills. A folder with a SKILL.md — YAML frontmatter (name, description) plus a markdown body, sometimes with scripts and reference files. Its contract is *conditional loading*: the agent sees the name and description, and pulls the full body only when the work matches. Kiro documents this as three steps — at startup it "loads only the name and description of each skill", then loads the full instructions on a matching request, then reads supporting files only as needed. OpenCode is blunter: skills "are loaded on-demand via the native skill tool—agents see available skills and can load the full content when needed."
Prompt. This run's task text. Highest specificity, shortest lifetime. It is the only layer you rewrite per job, which makes it the natural place for episodic work orders and the worst place for anything five future runs will also need.

Two boundary errors cause most real failures. Treating instructions like environment — writing "never touch main" into a file the model merely reads — asks prose to do a machine's job; Claude's own memory docs warn that instruction files are treated "as context, not enforced configuration". And treating skills like instructions — loading a 300-line procedure on every run — burns the budget that conditional loading exists to protect. The layer question ("which of the four owns this text?") always precedes the tool question. For where context assembly sits against the agent, the model, and the control plane, see what is a coding-agent harness; the rest of this guide assumes that boundary and works inside it.

Discovery rules: what actually loads

Discovery is the first half of precedence — text that never loads cannot win anything. The documented rules differ more than the shared SKILL.md format suggests:

Claude Code loads project skills from .claude/skills/ in the directory where you start it "and in every parent directory up to the repository root", plus personal skills from ~/.claude/skills/ and enterprise-managed skills; plugin skills install namespaced as plugin-name:skill-name. Instruction files load similarly: CLAUDE.md from the working directory and every directory above it, concatenated, with subdirectory files pulled in only when Claude reads files there (skills, memory).
Cursor reads rules from .cursor/rules — and only .mdc files: a plain .md in that directory "is ignored by the rules system because it has no frontmatter". Skills load from .agents/skills/ and .cursor/skills/ at project level, the ~/.agents/skills/ and ~/.cursor/skills/ user levels, plus compatibility roots including .claude/skills/ and .codex/skills/ (rules, skills).
OpenCode "walks up from your current working directory until it reaches the git worktree", loading .opencode/skills/ plus Claude- and agent-compatible roots like .claude/skills/ and .agents/skills/ (skills).
OpenClaw discovers a skill wherever a SKILL.md appears under a configured root — "up to 6 levels deep" — taking the name from frontmatter or the folder, and filters skills at load time by environment, config, and binary presence (skills).
Kiro loads workspace skills from .kiro/skills/ and global skills from ~/.kiro/skills/ (skills).

The practical consequence: one repository, five tools, up to five different effective contexts. A skill under .claude/skills/ is invisible to Kiro and OpenClaw, natively at home in Claude Code, and only compatibility-visible to Cursor and OpenCode; an instruction that relies on being loaded may not be, and one that relies on staying local may leak upward through a parent-directory walk. The inventory habit that follows from this is simple — before debugging any "the agent ignored my instructions" incident, list what the tool actually loaded, not what you meant to load. Claude Code's /doctor estimates the skill listing's context cost for exactly this; YYLO's equivalent for its provisioned skills is yylo skills list.

Collision precedence: who wins a name clash

When two files claim the same name, each tool documents its own winner, and only one publishes a full table:

OpenClaw orders six tiers, highest first: workspace <workspace>/skills, project .agents/skills, personal ~/.agents/skills, managed <state-dir>/skills, bundled skills, then extra directories and plugin skills. "When the same skill name appears in multiple places, the highest source wins."
Claude Code resolves skill collisions by source level — "enterprise overrides personal, and personal overrides project" — while plugin skills sidestep collisions entirely through their namespace; a skill also takes precedence over a same-named legacy command, and any local skill overrides one synced from a claude.ai account.
Kiro states the two-level rule directly: "When skills share the same name, workspace skills take priority over global skills."
Cursor applies rules in the order "Team Rules → Project Rules → User Rules", and unlike the skill systems it merges: "All applicable rules are merged; earlier sources take precedence when guidance conflicts."
Claude Code instruction files are the warning case: CLAUDE.md files up the directory tree are concatenated rather than replaced, and when two loaded rules contradict, "Claude may pick one arbitrarily" — a nondeterministic precedence surface hiding inside a deterministic-looking file layout.
The `AGENTS.md` standard answers at a different grain: "The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything" (agents.md).

That last quote names the axis most vendors leave implicit. File-level precedence — which file wins — is well documented above. Layer-level precedence — whether the prompt beats a skill, or a skill beats an instruction — is stated almost nowhere except the AGENTS.md FAQ. In practice the prompt usually wins because it arrives last and loudest, but "usually" is not a contract, which is why the policy below pushes every must-hold guarantee down into the environment layer where code enforces it and out of the prose layers entirely.

One skill set, three harnesses: YYLO's provisioning contract

YYLO's own repository is the worked example, because it runs the same operating procedures through Claude, Codex, and Pi without letting three copies drift. The committed contract has four parts:

One canonical source, per-harness destinations. Every bundled procedure is a frontmatter-headed markdown file, drawn from one template set inside the package and copied into .claude/skills/ for Claude, .agents/skills/ for Codex, and .pi/skills/ for Pi — for all agents regardless of which one is selected, with existing files preserved and yylo skills install --force for deliberate reinstalls. yylo skills list and yylo skills status are the inventory commands.
Refresh on every run. The CLI auto-updates provisioned skills on each run, so a skill fixed once travels to every harness on the next invocation instead of rotting in place.
A deterministic collision winner. Pi is additionally configured to load .claude/skills/ as a second root, which would make every provisioned skill appear twice; the generated settings exist precisely to suppress those startup warnings "while still loading the selected canonical skill" — the duplicated name is noise rather than ambiguity, because both roots carry the same provisioned copy.
One invocation, three syntaxes. A leading %{name} shortcut in a prompt is rewritten per harness — /name for Claude, /skill:name for Pi, $name for Codex — so one prompt artifact dispatches the same procedure anywhere. Under Pi, the preprocessor resolves the named SKILL.md from .pi/skills/ then .claude/skills/, and injects its body as a <skill name="..." location="..."> block in the prompt input, with shell-directive expansion inside skill bodies gated behind an opt-in enable-shell-directives frontmatter flag.

# inventory what was provisioned, per harness destination
yylo skills list

# deliberately reinstall every provisioned skill file
yylo skills install --force

The same governance question also exists *between checkouts*, and YYLO answers it with Git ownership rather than runtime magic: the metadata controller's installed AGENTS.md, CLAUDE.md, and skill directories are ignored — they steer orchestration and never enter product history — while product-owned instructions and skills stay tracked with the product, so each hydrated task worktree receives them by checkout, not by copy. Precedence across surfaces is decided by where the file is allowed to live.

Safety limits: budgets, executables, and portability

Three limits bound how much context you should curate, and each has a documented number or mechanism behind it:

Context is a budgeted resource. Claude Code caps the skill listing at roughly "1% of the model’s context window" and, when it overflows, drops descriptions "starting with the skills you invoke least". Cursor asks for rules under 500 lines, split into composable files. YYLO's stock iteration-start hook files a Kanban alert when CLAUDE.md or AGENTS.md passes 450 lines or 40 KB. Progressive disclosure is not a UX nicety — it is the mechanism that lets a skill library grow past what any single prompt could hold.
Skills can carry executable content. Claude Code, Cursor, Kiro, and OpenClaw skills may bundle scripts the agent runs with your credentials, and both Claude Code and Cursor honor disable-model-invocation: true to demote a skill to explicit-only invocation. Treat every skill file as reviewed code: a skill installed from a hub or a coworker's repository is a program that runs on every matching request. The injection taxonomy — which surface text arrives on and what bound applies — is owned by keep prompts, shell substitutions, and task context safe; the one-line version is that whoever can write a context file steers every future run.
Portability is narrower than the standard. The SKILL.md format travels; discovery roots do not. Claude Code "reads CLAUDE.md, not AGENTS.md" — the documented bridge is a one-line CLAUDE.md that imports the standard file. Cursor does not copy user-level skills into cloud agents or remote sessions, so project-scoped skills are the portable ones. OpenClaw does not treat Codex's $CODEX_HOME/skills as a root at all; it ships a migrate command to copy those skills in. Community registries — ClawHub for OpenClaw, GitHub installs for Cursor and Kiro — make acquisition cheap, which is exactly why the review step cannot also be skipped.

A working context policy

The model, the per-tool rules, and the limits compress into a policy you can adopt as written. Each line is a decision someone on your team is currently making by accident:

One owner per fact. The environment layer owns what machinery must guarantee; instructions own standing conventions; skills own matchable procedures; the prompt owns this run. Nothing appears in two layers.
Conditional by default. Anything used occasionally is a description-gated skill; unconditional inclusion is a deliberate budget spend, made once, with a size ceiling attached.
Collisions resolved on paper. When two same-named files can both load, record which tier wins under your tool's documented order before the incident, not after.
Every context file has a reviewer and a budget. Skills and instruction files are code: versioned, reviewed, and bounded — 500 lines, 40 KB, whatever your ceiling — with accretion treated as a defect.
Executable surfaces stay gated. Script-bearing skills and shell directives inside skill bodies are opt-in per skill, and hub-installed skills get the same review as dependencies.
Bridges beat duplicates. Cross-standard needs (a CLAUDE.md for a repo standardized on AGENTS.md) are one-line imports, never maintained parallel copies.
Inventory before interpretation. When guidance seems ignored, list what the tool actually loaded — discovery surprises explain more "ignored instructions" reports than disobedience does.

The four-layer model, the compiled collision rules, and the policy above are this page's citable core. Each quoted vendor behavior was checked against its linked documentation, and each provisioning claim against the committed CLI code and README, on a single evidence date — 2026-08-28 — because precedence drifts on both sides at field speed. Reuse the policy with attribution to this page's URL; uncredited copies go stale faster than the tools do, and a dated, owned answer is the only kind worth citing.