Concept

• Asset Rush - Models are trained to finish by producing a result, so they tend to push ahead on untested hypotheses and state guesses with confidence, and many of the corrections that become skills are counterweights to this pull.
• Completion Criterion - Every step in an agent document should end on a completion criterion whose clarity resists premature completion and whose demand drives the depth of legwork; the strongest are both checkable and exhaustive.
• Context Load Versus Cognitive Load - Material placed permanently in an agent's context costs attention on every task for as long as it stays there, so it is usually better to accept the one-off cognitive load of invoking a skill deliberately than to auto-invoke it.
• Context Pointer - A context pointer is an always-loaded line (a skill description, an AGENTS.md entry) that names out-of-context material and encodes when to reach it, and its wording rather than its target decides how reliably the agent reaches it.
• Fix the Environment, Not the Output - Every agent mistake should become a permanent change to the agent's environment (an AGENTS.md line, a tool, a check), asking which capability is missing rather than telling the agent to try harder.
• Information Hierarchy - An agent document is built from steps and reference arranged on a ladder (in-file step, in-file reference, disclosed reference), and deciding where each piece sits, including disclosure and co-location, is the core structural decision.
• Leading Words in Agent Instructions - Words that are heavily represented in a model's training data, such as "refactor", steer its behaviour strongly and predictably, so instructions should name the task with the established term rather than novel language.
• Lean Skill Instructions - Skill files should front-load their essential instructions into the first 100 lines, phrase them positively, and remove any line that does not change the agent's behaviour.
• Model-Invoked Versus User-Invoked Skills - Every skill can be split on one axis, who can invoke it, trading always-loaded context load (model-invoked) against human cognitive load (user-invoked), with the rule that a user-invoked skill may call model-invoked skills but never another user-invoked one.
• Negation in Agent Instructions - Steering by prohibition activates the forbidden behaviour and makes it more available, so instructions should state the positive target, keeping a prohibition only as a hard guardrail and even then pairing it with the positive.
• Premature Completion - Visible steps still to come pull an agent into ending the current step early; the defence is to sharpen the completion criterion first, and only then hide later steps behind a real context boundary such as a subagent or hand-off.
• Progressive Disclosure - Load only metadata up front, such as skill frontmatter and tool names, and pull bodies, linked files and deferred tools in when relevant; this is now the dominant loading pattern across agent harnesses.
• Router Skill - When user-invoked skills multiply beyond what a person can remember, a single user-invoked router skill that maps the others and when to use each cures the cognitive load, but must be kept in sync or it becomes a router that lies.
• Sediment - Without a pruning discipline, agent documents accumulate stale layers because adding feels safe and removing feels risky; checking each line for relevance, and deleting no-ops by testing against the model's default, keeps them live.
• Self-Authored Skill Drift - When an agent writes its own skills and memory, yesterday's agent can author an instruction today's agent obeys, creating a drift failure class with no code or config change that operators gate with staged write approval and a stale-and-archive lifecycle.
• Shared Language Glossary - A project glossary file gives the agent and the human one ubiquitous language, which cuts verbosity, keeps naming consistent, and doubles as a source of leading words.
• Single Source of Truth and Cache - Each meaning in agent documentation should live in one authoritative place, and any document restating what the environment already says (scripts, config, layout, --help) is a cache that only earns its load when the lookup is expensive or the knowledge is unwritten.
• Skill as Repeated Correction - An agent skill is worth writing when you notice yourself giving the same correction to an agent repeatedly, so the skill captures that correction once instead of re-typing it every session.
• Splitting Skills - Split one agent document into two only when the cut earns the load it spends: by sequence, when later steps tempt the agent to rush the current one, or by invocation, when a distinct leading word or another skill needs to reach part of it independently.
• Steering Files as Navigation Pointers - Always-loaded steering files (AGENTS.md, CLAUDE.md) work best as a short map of pointers into a versioned docs system of record, with coding standards enforced at review and mechanical rules turned into deterministic checks.
• Thin Orchestrator Skills - User-invoked entry-point skills can be a line or two long, delegating to a model-invoked primitive by explicitly instructing the agent to call the Skill tool, so behaviour lives in one place and is composed rather than copied.