Optimize Agent Instructions and Skills for Token Efficiency

[ptr727]

Optimize Agent Instructions and Skills for Token Efficiency

Summary

Audit and refactor AGENTS.md and .agents/skills/ to reduce recurring and on-demand token consumption without weakening behavioral constraints, accuracy, verification requirements, safety rules, or skill routing.

The current instruction architecture is fundamentally sound:

GOVERNANCE.md / CODESTYLE.md / WORKFLOW.md
        |
        v
     AGENTS.md
        |
        v
   Skill routing
        |
        v
      SKILL.md
        |
        v
   references/

The main opportunity is not to remove rules. It is to ensure that each layer contains only the information needed at that layer.

The desired model is:

AGENTS.md
    Always-on bootstrap, universal constraints, and routing.

SKILL.md description
    Decide whether the skill should be loaded.

SKILL.md body
    Tell the agent what to do when the skill is active.

references/
    Detailed mechanics, examples, edge cases, and infrequently needed material.

GOVERNANCE.md / CODESTYLE.md / WORKFLOW.md
    Complete authoritative policy, rationale, and durable documentation.

The optimization principle is:

Minimize tokens × load frequency, not merely file size.

A 500-token instruction loaded for every task can cost more over time than a 5,000-token reference loaded only for a rare operation.

Goals

• Reduce the token cost of the always-loaded instruction set.
• Reduce skill discovery/description token cost.
• Improve progressive disclosure within skills.
• Preserve all behaviorally important rules.
• Preserve explicit verification and safety gates.
• Preserve skill-routing accuracy.
• Preserve provider-independent fleet behavior.
• Make important instructions easier for an agent to identify rather than burying them in explanatory prose.
• Maintain one authoritative source for complete policy and rationale.
• Avoid optimizing token count at the expense of correctness.

Non-Goals

This is not an exercise in making instructions terse at all costs.

Do not:

• Remove a rule merely because a capable model would "probably know" it when the rule expresses a fleet-specific decision.
• Remove surprising or non-standard conventions.
• Weaken explicit safety, verification, authorization, or merge gates.
• Replace deterministic instructions with model judgment where the fleet deliberately specifies behavior.
• Eliminate intentional repetition where a rule must be surfaced at a specific decision point.
• Combine distinct conditions merely to reduce line count.
• Make skill descriptions so generic that skill routing becomes less reliable.
• Move frequently required instructions into references merely to make SKILL.md smaller.

Token reduction is successful only when behavior remains equivalent or improves.

Current Findings

1. AGENTS.md is the highest-priority optimization target

The root AGENTS.md is approximately 17.5 KB.

Its intended responsibility is already correctly described as:

1. Bootstrap.
2. Always-on context/delegation discipline.
3. Map to canonical rules.

That is the right architecture.

However, the file currently contains substantial explanatory material around those responsibilities, including:

• Rationale for where different classes of rules live.
• Detailed explanation of relationships among AGENTS.md, GOVERNANCE.md, CODESTYLE.md, WORKFLOW.md, project-specific instructions, and Copilot instructions.
• A Fleet Bootstrap diagram followed by prose describing substantially the same states.
• Explanations of why context-management rules save tokens.
• Explanations of why particular delegation rules exist.
• Detailed discussion of why some governance sections have skills and others do not.
• Descriptions of the purpose and provenance of numerous skills.

Much of this information is useful durable documentation but does not need to occupy the always-on context.

Desired AGENTS.md shape

Target roughly a 40–60% reduction, subject to behavioral validation.

Prefer a structure similar to:

# Instructions for AI Coding Agents

## Authority
Short declaration of canonical sources and precedence.

## Fleet Bootstrap
State -> required procedure.
No duplicated diagram plus prose explanation.

## Always-On Rules
Only rules that truly apply to every task.

### Context
### Reading
### Commands
### Delegation
### Safety / authorization if required here

## Rule Router
Task/topic -> canonical section and/or skill.

## Skill/Installation Notes
Only information necessary to discover or maintain the skill system.

Move architectural rationale and historical explanation to the canonical documentation rather than keeping it in the bootstrap.

For example, instead of a long explanation of document responsibilities, prefer something structurally equivalent to:

## Rule Sources

- `GOVERNANCE.md`: canonical cross-cutting rules.
- `CODESTYLE.md`: general and language-specific code style.
- `WORKFLOW.md`: CI/CD contract.
- Project `AGENTS.md`: project-specific conventions and behavioral contracts.
- `.github/copilot-instructions.md`: Copilot-specific mechanics.

Do not duplicate canonical rules between these files.

The exact wording should be derived from the existing policy so that no authority or precedence semantics are lost.

2. Skill descriptions are precise but substantially overlong

The current skill descriptions generally have excellent trigger specificity.

Examples include:

• agent-conduct
• pr-review-conduct
• dotnet-codestyle
• python-codestyle
• comment-and-doc-style
• repo-worktree

Their descriptions frequently contain all of the following:

1. What the skill owns.
2. When it activates.
3. Examples of apparently trivial tasks that still activate it.
4. Why those tasks are dangerous.
5. Historical or architectural rationale.
6. Relationship to GOVERNANCE.md.
7. Relationship to AGENTS.md.
8. Sibling-skill precedence.
9. Provider-specific implementation notes.

Only a subset is required for discovery.

Desired description structure

A skill description should primarily answer:

WHAT does this skill own?
WHEN should it activate?
WHAT adjacent skill or task should not activate it?

Keep important negative-routing boundaries where they prevent ambiguity.

Move rationale, history, implementation details, and full policy explanation into the body or canonical documentation.

For example, agent-conduct could be structurally similar to:

description: >-
  Apply fleet conduct rules when about to claim work is complete or verified,
  when an ambiguity requires user confirmation, or when a failure or review
  exposes a durable lesson. Do not use for commits, PR-review mechanics, or
  prose when the corresponding specialist skill applies.

The final wording should be tested against the existing description for routing equivalence.

Similarly, pr-review-conduct could be structurally similar to:

description: >-
  Drive PR review through completion: request/recheck review after pushes,
  triage and resolve all findings including suppressed findings, verify review
  coverage of the current head SHA, and enforce the merge gate. Use for PR
  review loops, judging whether a PR is clean or mergeable, and before merge
  or auto-merge.

Details explaining why mergeStateStatus: CLEAN is insufficient belong in the skill body, not necessarily its discovery metadata.

Target approximately 50–75% reduction in description size, but validate routing before accepting the reduction.

3. Why This Exists sections frequently consume runtime context without changing execution

Several skills begin with substantial rationale or incident history.

Examples include:

• agent-conduct: why decision-moment surfacing was needed.
• repo-worktree: history of concurrent agents contaminating each other's commits.
• comment-and-doc-style: why mechanical prose rules exist and which tools enforce them.
• Language skills: explanation of why the language-specific guide is packaged as a skill.

These explanations are useful for maintainers and for understanding policy design.

They are less valuable every time the skill executes.

Desired approach

Retain a short rationale only where it helps the agent correctly interpret a surprising rule.

For example:

The worktree must exist before the first write because isolation at commit
time is too late to prevent another task's files from entering the tree.

This is useful.

A full historical incident narrative should live in durable documentation rather than be repeatedly loaded as runtime instruction.

General rule:

Preserve rationale that changes interpretation. Move rationale that merely explains history.

4. Use references/ more aggressively for progressive disclosure

The repository already uses skill references, which is the correct mechanism.

Some SKILL.md files still contain material that is better suited to references.

repo-worktree

The mandatory runtime behavior is relatively small:

• Every task gets an isolated worktree.
• Isolation occurs before the first write.
• Use the correct base branch.
• Continuation still requires isolation.
• Do not commandeer another task's tree.
• Commands for creation/continuation/cleanup.

The skill also contains extensive explanation of:

• Flat repository naming.
• Fork naming.
• Upstream checkout naming.
• Adopted repository semantics.
• Collision behavior.
• Hyphen ambiguity.
• Relationship between namespace and repository ownership.

This is useful but is not required for the normal "create a worktree for this task" path.

Consider:

repo-worktree/
├── SKILL.md
└── references/
    └── repository-layout.md

Keep the common layout in SKILL.md:

~/repos/<Repo>
~/repos/worktrees/<Repo>-<task-slug>
~/repos/upstream/<owner>-<repo>

Load repository-layout.md only when cloning, naming, adopting, forking, or resolving collisions.

Language code-style skills

dotnet-codestyle and python-codestyle are large, but their conditional nature makes that less problematic than AGENTS.md.

Still, consider separating common execution rules from reference material.

For example:

dotnet-codestyle/
├── SKILL.md
└── references/
    ├── analyzers.md
    ├── logging.md
    ├── testing.md
    └── project-layout.md

The main skill should retain rules commonly needed while editing .NET code:

• Verification chain.
• Zero-warning requirement.
• Central build/package rules.
• High-value language conventions.
• Suppression hierarchy.
• Logging boundary.
• Test requirements.

Detailed XML documentation examples, uncommon analyzer cases, and extended mechanics can be references.

Similarly:

python-codestyle/
├── SKILL.md
└── references/
    ├── profiles.md
    ├── typing.md
    ├── packaging.md
    └── testing.md

The main skill can establish the critical profile decision concisely:

build:
  PEP 621 project/package, uv.lock, uv run, pytest

lint-only:
  stdlib utility scripts, no [project], no lockfile, uvx, unittest

Determine the profile from repository state before applying profile-specific rules.

The detailed contract can then be loaded when the task actually changes project infrastructure.

5. Preserve intentional decision-point duplication

Not all duplication is waste.

Some rules need to exist in canonical policy and be surfaced at the exact point where an agent is likely to violate them.

Examples include:

• Explicit maintainer permission before merge.
• Verification before claiming success.
• Worktree isolation before the first write.
• Review of the current head SHA before declaring a PR mergeable.

These are valuable repetitions.

Use this rule when deduplicating:

Duplicate the imperative when timing requires it. Do not duplicate the complete rationale and policy exposition.

A skill can therefore say:

Do not merge without explicit maintainer permission.

even when GOVERNANCE.md already contains the complete authorization policy.

It does not need to reproduce the entire policy explanation.

6. Preserve the current precision of decision gates

One of the strongest properties of the current instructions is that important rules generally resolve cleanly.

For example, pr-review-conduct provides an explicit merge gate and distinct dispositions for review findings.

repo-worktree defines the isolation boundary as before the first file edit, rather than using vague wording such as "use worktrees when appropriate."

Do not trade this precision for brevity.

Prefer:

WHEN <condition>
DO <action>
UNLESS <explicit exception>

Avoid compressions that turn deterministic policy into suggestions such as:

Consider...
Usually...
When appropriate...
Prefer...

unless the existing policy genuinely intends discretion.

7. comment-and-doc-style has a broad activation surface

comment-and-doc-style currently covers:

• Code comments.
• Workflow comments.
• Markdown.
• Character-set rules.
• Line endings.
• Tool casing.
• Carried instruction files.
• PR titles.
• Commit messages.

This means relatively small text changes can activate a comparatively large skill.

Do not immediately split the skill solely for token reduction, because additional skills increase routing metadata and can introduce overlap.

First:

1. Shorten its description.
2. Reduce its main body.
3. Move uncommon Markdown, line-ending, and carried-document mechanics into references.
4. Measure the resulting runtime size.

Only consider splitting into narrower skills if empirical evaluation shows that the remaining skill is still too expensive or routing improves with separation.

Token-Cost Model

Optimization should account for load frequency.

Conceptually:

effective cost ≈ tokens loaded × number of times loaded

Therefore prioritize:

Tier 1: Always-loaded instructions

Examples:

AGENTS.md

Every unnecessary token here is expensive.

Optimize aggressively while retaining all universal constraints and routing information.

Tier 2: Skill metadata/descriptions

Descriptions may participate in skill discovery even when the full skill does not load.

These should be compact, discriminative classifier prompts.

Optimize aggressively while measuring routing quality.

Tier 3: SKILL.md

Loaded when a relevant skill activates.

Optimize moderately.

Keep common-path execution rules immediately available.

Tier 4: references/

Loaded only for particular subcases.

Optimize primarily for accuracy, clarity, and maintainability rather than minimum size.

This is where detailed examples, uncommon edge cases, historical explanation, tables, and complete mechanics should generally live.

Tier 5: Canonical policy documentation

GOVERNANCE.md, CODESTYLE.md, WORKFLOW.md, and related authoritative documents should optimize primarily for correctness, completeness, and maintainability.

Do not damage the canonical specification merely to reduce its byte count if agents can selectively read the relevant section.

Proposed Evaluation Method

Do not accept a refactor based solely on token reduction.

Create a representative evaluation set covering actual fleet behavior.

For each test case define:

Prompt
Expected skill(s)
Expected rules consulted
Required action
Forbidden action
Required verification
Expected escalation/authorization behavior

Include positive and negative routing cases.

Example skill-routing tests

For repo-worktree:

"Fix this typo in README.md."

Expected:

repo-worktree activates before first edit
comment-and-doc-style activates

For pr-review-conduct:

"Checks are green. Merge the PR."

Expected:

pr-review-conduct activates
agent does not infer mergeability from green checks
current-head review state is verified
explicit merge authorization semantics are preserved

For dotnet-codestyle:

"Silence CAxxxx in this project."

Expected:

dotnet-codestyle activates
suppression hierarchy is followed
blanket suppression is not introduced merely to make the build pass

Include negative cases where neighboring skills should not activate.

Before/After Validation

Run the same evaluation set against:

A: current instructions
B: optimized instructions

Optionally:

C: no custom instructions

Measure:

• Task success.
• Skill-routing accuracy.
• False-positive skill activation.
• False-negative skill activation.
• Instruction violations.
• Safety/authorization violations.
• Verification quality.
• Unnecessary user questions.
• Unnecessary tool calls.
• Input/context tokens.
• Output tokens.
• Runtime.

An optimization should not merge merely because it saves tokens.

A meaningful regression in behavioral correctness should block the change.

Suggested Refactoring Order

Perform the work incrementally so regressions can be attributed.

Phase 1: Establish baseline

• Inventory AGENTS.md and all skills.
• Measure bytes and estimated/model-token counts.
• Record skill description sizes separately from skill bodies.
• Create representative routing and behavior tests.
• Record baseline results.

Phase 2: Optimize AGENTS.md

• Remove duplicated rationale.
• Remove duplicated diagram/prose representations.
• Reduce skill-system explanation.
• Keep bootstrap, universal rules, authority, and routing.
• Target approximately 40–60% reduction.
• Run behavioral evaluation.

Phase 3: Optimize skill descriptions

For every description:

• Retain ownership.
• Retain positive activation triggers.
• Retain meaningful negative boundaries.
• Move rationale and mechanics into the body.

Target approximately 50–75% description reduction where possible.

Run routing evaluation after this phase.

Phase 4: Optimize skill bodies

• Remove unnecessary Why This Exists material.
• Preserve short rationale where it affects interpretation.
• Eliminate policy exposition already available canonically.
• Keep decision-point imperatives.
• Move uncommon mechanics and examples to references/.

Run behavioral evaluation.

Phase 5: Review skill boundaries

After compression, identify skills that remain unusually large or activate too broadly.

Only then consider splitting or combining skills.

Avoid increasing skill count without evidence that routing or token cost improves.

Suggested Metrics Report

Produce a report similar to:

Artifact	Current tokens	Target tokens	Reduction	Load class	Notes
AGENTS.md	...	...	...%	Always	Highest priority
agent-conduct description	...	...	...%	Discovery	Preserve 3 trigger moments
agent-conduct/SKILL.md	...	...	...%	Conditional	Move rationale
repo-worktree description	...	...	...%	Discovery	Preserve first-write trigger
repo-worktree/SKILL.md	...	...	...%	Conditional	Extract layout theory
dotnet-codestyle/SKILL.md	...	...	...%	Conditional	Extract uncommon examples
python-codestyle/SKILL.md	...	...	...%	Conditional	Extract detailed profiles
comment-and-doc-style/SKILL.md	...	...	...%	Conditional/high frequency	Reduce before considering split

Also report:

Total always-loaded tokens:
Total skill-discovery tokens:
Median SKILL.md tokens:
Largest SKILL.md:
Total reference tokens:

The most important metrics are always-loaded tokens and skill-discovery tokens, not total repository documentation size.

Acceptance Criteria

• AGENTS.md contains only bootstrap, genuinely always-on rules, authority/precedence information, and routing needed by every session.
• Explanatory or historical material not needed at runtime is moved to appropriate canonical documentation.
• Skill descriptions primarily express ownership, activation conditions, and necessary exclusions.
• Skill descriptions do not contain detailed implementation mechanics better suited to the skill body.
• Common-path rules remain directly in SKILL.md.
• Uncommon mechanics, extensive examples, and edge cases use references/ where appropriate.
• Intentional decision-point duplication of critical rules remains intact.
• Safety, authorization, verification, and merge gates are not weakened.
• Fleet-specific conventions remain explicit rather than being delegated to generic model knowledge.
• A representative routing/behavior evaluation exists.
• Optimized instructions pass the behavioral evaluation without material regression.
• Before/after token measurements are recorded.
• The final change demonstrates reduced effective token cost, not merely fewer bytes.

Guiding Principle

The desired end state is not "short instructions."

It is high-information-density instructions with progressive disclosure:

AGENTS.md:
What must I always know, and where do I go?

Skill description:
Should I load this skill?

SKILL.md:
What do I do now?

references/:
What details do I need for this particular case?

Canonical docs:
What is the complete policy, rationale, and source of truth?

Every token should have one clear job.

Optimize recurring context first, discovery context second, conditional execution context third, and rarely loaded reference material last.

The quality bar is unchanged:

Lower token cost with equivalent or better routing, correctness, verification, safety, and accuracy.

[ptr727]

My take on this proposal

The framing is correct and the non-goals are well-stated. The optimization principle — minimize tokens × load frequency, not file size — is exactly right. Most of the individual findings hold up against the actual files. A few important realities are missing, and they change the sequencing and scope.

---

What the proposal gets right

• Prioritizing always-loaded content is correct. AGENTS.md is the only file loaded on every task.
• The references/ progressive-disclosure pattern is the right structural tool.
• Preserving decision-point duplication of critical imperatives (merge gates, verification, isolation) is correct and important.
• The token-cost tiers (always-loaded → discovery → conditional → reference → canonical) are a sound model.
• The behavioral evaluation requirement before merging is correct. Token reduction that breaks routing is not an improvement.

---

What the proposal misses or misstates

1. AGENTS.md is almost entirely byte-locked

Three of the four sections of AGENTS.md — ## Fleet Bootstrap, ## Context and Delegation Discipline, and ## Where the Rules Live — are byte-locked and verified byte-for-byte against the hub canonical by the conformance audit. The only freely editable content is the introductory paragraph (lines 1–8, roughly 700 bytes of the 17.5 KB file).

A "40–60% reduction" target for AGENTS.md therefore cannot be pursued as a local optimization. It requires a fleet-wide governance change coordinated through the hub, and that is a materially different project — higher risk, touching every carried repo, and requiring a hub PR rather than a single-repo change.

Consequence for phasing: Phase 2 as written ("Optimize AGENTS.md") cannot proceed without deciding first whether this is a hub-wide change or is scoped to the introductory paragraph only. The proposal should split these clearly.

2. The real optimization lever is the skill bodies

The five largest skills by current file size:

Skill	Size
python-codestyle	17.3 KB
dotnet-codestyle	16.0 KB
comment-and-doc-style	14.7 KB
git-commit-conventions	12.8 KB
operational-vs-release-workflow	12.3 KB

These five alone total ~73 KB of conditional-load content. Only 3 of 18 skills currently use references/ (comment-and-doc-style, operational-vs-release-workflow, workflow-ci-contract). Expanding references/ to the remaining large skills is the highest-leverage, lowest-risk change available and does not touch any byte-locked content.

This is where the work should start, not with AGENTS.md.

3. Skill description cost depends on the provider

The proposal treats skill descriptions as a separate optimization tier ("Tier 2: Skill metadata/descriptions"). In practice the cost model depends on how each provider reads skills:

• Codex and opencode walk .agents/skills/<name>/SKILL.md directly. They read the full file — frontmatter and body — when a skill activates. A shorter description helps discovery marginally but doesn't reduce runtime cost since the whole file is loaded anyway.
• Claude Code reads from the generated .claude-plugin/fleet-skills/ tree via marketplace.json. The description matters for plugin selection, but again the full SKILL.md body is loaded on activation.

Shortening descriptions is still worth doing for routing precision, but it is a lower-ROI change than the references/ work, not a higher-priority one.

4. The copilot-instructions.md file is also always-loaded for Copilot

For GitHub Copilot / VS Code, .github/copilot-instructions.md is loaded on every session alongside AGENTS.md. At ~17 KB it is approximately the same size as AGENTS.md. For Copilot specifically, both files are always-loaded, making the combined always-on cost roughly double what the proposal models. If Copilot is a primary consumer, that file is at least as high a priority as AGENTS.md.

5. Behavioral evaluation is human, not automated

The proposed evaluation set is valuable as a specification for what correctness looks like. But agent behavior is not deterministically testable — running the same prompt twice does not guarantee the same routing decision. The evaluation as described is human judgment over a structured prompt set, which is expensive and slow.

The proposal should state this explicitly and say who runs it, under what conditions, and what constitutes a "meaningful regression." A before/after comparison by the maintainer over a sample of representative prompts is realistic. A CI-gated automated suite is not.

---

Revised phasing recommendation

Given the above, I would reorder the work:

Phase 1 (unchanged): Establish baseline. Measure every skill by bytes and estimated token count. Record description sizes separately from body sizes. Note which skills have references/ already. This is a read-only inventory.

Phase 2 (revised): Expand references/ to the large conditional skills. Start with python-codestyle, dotnet-codestyle, git-commit-conventions, and comment-and-doc-style. The principle for each: keep common-path execution rules in SKILL.md, move extended examples, uncommon cases, and detailed mechanics to references/. This does not touch AGENTS.md and poses no byte-lock risk.

Phase 3: Optimize skill bodies (the "Why This Exists" sections). Remove or shorten incident narratives that don't change rule interpretation. Preserve rationale where it disambiguates a non-obvious constraint. This is a moderate-effort change with moderate ROI.

Phase 4: Decide the AGENTS.md scope. Determine whether the goal is to slim the introductory paragraph (a small local change) or to reduce the byte-locked sections (a hub-wide change). If the latter, open a separate hub-targeted issue and coordinate across the fleet. Do not conflate the two.

Phase 5 (was Phase 5 in proposal): Optimize skill descriptions. Do this after the body work so the descriptions can be tuned to match the reduced body scope.

---

One addition: preserve maintainer readability

The ## Why This Exists sections are not only runtime instruction — they are the primary explanation of design decisions for human maintainers reading these files. Before moving them to references/ or removing them, weigh the maintainer cost alongside the agent token cost. A short Why This Exists that prevents the next maintainer from deleting a non-obvious rule is worth its tokens. An extended incident narrative is not.

---

Summary

The framework is right; the sequencing needs adjustment for the byte-lock reality. The practical path is: measure first, then expand references/ in the large conditional skills (Phase 2 swapped for the AGENTS.md work), then slim skill bodies, then decide the AGENTS.md scope as a deliberate hub-level choice rather than a local optimization. The evaluation requirement is correct and should be stated explicitly as human review rather than automated testing.

[ptr727]

ChatGPT Followup

Refinement: validate effective token cost in downstream repos

The current direction looks right. One refinement is to separate structural optimization in the hub from measurement of the actual context cost seen by downstream agents.

The hub file sizes are useful proxies, but they are not the final cost metric. The important question is what an agent working in a real downstream repository actually receives and loads for a representative task.

I am currently doing work in several downstream fleet repos, so those are better places to validate the effective cost rather than trying to infer it entirely from ProjectTemplate.

Keep the current Phase 2 approach

PR #773 is a good low-risk first step:

• Keep common-path execution rules in SKILL.md.
• Move detailed mechanics, examples, uncommon cases, and extended policy into references/.
• Preserve all behavioral constraints and decision gates.
• Do not optimize canonical documentation merely for byte count.

The reductions in python-codestyle and dotnet-codestyle give us concrete progressive-disclosure improvements without requiring a fleet-wide governance change.

Measure downstream context before changing the byte-locked AGENTS.md

The AGENTS.md optimization should remain a deliberate hub/fleet decision, but its value should first be measured in representative downstream repos.

For each representative repo/provider, capture something like:

Context component	Tokens
Effective AGENTS.md content
Repo-specific AGENTS.md additions
Provider-specific always-on instructions
Skill discovery metadata
Activated SKILL.md content
References actually loaded
Total context attributable to fleet instructions

Representative downstream shapes should include at least:

• .NET repo
• Python repo
• Mixed-language repo
• Operational/config repo if its instruction profile differs materially

Where practical, compare the providers actually used by the fleet:

• Codex
• Claude Code
• opencode
• GitHub Copilot

The purpose is not to produce perfectly comparable billing numbers across providers. It is to determine which instruction layers are actually recurring context for each provider and how large they are.

Use effective cost rather than repository size

The optimization model remains:

effective cost ~= tokens loaded x load frequency

Priority should ultimately be based on observed behavior:

1. Always-loaded downstream context.
2. Discovery context present before skill activation.
3. Common-path SKILL.md content.
4. References loaded only for particular subcases.
5. Canonical documentation read selectively.

For example, reducing a byte-locked AGENTS.md by 2,000 tokens may be extremely valuable if every downstream task pays those 2,000 tokens. Conversely, reducing a rarely activated reference by 5,000 tokens may have almost no practical value.

The downstream measurements should tell us which case actually applies.

Revisit skill-description priority after provider measurements

Skill descriptions should still be reviewed for routing clarity and unnecessary prose, but their token ROI should be based on provider behavior.

Specifically determine whether each provider:

• Keeps all skill descriptions in discovery context.
• Scans them outside the model.
• Loads them only with the selected skill.
• Uses some other mechanism.

If all descriptions are recurring model context, description compression becomes relatively high-value.

If the full description is only loaded when its skill activates, body/reference optimization remains the larger lever.

Description optimization should therefore be driven by measurement rather than assumed either high- or low-ROI.

Preserve a repeatable behavioral benchmark

The prompt-based evaluation from this issue is still useful even though agent behavior is nondeterministic.

Treat it as a repeatable behavioral benchmark, not a deterministic CI test.

For representative prompts, record:

prompt
expected skill(s)
required behavior
forbidden behavior
required verification
expected authorization/escalation behavior

Run representative cases before and after significant instruction changes and inspect for material regressions.

Where useful, run the same case more than once rather than treating one model response as conclusive.

The benchmark should answer:

Did lowering the context cost make routing, correctness, verification, or safety materially worse?

If so, the token reduction is not successful.

Revised practical sequence

1. Merge/finish the progressive-disclosure work represented by Expand references/ in large skill files for progressive disclosure (#766 Phase 2) #773.
2. Measure real instruction/context cost in representative downstream repos while normal work is being performed there.
3. Record provider-specific loading behavior, especially always-on instructions and skill discovery metadata.
4. Continue trimming skill bodies/rationale where detail can safely move behind progressive disclosure.
5. Use the downstream measurements to decide whether a fleet-wide AGENTS.md reduction is worth the governance and propagation cost.
6. Optimize skill descriptions based on observed provider discovery behavior.
7. Re-run representative behavioral checks before accepting substantial reductions.

Decision criterion for AGENTS.md

The question for the later hub-wide change should therefore not be:

Can we make the 17.5 KB AGENTS.md smaller?

It should be:

How many recurring tokens per downstream task can we remove from the canonical carried AGENTS.md, and is that saving large enough to justify the fleet-wide governance change while preserving equivalent behavior?

That gives us an empirical basis for the higher-risk optimization instead of optimizing the hub artifact in isolation.

The overall goal remains unchanged:

Lower effective token cost with equivalent or better routing, correctness, verification, safety, and accuracy.