# Agent Resource Discipline > Use this skill at the start of any non-trivial session in this ecosystem -- the single biggest lever for reducing token / quota / context-window consumption and for keeping the agent productive across sessions. Make sure to load this whenever the work involves more than a few file reads, any PDF handling, multi-file editing, web fetching, or continuation of prior-session work, EVEN IF THE USER DO… - **Type:** Skill - **Install:** `agentstack add skill-a-attia-scicomp-research-skills-agent-resource-discipline` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [a-attia](https://agentstack.voostack.com/s/a-attia) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [a-attia](https://github.com/a-attia) - **Source:** https://github.com/a-attia/scicomp-research-skills/tree/main/skills/agent-resource-discipline ## Install ```sh agentstack add skill-a-attia-scicomp-research-skills-agent-resource-discipline ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Agent Resource Discipline ## How this skill is organised (progressive disclosure) This skill follows the **three-level progressive disclosure** pattern codified by Anthropic's `skill-creator` (see "Adjacent prior art + lineage" below): - **Level 1 (always in context once the skill is loaded)**: this `SKILL.md`, ~250 lines. Contains the universal rules + the decision-procedure for which references to consult. - **Level 2 (loaded on demand by name)**: the `references/*.md` files -- one per discipline. Loaded only when a session actually exercises that discipline. - **Level 3 (planned future work)**: enforcement hooks (SessionStart / PreToolUse / Stop) that mechanise the protocols here so they fire reliably without depending on agent discipline alone. Specification in section "Planned future work: enforcement hooks" below. This is the same pattern the skill itself preaches: load only what you are about to use; defer the rest. ## When to load this skill Load this skill at the start of any session that will involve any of: - reading or grepping more than ~5 files; - handling PDFs (literature survey, related work, supplementary material); - editing or creating files in multiple project sub-directories; - web fetching (publisher pages, arXiv, GitHub, doc sites); - working across multiple agent sessions on the same project (where cross-session memory matters). In practice that's most non-trivial sessions in this ecosystem. The universal one-liners in `~/.scicomp-research-skills/AGENTS.md` Section 6 cover the basics so cheap-and-fast rules fire even without this skill loaded; this skill expands them with the full how-to. ## Why this matters Agent tokens / quota / context-window are the scarcest resources in any non-trivial session. Beyond raw cost, the **attention budget** -- the agent's ability to pick the right detail out of its context -- degrades faster than the nominal context window suggests. Empirical work (Chroma's "context rot" study, cited by Anthropic in their Sep 2025 *Effective Context Engineering for AI Agents* post) shows that recall quality drops well before the window fills. Heavily-loaded contexts also introduce *recency bias* and *goal drift*. This skill therefore optimises for both raw token cost AND for keeping the working set small enough that the agent's attention stays sharp. Default agent behaviour wastes resources in predictable ways: - **Tool mis-selection** (`bash grep` instead of the dedicated `Grep` tool, `bash cat` instead of `Read`, ...) costs tokens AND loses features (paging, structured results). - **Bulk reads** (`Read` with no offset/limit on a 2000-line file when 50 lines would do) burn context window for no gain AND accelerate context rot. - **Re-derivation** (re-reading a PDF that was already summarised in a survey note last session) wastes tokens AND risks contradicting the prior summary. - **Forgetting** (not reading PLAN.md / collection log / notes index at session start) causes the agent to either re-do work or to make decisions inconsistent with prior sessions. - **Re-fetching** (calling WebFetch on the same URL twice in one session) burns external quota and adds latency. - **Goal drift in long sessions** -- the original PLAN.md fades from recent attention as conversation length grows. Manus calls this the "lost-in-the-middle" failure mode and addresses it via *recitation* (re-reading the plan into recent context). These are all preventable with explicit rules. This skill codifies them as a research-flavoured operationalisation of the broader file-as-memory + just-in-time retrieval patterns now standard in the agent-engineering literature. ## The five disciplines This skill loads a small SKILL.md (you are reading it) and provides five per-topic reference files, each loaded on demand. Each codifies one resource-management discipline: | Discipline | Reference file | When to load | |:-------------------------|:----------------------------------------|:--------------------------------------------------| | Tool selection | `references/tool-selection.md` | First time in this session you need a non-trivial file/search/edit operation. | | Targeted reads | (covered in tool-selection.md) | (same) | | PDF lifecycle | `references/pdf-lifecycle.md` | Whenever a session involves PDF intake or re-reading. | | Persistent memory | `references/persistent-memory.md` | Start of any session on a project with PLAN.md / collection log / notes index. | | Context-window budget | `references/context-window-budget.md` | When loading multiple skills, multiple reference files, or multiple PDFs simultaneously. | | Web-fetch discipline | `references/web-fetch-discipline.md` | Whenever WebFetch is called in this session. | Load only the references relevant to the current session. Do NOT load all five at once -- that defeats the purpose. ## Critical rules (apply unconditionally; do not require loading a reference file) These are also in `~/.scicomp-research-skills/AGENTS.md` Section 6, so they fire even if this skill is not loaded. Restated here for in-skill reference: 1. **Use dedicated tools, not Bash equivalents.** - File search: `Glob` (not `find` / `ls -R`). - Content search: `Grep` (not `bash grep` / `bash rg`). - File read: `Read` (not `cat` / `head` / `tail`). - File edit: `Edit` (not `sed` / `awk`). - File create: `Write` (not `cat `). - User communication: response text (never `echo` / `printf`). 2. **Batch independent tool calls into a single message.** A message with three independent `Read`s costs less and finishes faster than three sequential messages. 3. **Read targeted, not bulk.** For files >300 lines, use `Grep` first to locate the relevant section OR `Read` with explicit `offset`+`limit`. The default 2000-line `Read` is for skimming, not routine consumption. 4. **Re-use prior work before generating new work.** Before re-reading a PDF, check `notes/survey_.md`. Before re-deriving a fact, check the audit log / notes / PLAN.md. 5. **Indices are the persistent memory.** Read `PLAN.md` status + `_collection_log.md` + `notes/README.md` at session start; update them at session end if work was done. 6. **Recitation in long sessions.** For sessions exceeding ~50 tool calls, re-read `PLAN.md` (or the relevant section thereof) every ~30-50 calls to combat goal drift. The Manus team identified this as the simplest defence against the "lost-in-the-middle" failure mode in long agent runs. Recitation is cheap; goal drift is expensive. 7. **Do not edit `AGENTS.md` or system-prompt-equivalent files mid-session.** If the agent client uses prompt caching (Claude Code does, OpenCode does for Claude models), editing the cached prefix invalidates the cache and silently 10x's the per-token cost of all subsequent calls in the session. Restart the session if you genuinely need to change agent-facing rules. 8. **Keep errors in the conversation; do not silently retry.** When a tool call fails (dead URL, rate limit, file not found), let the error sit in the conversation so the model adapts. Silent retry loops both burn quota and hide useful failure signal. For structural failures (a citation's PDF really is unobtainable, an arXiv ID is wrong), log to the appropriate audit entry (`_collection_log.md` "Items not found / left for user", `PLAN.md` "Open Questions") so the failure becomes part of the persistent record. ### Note on prompt caching OpenCode (and Claude Code, and Cursor) on Claude models supports **prompt caching** of stable prefixes (system prompt + tools + typically the most recently loaded skill content). Cached tokens are ~10x cheaper than uncached. Implication: re-loading a small skill via `Read` mid-session is **cheaper than carrying its content forward in conversation**, because the cached version pays cached-rate on every subsequent turn. This is part of why the progressive-disclosure model above works: levels 2 + 3 can be loaded fresh when needed without worrying that they'll dominate cost. ## Common rationalizations + rebuttals The agent will, in real sessions, invent plausible-sounding reasons to skip the disciplines above. The pattern is sufficiently consistent that we name + rebut the common ones explicitly. When the agent catches itself thinking one of these, it should treat that thought as a signal to STOP and re-evaluate. | Rationalization | Why the agent thinks it | Rebuttal | |:------------------------------------------------------------------|:-------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------| | "I already read this file last turn; I'll trust my memory." | Avoids the cost of re-`Read`-ing. | The file might have been edited (by you or the user). `Read` is cheap; recall is not always reliable. | | "It's just one extra `bash cat`, no big deal." | The override feels small in isolation. | This is the rationalization that turns a 200-token session into a 20k-token session. One bash-cat is fine; the habit isn't. | | "Let me re-read the PDF to make sure the survey note is right." | Healthy scepticism + low confidence in your own past summaries. | If you have specific reason to doubt the note, target-grep the `.txt` for the suspect fact. If not, trust the note; that's what it's for. Re-reading the whole PDF "to be safe" is the most expensive single action in this ecosystem. | | "I'll load all the section references now so I have them ready." | Tidy-up instinct; wants to "set up" before working. | Loading speculatively is the failure mode the context-window-budget exists to prevent. Load when you actually use. | | "I'll fetch the publisher page to confirm the year." | Wants external verification; doesn't trust local data. | The user verified the bib entry; that's what verification IS. Trust the bib unless you have specific reason to doubt it. | | "I'll skip updating `notes/README.md`; it's just an index." | The deposit feels like overhead at the end of a session. | The deposit funds the next session's withdrawal. Skipping it is the most expensive bug in this ecosystem. | | "I'll process all 14 PDFs now while I have momentum." | Wants to batch-finish a sub-task. | Process one at a time; close each before opening the next. The context-window cost of 14 simultaneous `.txt` files is much larger than the round-trip cost of 14 separate `Read`s. | | "Let me just retry that fetch, it might work this time." | Hope-based rather than evidence-based. | Twice per session is the cap. After that, log to "Items not found" and move on. | | "I'll silently fix this typo in the bib." | Helpful instinct; wants to clean up. | Silent fixes break the audit trail. Add a "Corrections to apply" entry; let the user batch-apply. | | "It's a small task; the protocol overhead would dominate." | Wants to skip first-action / last-action for speed. | A genuinely small task (one file edit, one question answered) is fine. Anything multi-file or multi-step earns the protocol's overhead back several times over. | If you (the agent) find yourself thinking ANY of the left-column phrases mid-session, stop and re-read this table. ## First-action protocol (every non-trivial session) At the start of any session that touches a project with the standard layout (paper-skeleton or similar): 1. **Load** (in parallel, single message): `AGENTS.md`, `PLAN.md` (status fields + open questions), `references/_collection_log.md` (verification status), `notes/README.md` (which surveys exist + their status). Total: 4 small reads. 2. **Decide** which skills the session actually needs (research-paper- writing? literature-survey? human-facing-doc-authoring? this skill? often only 1-2 are relevant -- not all of them). 3. **Decide** which references this session needs from each loaded skill (e.g. just `references/introduction.md` from research-paper-writing, not the whole references/ tree). 4. **Then** start the user's actual task. Step 1 is cheap (4 small reads) and prevents the most common waste mode: doing work the previous session already did, or doing work inconsistent with what the previous session decided. ## Last-action protocol (every session that produced work) Before declaring the session done: 1. **Update the indices** that record this session's output: - new survey notes -> add row to `notes/README.md`. - new bibliography entries / verifications -> append to `references/_collection_log.md`. - status change -> update the relevant `PLAN.md` status field. - new section drafted -> mark in `PLAN.md` outline + maybe add `notes/section_.md`. 2. **Surface contradictions** explicitly. If something this session discovered contradicts prior notes / plan / bib entries, do not silently proceed; add a "Corrections to apply" entry to the relevant log. 3. **Report** to the user what was done + what indices were updated. Steps 1+2 are the "deposit" that funds the next session's cheap "withdrawal" via the first-action protocol. ## Output contract When this skill is loaded, every action the agent takes should be auditable against the rules above. If the agent finds itself about to: - run a Bash command that has a dedicated-tool equivalent -> stop and use the dedicated tool. - do a bulk `Read` of a >300-line file -> stop and either `Grep` first or use `offset`+`limit`. - re-read a PDF that has a survey note -> stop and read the note first. - start work without reading `PLAN.md` / `_collection_log.md` / `notes/README.md` -> stop and read them (in parallel). - finish work without updating those same indices -> stop and update. The goal is **no avoidable waste**, not "minimise tokens at the cost of correctness". When the rules conflict with correctness, correctness wins -- and the conflict gets logged as a "Corrections to apply" entry so the rule can be refined. ## Tool-availability assumptions This skill assumes the agent has tools approximately equivalent to OpenCode's `Read`, `Grep`, `Glob`, `Edit`, `Write`, `Bash`, and `WebFetch`. For agents with more limited toolsets: - **Shell-only agents** (some Claude Code tool configs): use `pdftotext`, `rg`, `fd`, `sed`/`awk` carefully (quote everything; prefer here-docs over `echo` chains; cap output with `head`/`tail` EXPLICITLY rather than relying on the agent's truncation). - **Agents without WebFetch**: load `references/web-fetch-discipline.md` for the protocol of caching fetches into the repo via shell commands (`curl` -> `references/_cache/.html`). - **Agents without parallel tool calls**: serialise; the parallelism rule simply does not apply, but the targeted-read and re-use-prior-work rules still do. ## Adjacent prior art + lineage This skill is a research-flavoured aggregation of patterns that have crystallised across the agent-engineering literature since mid-2025. Citations are given so users (and future maintainers) know what we borrowed, what we adapted, and where the genuinely novel pieces are. **Foundational sources (cited in the rules above):** - **Manus team blog p … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [a-attia](https://github.com/a-attia) - **Source:** [a-attia/scicomp-research-skills](https://github.com/a-attia/scicomp-research-skills) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-a-attia-scicomp-research-skills-agent-resource-discipline - Seller: https://agentstack.voostack.com/s/a-attia - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.