Back to Blog
GuidesEngineering

Codex Skills: Teaching the Agent Your Conventions

Shiplight AI Team

Shiplight AI Team

Updated on July 31, 2026

View as Markdown
Illustrated Shiplight blog cover: a committed instruction file feeding conventions into a coding agent, with an enforcement gate beside it.

By the second week with a coding agent, every team has a list. Use the shared fetch wrapper, not raw fetch. Migrations go in this directory. Do not touch the generated file. Tests belong next to the module.

Repeating that list in every prompt is the problem. Writing it somewhere the agent reads is the fix, and the interesting part is knowing which items need explaining and which need enforcing.

Where instructions live

Agents read committed instruction files from the repository, which is the property that matters. A convention in version control is reviewed like any other change and applies to everyone. A convention in one engineer's personal config applies to one engineer, and nobody knows when it drifts.

Keep the file specific and short. The failure mode is a document that grows into a style guide nobody maintains, at which point the agent is carrying two thousand tokens of advice on every turn and following the parts that happen to land near the task.

What earns its place:

Conventions with reasons. Not "use tabs," which belongs in a formatter. The ones needing explanation: why this module is structured oddly, which patterns are deliberate and which are legacy, what the shared wrapper exists to prevent.

Things that are not discoverable from the code. An agent can read the codebase. It cannot read the incident that caused a guard to be added, or the migration you are halfway through.

What not to touch. Generated files, vendored code, the module being rewritten in another branch. This one saves the most rework.

How to verify. What "done" means here, and how to demonstrate it. Underused and high value: an agent told to run the test suite and check the flow in a browser produces reviewable work; an agent told only to implement produces a diff.

Explaining versus enforcing

The distinction that decides whether a convention actually holds.

An instruction is advisory. The model reads it, weighs it against the task, and usually complies. Under pressure from a task that seems to require otherwise, it may not. That is not disobedience; it is a system that interprets rather than executes.

A hook or a lint rule is binding. Deterministic code that runs on an event and cannot be reasoned around.

So: explain the things where judgment is appropriate, and enforce the things where it is not. "Prefer composition over inheritance here" is guidance. "Never commit a change to the generated schema file" is a rule, and it belongs in a pre-commit hook or CI check where it will hold every time.

Teams that put everything in the instruction file are surprised when the agent occasionally ignores something important. It was always going to.

The layered version of this distinction, with skills, subagents, hooks and MCP servers each doing a different job, is in Claude Code skills. The reasoning transfers across agents even where the mechanisms differ.

Capability versus knowledge

An instruction file cannot give an agent something it does not have.

If the agent needs to open a browser, query a database, or read your issue tracker, that is an MCP server, not a paragraph. See what is MCP?

The two work together and underperform separately. An agent with a browser but no procedure checks the happy path and stops. An agent with a detailed verification procedure and no browser cannot follow it. This is why Shiplight ships as an MCP server plus a set of skills rather than either alone: the browser access needs a protocol, and knowing how to verify a change properly is knowledge.

Keeping it honest

Update it when you correct the agent. The correction you just typed is the missing line. If you are typing it a third time, that is the signal.

Prune it. Advice about a module that no longer exists is context cost with no benefit, and it makes the rest less likely to be followed.

Review it like code. It changes the behavior of every engineer's agent. That deserves a pull request.

Do not let it substitute for verification. An instruction file makes the agent's output more likely to be right. It is not evidence that any particular change is. An agent reporting success is assessing work it just did, from the context that produced it, which is covered in can coding agents test their own code?

Frequently Asked Questions

1

Where do I put instructions for Codex?

In a committed instruction file in the repository, so the conventions are reviewed like any other change and apply to the whole team rather than one machine.

2

What should go in the file?

Conventions that need a reason, things not discoverable from the code, what not to touch, and how to verify a change is done.

3

Why does the agent sometimes ignore my instructions?

Because they are advisory. The model weighs them against the task. Anything that must hold every time belongs in a hook or a CI check instead.

4

Can instructions give the agent new capabilities?

No. Reading a browser or a database requires an MCP server. Instructions teach an agent how to use what it already has.

5

How long should the file be?

Short enough that all of it gets followed. A long file costs context on every turn and dilutes the parts that matter.

Related Reading