Prune Your Agent Skills: Astra's Official Guide to Cutting Instruction Debt

What This Article Covers

The article opens by noting that coding agents have advanced rapidly, but many projects still carry bloated instructions — Skills, AGENTS.md, and task prompts — designed to compensate for older model limitations. When a new model like GPT-6 Astra arrives, the most valuable update is not adding more rules but re‑evaluating existing ones. The goal is to shift specifications from "compensating for model gaps" to "letting the model operate autonomously within correct boundaries."

Skills: More Is Not Better

A skill file is a Markdown prompt, sometimes with scripts, best suited for:

Specific workflows needed only for certain tasks.

Operational instructions for a plugin, tool, or external system.

However, teams often download large numbers of skills. This creates problems because the model first sees only each skill's name and description to decide whether to invoke it. When skills proliferate:

Descriptions consume initial context.

Long descriptions get truncated.

Overly generic descriptions make the model unsure which skill to pick.

Multiple skills contradict each other.

Every skill signals "read me for any related task."

The result is diluted selection signals — the model struggles to invoke the right skill at the right moment.

Concrete Example: Postgres Schema Migration Skill

Bad description:

Create and validate Postgres schema migrations. Use when working with databases, queries, models, or persistence.

The second sentence casts too wide a net: writing a SQL query, discussing an ORM model, or debugging cache persistence all touch "database / queries / models / persistence" but rarely need schema migration guidance.

Better description:

Create and validate Postgres schema migrations. Use when adding or changing a migration, or reviewing its rollout.

This lists three precise trigger scenarios — adding a migration, changing a migration, reviewing rollout — so the model doesn't have to guess relevance.

The article notes that Codex's $skill-creator tool was recently updated to address these failure modes; its first rule: keep descriptions as short as possible while still stating clearly when to use the skill. Public documentation confirms the mechanism: the system reads names and descriptions first (initial skill list capped at 2% of context window, or 8,000 characters if window size unknown), then loads the full SKILL.md only after a match. If there are too many skills, some may not even appear in the initial list. Therefore, a description is a routing rule , not a résumé or ad slot.

Useful Skills Rely on Progressive Disclosure

The second recommendation is "progressive disclosure." Don't write a multi‑workflow skill as a massive manual that the model must read end‑to‑end every time. Instead, structure it in three layers:

Layer 1 – Catalog signal: One sentence stating "what task should come to me."

Layer 2 – Minimal execution guide: After selection, outline the workflow, risks, and entry points.

Layer 3 – On‑demand details: Reference docs, tool parameters, long examples, scripts, templates — loaded only when needed.

This avoids stuffing irrelevant guidance into the current task, saving context and preventing the model from being steered off course by inapplicable rules.

Overly Specific "Recipes" Can Hinder Results

Many skills are written as ultra‑detailed step‑by‑step recipes. Older models needed such hand‑holding, but as models improve at handling ambiguity and context, over‑specification can restrict them. Moreover, repository skills affect other contributors who may use different agents (e.g., Sol, Luna, GPT-6 Astra); constraints that help one model may over‑constrain another.

Steps remain valuable when they capture:

Real external tool invocation patterns.

Business constraints not inferable from the codebase.

Approval boundaries for high‑risk actions.

Reproducible, ordered troubleshooting procedures.

Hard‑won compatibility details.

What should be deleted: encoding generic reasoning the model already performs, such as "read the entire repo before any change" or "draw a full architecture diagram for every tiny edit." These waste time and discourage the model's ability to gather information per task.

AGENTS.md: Standing Instructions Need Even More Restraint

If skills are on‑demand manuals, AGENTS.md is the repo's standing environment guide. It runs on every session, so each line must answer: "Does this task really still need it?"

Requiring a full repo map or multiple documents before every edit is excessive for a typo fix. Stronger models can decide what to read; forced full pre‑reads burn context and slow work.

Before/After Comparison

Anti‑pattern:

Before every edit, read architecture.md, database.md, and deployment.md.

Better:

Use architecture.md for service boundaries, database.md for schema changes, and deployment.md when preparing a deployment.

This changes "absolute preconditions" into "conditional routing" — a map telling the model which route to take for which scenario.

The article also notes a subtle shift: older models needed repeated reminders to run tests and check their work; GPT-6 Astra may do this autonomously, so old reminders can trigger unnecessary test runs. The point isn't "stop writing tests" but "don't make 'please check' the sole quality gate." Instead, define test boundaries clearly: which tests have no side effects, when they can run automatically, which environments/data are off‑limits.

The local tests use disposable fixtures and have no production access. Run them, fix failures caused by the requested change, and rerun affected tests without asking for approval at each step.

This provides safety facts and clear authorization, letting the model close the loop without pausing for permission at every step.

Decision Boundaries: Write Them Precisely

Teams often add hard "ask first" / "do not proceed" rules to prevent unauthorized actions. Astra respects boundaries literally; if a boundary is too broad, the model may stop where you wanted it to continue. The solution is not lower safety but sharper boundaries:

Must approve: Sending email, changing production, transferring funds, public publishing, deleting irrecoverable data.

Autonomous: Local tests without production credentials, read‑only research, reversible temp files, code fixes and retests within the requested scope.

Conditional: e.g., "auto‑rerun tests only when using disposable fixtures and no production credentials."

A good boundary is a decision line that lets the agent distinguish risk levels, not a blanket "prohibit."

Persistence: Define "Done" as an Acceptable State

The article notes that GPT-6 Astra may appear more cautious: it delivers a first implementation then returns for review, even though work remains. The fix isn't a vague "continue" but defining completion criteria up front. If the task includes running the implementation, verifying results, fixing failures, and rerunning affected tests, state that explicitly. If you want a review after the first version, say so — the model will naturally stop earlier.

Write "done" as a verifiable state, not "keep trying" as an emotional slogan.

Example: "Implement, start local env, verify three core paths, fix failures caused by this change, then report" vs. "Try to finish completely." The former gives the agent a finish line; the latter only gives pressure.

Author's Take: Delete Instruction Debt, Not Just Skills

The core issue isn't quantity but instruction debt — layers of guidance added to prop up older models that become noise after the model improves. They consume context, create conflicts, lower selection precision, and can turn an autonomous agent into a rigid process follower.

Yet certain skills must not be deleted just because the model is stronger:

External system interfaces: Private APIs, CLI params, auth flows, internal tool conventions — the model cannot know these.

High‑risk operations: Production changes, payments, data deletion, release processes — need explicit approval and rollback boundaries.

Organizational tacit knowledge: Business rules beyond code style, historical compatibility, ownership, no‑go paths.

Validated specialized workflows: Migration rollout, incident response, compliance checks — value lies in codifying reliable, repeatable steps.

Cross‑model minimum contracts: When the team uses multiple agents, a short, clear, non‑over‑constraining common language is still needed.

Actionable Cleanup Checklist

For each skill and AGENTS.md rule, ask:

Does it have a clear, independent trigger scenario ?

Without loading it, does the model genuinely lack critical facts, tool operations, or safety boundaries?

Does it provide irreplaceable information, or just repeat common sense ("be careful," "check first," "read everything")?

Does it compete with another skill for the same task class?

Can its long‑form details be moved to references, leaving the root file as a pure router?

Are its forced steps — designed for an older model — still necessary today?

Does it clearly separate "must stop and ask" from "may proceed autonomously"?

Items answering "no" to the first three are prime candidates for deletion or merging.

Four‑Step Cleanup Process

1. Inventory First, Delete Later

List every skill's name, description, recent tasks, dependent scripts, and overlap with other skills. See the full catalog before judging duplication — duplication means two skills fighting for the same task type, not just similar filenames.

2. Rewrite Descriptions as Routing Rules

Change each description to " what task + what condition + when to trigger ". It should read like a router, not a landing page.

Bad: Used for all database development. Good:

Use when adding, modifying, or reviewing a Postgres schema migration.

3. Split Body into Router + Details

Keep the root SKILL.md minimal: trigger conditions, core flow, risk flags, pointer to the next reference or script. Move large examples, parameter tables, edge branches, and tool specifics into separate files.

4. Regression‑Test with Real Tasks

Pick a few real tasks: a small fix, a migration, a deployment prep, a high‑risk action. Observe whether the model picks the right skill, loads irrelevant docs, or stops prematurely where it should proceed autonomously. Skill quality is measured by improved selection and completion rates on actual work, not by file length.

Closing Thought

When a new model arrives, the easiest thing is to keep adding rules; the hardest — and most valuable — is admitting some rules have expired. This article's essence isn't "don't use skills" but redesign skills from a prompt warehouse into a clean, on‑demand knowledge system . Less "always read me first," more "call me only in this exact scenario"; less repetitive micromanagement, more precise expression of safety boundaries, completion criteria, and organizational knowledge. The result isn't just a shorter catalog — it's an agent that judges better and sustains work longer.