paulrberg/agent-skills/agents-brain

Agents Brain

If these instructions are already present in the conversation from a slash or dollar invocation, follow them directly. In that case, do not invoke this skill again through a skill tool.

Apply explicit user instructions and established authorization before this skill's defaults. Do not ask again for an unchanged decision. Preserve host restrictions and required destructive-action approval.

Routes

• maintain [path] [target ...] [flags]: Maintain context and apply task-backed skill lifecycle changes. Use this route

by default for context maintenance or inspection. Read references/maintain.md.

• create-skill [skill-name]: Create a project-local skill from an explicit request. Read

references/create-skill.md. Apply its repository catalog guard before scaffolding. Explicit creation does not require recurring-use evidence.

• create-agents-md [path] [--root-only] [--dry-run] [--force]: Initialize AGENTS.md files for a scope from an explicit

request. Create the scope-root file and judge each subtree for a nested file. Read references/create-agents-md.md.

Choose the route before discovery or writes. All routes use the prompting and STE requirements below. The maintenance sections govern maintain. Each creation reference owns its route's scope, workflow, validation, and report.

Maintenance Scope

Maintain repo-local context as one coherent system. It includes these targets:

• Human-facing README.md files.
• Agent-facing AGENTS.md files, with companion CLAUDE.md symlinks only for pre-native Claude Code. See Claude Code

Compatibility below.

• Existing project-installed skills under .agents/skills and eligible source-catalog skills under skills/<name>/.
• Context docs: other Markdown files, under any name or directory, that provide durable guidance for agents or humans.

Examples include conventions, command catalogs, data-format rules, workflow runbooks, and reference material.

Maintain repo-owned skills as task work reveals obsolete workflows, meaningful overlap, or recurring procedures worth capturing.

Success means every selected target meets these criteria:

• Repository evidence supports its content.
• It respects its audience and scope.
• It spends agent context only on guidance that changes behavior.
• It passes the narrowest repository-defined validation.

Stop after reporting completed or planned changes, validation, and any blockers.

Prompting and Context Optimization

Write skills and other agent-facing context for current Claude and GPT agent models, not for one model. Do not name a model, a model version, or a model-specific default in that prose. Content that selects, configures, or attributes a model is the exception, for example routing tables, model: fields, and API parameters. Preserve README.md as clear human-facing documentation.

Before complex, long-running, multi-tool, or orchestration-heavy context work, resolve scripts/fetch-guidance.sh relative to this skill directory. For that work, run it once for anthropic and once for openai. The two runs are independent, so start both in the same turn, as parallel calls or one shell command. Read both returned files completely, in one parallel batch. Run the helper and read the guides only when the task writes or changes prompts, skills, or other agent-facing prose. For other edits, do not run the helper or read either guide. In that case, report guides: skipped (no agent-facing prose).

The helper retrieves Anthropic's prompting best practices and OpenAI's latest-model guide because their recommendations may change. The Anthropic guide covers all current Claude models and links each per-model prompting page. The OpenAI guide covers the current GPT model family. Its prompting recommendations come from tests on one model in that family. Simple context work does not require either guide.

Treat advice that names a model as measured on that model. Apply it to other models only when the cross-model guidance supports it. To check such a claim, read the linked per-model page. When the guides give opposite corrections for different models, state the wanted behavior directly. Do not write a correction to one model's default, such as "be brief" or "write more".

Accept an integrity-valid cached guide for 24 hours. Use --refresh for explicitly latest or change-sensitive work, materially disputed guidance, or conflicts with observed model behavior. Interpret helper diagnostics precisely:

• cached reused a guide validated no more than 24 hours ago without network access.
• revalidated refreshed validation metadata after a successful conditional 304 response.
• fetched atomically replaced the cache with integrity-valid content from the pinned official URL.
• stale reused a guide validated no more than seven days ago after live retrieval failed. Proceed only after reading

it. Disclose the validation timestamp and retrieval failure under open issues and caveats.

Forced refreshes, expired entries, integrity failures, and unexpected redirects fail closed. If either required guide cannot be returned, stop qualifying work before writing. Do not substitute memory or another source. Never create the cache in a repository or skill installation.

Keep only content that changes a decision, prevents an evidenced mistake, or supplies a non-discoverable constraint. State each meaning once at the narrowest reliable load scope, except where independently installed artifacts need to stay self-contained. Preserve authority, safety, material exceptions, semantic success criteria, and exact machine-consumed text. Documentation-only authority does not permit changing helpers or schemas. Report an extraction opportunity instead.

STE Authoring and Review

Before writing or changing agent-facing prose, read references/asd-ste100.md completely. Apply its STE-based profile during writing. Complete its meaning and style review before reporting completion. Preserve obligation strength, uncertainty, conditions, technical precision, and protected literal content. Honor the target's audience and any instructions to preserve accurate user-authored prose. The profile does not establish official ASD dictionary compliance. One complete read of that reference during the current run satisfies every later requirement in this skill to read it, unless the file changed since.

Maintain Workflow

Use $agents-brain maintain for context maintenance and task-backed skill lifecycle changes. Within the requested scope, update existing context, create warranted missing context, and apply task-backed skill lifecycle changes.

In every maintain run, capture corrections. Scan the session for user corrections, such as a restated instruction, "do not do X", "always do Y", or a reverted choice. Record each durable correction as a rule in the nearest in-scope steering file, such as AGENTS.md, or in the owning skill. When a correction is not durable, state the reason in the report: one-off, already stated, or a project-specific exception.

Read references/create-docs.md only when creating or regenerating context. Read references/maintain-skills.md only for skill lifecycle decisions or establishing continuous maintenance. These references support the workflow. They are not separate modes.

For skill creation, use this skill's references/create-skill.md after applying the maintenance evidence gate. Follow applicable source-catalog lifecycle instructions when defined. Installation and skill management outside this repository belong to a dedicated workflow. For inspection-only or unclear intent, use maintain --dry-run and report the smallest useful planned change set.

Maintenance Authority

• Explicit creation, update, repair, fix, maintenance, or equivalent intent authorizes in-scope local writes.

Inspection-only intent, Plan Mode, and --dry-run do not. Carry out evidence-backed removal, merging, and creation when the request or standing repository instructions authorize those lifecycle actions.

• Require explicit confirmation before deleting README.md, AGENTS.md, regular CLAUDE.md files, or context-doc targets.

--force authorizes documented overwrites, not deletions. The one standing exception is a CLAUDE.md symlink to a sibling AGENTS.md when the installed Claude Code reads AGENTS.md natively (see Claude Code Compatibility): delete it without asking.

• Resolve scope from the requested outcome. Preview a large change set, then continue when it is already authorized.

File count alone is not an approval boundary. Ask only when an unresolved choice changes scope or intended meaning.

• Keep context edits documentation-only. When authorized, skill lifecycle work may change the affected skill's owned

files and local consumers. The repository boundary never permits external writes.

Complete authorized discovery, edits, and validation before reporting completion. When one target needs input, continue independent targets. Identify the exact unresolved choice. If a skill rule requires a pause, cite that rule and explain why existing authorization does not cover the next action.

Continuous Repository Skill Maintenance

During an authorized implementation task, notice skill impact while reading relevant guidance, after changing the workflow it describes, and before the final report. Review only skills implicated by that task. When repository instructions or the user authorize continuous maintenance, act on verified opportunities and complete the resulting changes. A recommendation alone is not completion. Finish fixed-scope caller workflows before independent maintenance, except for necessary prerequisites. Read-only tasks remain read-only.

Continuous means repeated attention during normal task work, not a background monitor, scheduled job, or catalog-wide audit. Freeze the boundary to the repository where the task was given. Never follow a skill's source or installation into another repository or a global agent directory. A failed or blocked main task does not prevent an independent, authorized skill improvement supported by verified evidence.

When asked to establish this behavior for future tasks, use the standing-instruction guidance in references/maintain-skills.md to update or create the applicable AGENTS.md. Loading this skill in one session does not by itself make future agents run it.

Maintenance Arguments

• path: Optional repo-relative subtree. Restrict documentation, package-root, project-skill, source-catalog skill, and

context-doc discovery to that subtree.

• target ...: Optional filters: skill names from existing .agents/skills/<name>/ or eligible skills/<name>/ trees,

or repo-relative Markdown paths selecting context docs. Without filters, discover context within the selected tree. Continuous skill lifecycle review still considers only skills implicated by the current task's evidence.

• --root-only: Select only root README.md, AGENTS.md, and CLAUDE.md targets. Exclude project-installed skills,

source-catalog skills, and context docs unless explicitly selected by target.

• --dry-run: Report planned writes and concise diffs without changing files.
• --preserve: Keep accurate user-authored prose and structure. Fix only drift and obvious noise.
• --minimal: Produce the smallest context that still meets the completion bar.
• --thorough / --full: Perform deeper analysis only where it adds durable, repository-specific context.
• --force: Regenerate existing README.md or AGENTS.md targets without prompting. Never applies to skills or deletions.