{"id":2956,"date":"2026-09-07T03:13:35","date_gmt":"2026-09-07T03:13:35","guid":{"rendered":"https:\/\/dmarketertayeeb.com\/blog\/audit-agents-md-skills-instruction-debt\/"},"modified":"2026-09-07T03:13:35","modified_gmt":"2026-09-07T03:13:35","slug":"audit-agents-md-skills-instruction-debt","status":"publish","type":"post","link":"https:\/\/dmarketertayeeb.com\/blog\/audit-agents-md-skills-instruction-debt\/","title":{"rendered":"How to Audit AGENTS.md and Skills for Instruction Debt Before Rewriting Them"},"content":{"rendered":"\n<p><strong>Before you delete or rewrite an <code>AGENTS.md<\/code> file for GPT-6 Astra, audit the full instruction chain and test the rules that create friction.<\/strong> A shorter file can be easier to maintain, but brevity by itself does not prove better coding, safer tool use or lower usage. The useful deliverable is a small, reviewable cleanup backed by evidence from the files and task scenarios.<\/p>\n\n\n\n<p>OpenAI&#8217;s current <a href=\"https:\/\/developers.openai.com\/api\/docs\/guides\/latest-model?model=gpt-6-astra\">Astra model guidance<\/a> says the model can be more sensitive to instructions in skills and other accessible files such as <code>AGENTS.md<\/code>, and recommends auditing them. That is a reason to inspect your setup, not a command to remove every rule. This guide turns that recommendation into a read-only audit you can run before changing a repository.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">What \u201cinstruction debt\u201d means<\/h2>\n\n\n\n<p>Instruction debt is guidance that still enters an agent&#8217;s decision process after its original reason has disappeared, or guidance that competes with another rule. It usually appears in five forms:<\/p>\n\n\n\n<ul class=\"wp-block-list\"><li><strong>Dead workarounds:<\/strong> a rule added for an older model or a fixed bug.<\/li><li><strong>Duplicates:<\/strong> the same requirement copied into global instructions, project files and skills.<\/li><li><strong>Conflicts:<\/strong> one layer says \u201cask first\u201d while another says \u201ccontinue autonomously,\u201d or two files define different test scope.<\/li><li><strong>Overbroad triggers:<\/strong> a typo fix activates a full architecture review, a whole-repository read or every test suite.<\/li><li><strong>Missing boundaries:<\/strong> the instruction says what to do but does not define completion, authority, evidence or the point where the agent must stop.<\/li><\/ul>\n\n\n\n<p>The word describes a maintenance problem, not a measured model outcome. A rule is not debt merely because it is long, and a short rule is not automatically useful. Keep the rule that protects correctness, narrow the rule that fires too often, and remove only what the audit can show is obsolete or redundant.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Start with the instruction chain, not the largest file<\/h2>\n\n\n\n<p>Codex does not treat every Markdown file in a repository as an instruction file. Its <a href=\"https:\/\/developers.openai.com\/codex\/agent-configuration\/agents-md\">official AGENTS.md documentation<\/a> describes a chain that includes a global <code>AGENTS.override.md<\/code> or <code>AGENTS.md<\/code>, project-level files, and nested files closer to the working directory. Later files appear later in the combined prompt and can override earlier guidance. The default project instruction limit is 32 KiB; fallback filenames can be configured separately.<\/p>\n\n\n\n<p>Skills add another layer. OpenAI&#8217;s <a href=\"https:\/\/developers.openai.com\/api\/docs\/guides\/tools-skills\">Skills documentation<\/a> says the model receives each available skill&#8217;s name, description and path for selection, then reads the full <code>SKILL.md<\/code> when it invokes that skill. Skill content can influence planning, tool use and command execution, so it deserves the same careful review as a project instruction file. The API Skills surface and local Codex skills are related concepts; confirm the discovery rules for the product you actually use.<\/p>\n\n\n\n<p>Build an inventory before judging any line. A local read-only pass can begin with a file list such as:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>rg --files -g 'AGENTS*.md' -g 'CLAUDE*.md' -g 'SKILL.md' -g '*agent*.toml' -g '*hook*' .<\/code><\/pre>\n\n\n\n<p>Then add the global Codex home, configured fallback filenames, skills that are actually available to the model, agent definitions, hooks and permission settings. Record what you could not inspect. Do not label the result a complete audit if the global profile or a linked reference was inaccessible.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">The six-column audit worksheet<\/h2>\n\n\n\n<p>Use one row per material rule or tightly related group. This prevents a vague \u201cthe prompt is too long\u201d conclusion from replacing a useful decision.<\/p>\n\n\n\n<figure class=\"wp-block-table\"><table><thead><tr><th>Column<\/th><th>What to record<\/th><\/tr><\/thead><tbody><tr><td>Source and scope<\/td><td>File path, global\/project\/nested scope, skill name or agent definition.<\/td><\/tr><tr><td>Trigger<\/td><td>When the rule can activate: every task, one skill, a path, a tool, a failure state or a deployment.<\/td><\/tr><tr><td>Authority<\/td><td>What outranks it if another instruction disagrees; include the relevant precedence layer.<\/td><\/tr><tr><td>Observed evidence<\/td><td>A real friction report, a file fact, a test result or \u201cnone yet.\u201d Keep hypotheses separate.<\/td><\/tr><tr><td>Disposition<\/td><td>Keep, shorten, split, narrow trigger, clarify boundary, investigate removal or leave unchanged.<\/td><\/tr><tr><td>Check<\/td><td>The smallest scenario or executable check that could falsify the decision.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n<p>For every row, ask four questions: Does the rule preserve a real project requirement? Does it repeat another layer? Does it change the agent&#8217;s authority or only its writing style? What would a user see if the rule were wrong? A rule with no identifiable benefit is a candidate for a small comparison, not an automatic deletion.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Run paper walkthroughs before making edits<\/h2>\n\n\n\n<p>A public <a href=\"https:\/\/x.com\/Av1dlive\/status\/2096578191691518314\">instruction-debt audit proposal from Avid<\/a> uses paper walkthroughs for a typo fix, a database migration, a UI change, a failing test and a deployment requiring approval. The useful idea is the method: trace request \u2192 activated instructions \u2192 required reading \u2192 allowed actions \u2192 approval boundary \u2192 stopping condition. These are scenarios for analysis, not commands to execute during the audit.<\/p>\n\n\n\n<figure class=\"wp-block-table\"><table><thead><tr><th>Scenario<\/th><th>Look for<\/th><th>Illustrative finding<\/th><\/tr><\/thead><tbody><tr><td>Small typo fix<\/td><td>Does a global \u201calways run the full suite\u201d rule widen a docs-only change?<\/td><td>Hypothesis: narrow the test trigger to code or build behavior, while retaining a link\/format check for docs.<\/td><\/tr><tr><td>Database migration<\/td><td>Does the agent know the source of truth, rollback boundary and approval owner?<\/td><td>Keep the migration safety rule; clarify that a plan and dry run precede any write.<\/td><\/tr><tr><td>UI change requiring visual inspection<\/td><td>Does a \u201ctests passed\u201d rule hide the need for desktop\/mobile visual review?<\/td><td>Keep the visual acceptance condition and name the viewport evidence.<\/td><\/tr><tr><td>Failing local test<\/td><td>Does the agent retry endlessly or widen scope before reproducing the failure?<\/td><td>Narrow the loop: reproduce, inspect the smallest cause, apply one fix, then rerun the relevant checks.<\/td><\/tr><tr><td>Deployment requiring approval<\/td><td>Can the agent draft and validate without treating a plan as permission to deploy?<\/td><td>Keep the approval gate; separate preparation, read-back and live mutation.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n<p>Label each predicted behavior as a hypothesis. A paper walkthrough exposes conflicting language; it cannot prove that the model would choose that path in a real run. If the decision matters, use a disposable fixture and measure the behavior under the same model, effort, tools and acceptance checks.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">A worked audit row<\/h2>\n\n\n\n<p>Consider this illustrative rule:<\/p>\n\n\n\n<pre class=\"wp-block-preformatted\">Always run the full test suite after every change.<\/pre>\n\n\n\n<p>The rule may protect a repository with fragile shared interfaces, but it treats a documentation typo and an authentication change as the same event. A safer proposed replacement keeps the goal while defining the trigger:<\/p>\n\n\n\n<pre class=\"wp-block-preformatted\">For code or build-behavior changes, run the affected checks and the smallest\nrelevant suite. For docs-only changes, run the available link and formatting\nchecks. Run the full suite when shared interfaces, build configuration or\ncross-package behavior changes. Report skipped checks and why.<\/pre>\n\n\n\n<p>This is a proposed diff, not evidence that the new wording improves Astra. The check is a pair of otherwise identical small tasks: a docs-only edit and a shared-interface edit. Record which checks the agent selects, whether the required safety condition is preserved and how long the run takes. Do not turn a single successful example into a general performance claim.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Keep project rules separate from task state<\/h2>\n\n\n\n<p>Rules that rarely change belong in the project instruction layer. Current task state, open questions and the exact next action belong in a task document that can be rewritten. An older <a href=\"https:\/\/github.com\/openai\/codex\/discussions\/323\">Codex discussion on persistent planning<\/a> makes the same distinction: permanent rules should stay concise, while task state should be reset and rebuilt between sessions. Mixing them makes both layers harder to trust.<\/p>\n\n\n\n<p>This also answers a common filename trap. A public <a href=\"https:\/\/x.com\/Khazix0918\/status\/2096125440893329685\">Khazix post<\/a> describes a singular <code>AGENT.md<\/code> rewritten for Astra and says it felt good after brief personal use. That is a useful practitioner signal, but Codex&#8217;s documented automatic names are <code>AGENTS.override.md<\/code>, <code>AGENTS.md<\/code> and configured fallbacks. A singular file is not automatically active unless your setup explicitly maps it. Inspect the loaded chain before crediting a rewrite.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Use human calibration as a preference exercise<\/h2>\n\n\n\n<p><a href=\"https:\/\/x.com\/alex_prompter\/status\/2096572884739338245\">Alex Prompter&#8217;s calibration idea<\/a> uses ten paired choices. Each round varies one dimension\u2014such as length, tone, structure or pushback\u2014so the user&#8217;s choice supplies evidence about a preference. From a later round, an existing rule is put on trial; the final file keeps only a short set of rules supported by choices.<\/p>\n\n\n\n<ol class=\"wp-block-list\"><li>Use a disposable folder and a low-risk task.<\/li><li>Show two outputs that differ in one named dimension, then wait for the user&#8217;s choice.<\/li><li>Record the choice as one imperative rule with its round number.<\/li><li>After several rounds, test one existing rule by showing a version that follows it and a version that breaks it.<\/li><li>Save no file until the user reviews the resulting rules.<\/li><\/ol>\n\n\n\n<p>Calibration captures a person&#8217;s preferences; it does not discover repository safety rules. It also does not make <code>rules.md<\/code> automatically load. If the result should govern Codex, place reviewed durable rules in the documented instruction chain or configure a fallback filename. Keep task-specific preferences in a separate file.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Make the smallest cleanup batch<\/h2>\n\n\n\n<p>After the inventory and walkthroughs, select one or two high-impact changes. A good batch usually does one of the following:<\/p>\n\n\n\n<ul class=\"wp-block-list\"><li>removes a confirmed duplicate while retaining the authoritative rule;<\/li><li>narrows an always-on trigger to the task or path that needs it;<\/li><li>separates permanent project rules from a noisy progress log;<\/li><li>clarifies who can approve a consequential action and what read-back proves it happened; or<\/li><li>replaces an unbounded verification loop with a named acceptance check and exit condition.<\/li><\/ul>\n\n\n\n<p>Keep the before version, the proposed diff and the reason for every change. Do not silently edit global instructions while investigating a project. Review the loaded instruction list in a fresh task, then run the smallest comparable task that exposed the friction.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">What would count as evidence that cleanup helped?<\/h2>\n\n\n\n<p>A static audit can show duplicated language, a wide trigger or a missing boundary. It cannot show that the model performs better. For that, freeze the task, model, effort, tools, fixture and grader. Compare the inherited instructions with a concise rewrite that preserves the same obligations. Record:<\/p>\n\n\n\n<ul class=\"wp-block-list\"><li>correct completion and every required constraint;<\/li><li>unnecessary files or skills loaded;<\/li><li>tool calls, tests and retries;<\/li><li>elapsed time and exposed input\/output usage;<\/li><li>human corrections and safety failures; and<\/li><li>the exact failure example, if either variant fails.<\/li><\/ul>\n\n\n\n<p>Start with a descriptive pilot rather than a universal claim. A six-task, three-variant, two-repetition design would be 36 Astra runs; it is a planning size, not a powered proof. If the result is promising, repeat the revealing cases on Sol or Luna without changing the fixture. A Luna or Sol result cannot establish Astra behavior.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Questions readers usually ask<\/h2>\n\n\n\n<h3 class=\"wp-block-heading\">Should I delete my AGENTS.md file for Astra?<\/h3>\n\n\n\n<p>No. Audit the active chain, keep rules that protect real project requirements, and test narrow rewrites against representative work. The official Astra guidance recommends auditing accessible instructions; it does not recommend deleting them wholesale.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Does a shorter instruction file always save context?<\/h3>\n\n\n\n<p>No. The loaded layers, skill selection, tool results and task history also contribute to context. Measure what is loaded and what the task needs. Do not convert line count into a usage or quality guarantee.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Is AGENT.md the same as AGENTS.md?<\/h3>\n\n\n\n<p>Not automatically in Codex. The documented discovery names include <code>AGENTS.override.md<\/code> and <code>AGENTS.md<\/code>, plus configured fallback filenames. Check your current configuration and loaded instruction report before relying on a singular filename.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Can a calibration prompt create my perfect rules file?<\/h3>\n\n\n\n<p>It can help capture explicit style preferences through controlled choices. It cannot infer every safety, repository or approval requirement. Review the result, place it in the right discovery layer, and test it on real task scenarios.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">How often should I audit?<\/h3>\n\n\n\n<p>Run a light inventory after a model or harness change, after a major repository refactor, and whenever the agent repeatedly asks for approval, runs unrelated work, stops early or repeats tests. Run a deeper scenario audit when you change authority or safety rules.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Method and limits<\/h2>\n\n\n\n<p><strong>Author: Tayeeb Khan, Digital Marketer Tayeeb.<\/strong> This article combines current OpenAI documentation, the open-source Codex implementation, public practitioner posts and public community reports. The original <a href=\"https:\/\/x.com\/pvncher\/status\/2095991462416490862\">Provencher article<\/a> is the broader instruction-cleanup starting point; the new posts add an audit protocol, a short personal rewrite report and a calibration procedure. The social posts are used for workflow questions and reported experiences, not as a representative survey. Khazix&#8217;s result is a brief personal report without a benchmark; Avid&#8217;s and Alex&#8217;s posts are proposed procedures; Lonely&#8217;s post is an amplification of the Provencher lineage. No DMT model-performance experiment has been run for this article. The worksheet examples are illustrative.<\/p>\n\n\n\n<p>For broader task contracts, evidence rules and model-effort choices, see the <a href=\"https:\/\/dmarketertayeeb.com\/blog\/gpt-6-astra-prompting-guide\">GPT-6 Astra prompting guide<\/a>. For the separate problem of context transitions and compaction, use the <a href=\"https:\/\/dmarketertayeeb.com\/blog\/gpt-6-astra-context-management-notes\">Astra context-management notes guide<\/a>.<\/p>\n\n\n\n<p>For model availability and links to the other focused guides, see the <a href=\"https:\/\/dmarketertayeeb.com\/blog\/gpt-6-astra-release-availability-overview\">GPT-6 Astra overview<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>A read-only AGENTS.md and skills audit for GPT-6 Astra: map instruction scope, find conflicts, run scenario walkthroughs, and prepare safe edits.<\/p>\n","protected":false},"author":1,"featured_media":2952,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[386],"tags":[319],"class_list":["post-2956","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-ai-for-marketers","tag-ai-workflows","has-featured-image"],"_links":{"self":[{"href":"https:\/\/dmarketertayeeb.com\/blog\/wp-json\/wp\/v2\/posts\/2956","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/dmarketertayeeb.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/dmarketertayeeb.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/dmarketertayeeb.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/dmarketertayeeb.com\/blog\/wp-json\/wp\/v2\/comments?post=2956"}],"version-history":[{"count":0,"href":"https:\/\/dmarketertayeeb.com\/blog\/wp-json\/wp\/v2\/posts\/2956\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/dmarketertayeeb.com\/blog\/wp-json\/wp\/v2\/media\/2952"}],"wp:attachment":[{"href":"https:\/\/dmarketertayeeb.com\/blog\/wp-json\/wp\/v2\/media?parent=2956"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/dmarketertayeeb.com\/blog\/wp-json\/wp\/v2\/categories?post=2956"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/dmarketertayeeb.com\/blog\/wp-json\/wp\/v2\/tags?post=2956"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}