argument-hint:\n<polish|create> [path] [target ...] [--root-only] [--preserve] [--minimal] [--thorough|--full] [--dry-run] [--force]\ncompatibility:\nRequires curl and a writable user cache directory; network populates or refreshes the GPT-6.1 Sol and Claude Opus 5.5\nprompting guides.\nname: agents-brain\nskill-dependencies:
\nIf these instructions are already present in the conversation from a slash or dollar invocation, follow them directly;\ndo not invoke this skill again through a skill tool.
\nCreate or polish repo-local context as one coherent system: human-facing README.md files, agent-facing AGENTS.md files\n(with companion CLAUDE.md symlinks only for pre-native Claude Code, per Claude Code Compatibility below), existing\nproject-installed skills under .agents/skills, eligible source-catalog skills under skills/<name>/, and context docs\n— any other Markdown files, under any name or directory, whose content is durable guidance for agents or humans, such as\nconventions, command catalogs, data-format rules, workflow runbooks, and reference material.
Success means every selected target is grounded in repository evidence, respects its audience and scope, spends agent\ncontext only on guidance that changes behavior, and passes the narrowest repository-defined validation. Stop after\nreporting completed or planned changes, validation, and any blockers.
\nOptimize skills and other agent-facing context for GPT-6.1 Sol and Claude Opus 5.5 while preserving README.md as clear\nhuman-facing documentation. Before complex, long-running, multi-tool, or orchestration-heavy context work, resolve\nscripts/fetch-guidance.sh relative to this skill directory, run it once for gpt-6.1-sol and once for\nclaude-opus-5-5, and read both returned files completely. The helper retrieves the official\nGPT-6.1 Sol prompting guidance\nand\nClaude Opus 5.5 prompting guidance\nbecause their recommendations may evolve. OpenAI publishes Sol guidance in the shared GPT-6 guide; evaluate its\nfamily-wide prompting recommendations on GPT-6.1 Sol. Simple context work does not require either guide.
Accept an integrity-valid cached guide for 24 hours. Use --refresh for explicitly latest or change-sensitive work,\nmaterially 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\nit and 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\ncannot be returned, stop qualifying work before writing instead of substituting memory or another source. Never create\nthe cache in a repository or skill installation.
\nKeep only content that changes a decision, prevents an evidenced mistake, or supplies a non-discoverable constraint.\nState each meaning once at the narrowest reliable load scope, except where independently installed artifacts need to\nstay self-contained. Preserve authority, safety, material exceptions, semantic success criteria, and exact\nmachine-consumed text. Documentation-only authority does not permit changing helpers or schemas; report an extraction\nopportunity instead.
\nChoose exactly one workflow and read only its reference.
\nFor skill creation, first inspect applicable repository instructions. When they define a source catalog and lifecycle,\nstop and follow that repository-owned workflow. Use skill-writing only when no catalog-specific workflow exists.
| User intent | \nWorkflow | \nReference | \n
|---|---|---|
| Update, refresh, sync, prune, polish, repair, or fix context | \npolish | \nreferences/polish.md | \n
| Create, initialize, generate, or regenerate context files | \ncreate | \nreferences/create-docs.md | \n
| Audit, check, review, inspect, or suggest changes without edits | \npolish in --dry-run mode | \nreferences/polish.md | \n
| Create or scaffold a skill | \nStop | \nUse repository catalog lifecycle or skill-writing | \n
| Install, discover, remove, or rename a skill | \nStop | \nUse a dedicated skill-management workflow | \n
If the intent is unclear, select polish in --dry-run mode and report the smallest useful planned change set.
--dry-run do not.--force authorizes documented overwrites, not deletions. The one standing exception is a CLAUDE.md symlink to a\nsibling AGENTS.md when the installed Claude Code reads AGENTS.md natively (see Claude Code Compatibility): delete it\nwithout asking.Complete authorized discovery, edits, and validation before reporting completion. When one target needs input, continue\nindependent targets and identify the exact unresolved choice. If a skill rule requires a pause, cite that rule and\nexplain why existing authorization does not cover the next action.
\npath: Optional repo-relative subtree. Restrict documentation, package-root, project-skill, source-catalog skill, and\ncontext-doc discovery to that subtree.target ...: Optional filters during polish: skill names from existing .agents/skills/<name>/ or eligible\nskills/<name>/ trees, or repo-relative Markdown paths selecting specific context docs.--root-only: Select only root README.md, AGENTS.md, and CLAUDE.md targets. Exclude project-installed skills,\nsource-catalog skills, and context docs unless explicitly selected by target.--dry-run: Report planned writes and concise diffs without changing files.--preserve: During polish, 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: During create, regenerate existing README.md or AGENTS.md targets without prompting. Never applies to\nskills or deletions.If --minimal and --thorough / --full are both present, make no writes and ask the user to choose. Report\nunrecognized flags; continue only when they cannot change scope, safety, or write behavior.
Run before discovery or writes:
\ncwd=\"$(pwd -P)\"\ncase \"$cwd\" in\n /) printf 'abort: refusing to run at the filesystem root\\n' >&2; exit 1 ;;\nesac\nrepo_root=\"$(git rev-parse --show-toplevel 2>/dev/null)\" || {\n printf 'abort: not inside a git repository\\n' >&2; exit 1; }\nmanaged_skill_root=\ncase \"$repo_root\" in\n /|\"$HOME\") printf 'abort: unsupported repo root: %s\\n' \"$repo_root\" >&2; exit 1 ;;\n \"$HOME/.agents\"|\"$HOME/.codex\"|\"$HOME/.claude\") managed_skill_root=\"$repo_root/skills\" ;;\n \"$HOME/.agents/\"*|\"$HOME/.codex/\"*|\"$HOME/.claude/\"*)\n printf 'abort: repo root is nested under an agent configuration repository: %s\\n' \"$repo_root\" >&2; exit 1 ;;\nesac\nif [ -n \"$managed_skill_root\" ]; then\n case \"$cwd\" in\n \"$managed_skill_root\"|\"$managed_skill_root/\"*)\n printf 'abort: installed skills must be edited in their source catalog: %s\\n' \"$cwd\" >&2; exit 1 ;;\n esac\nfi\nWhen managed_skill_root is set, allow README.md, AGENTS.md, and CLAUDE.md work elsewhere in that repository, but\nexclude the entire installed skills/ tree from every workflow. Apply the exclusion before discovery, canonicalization,\nor symlink traversal. If path, a target, or an explicit request would enter that tree, make no writes there and\nreport that the skill must be edited in its source catalog. --force does not override this boundary.
Outside managed agent-config roots, eligible git-tracked skills/<name>/ source catalogs are in scope for polish per\nreferences/polish.md.
Claude Code v2.1.277 and later read AGENTS.md directly whenever no CLAUDE.md, .claude/CLAUDE.md, or\nCLAUDE.local.md exists in the working directory or above it, so a CLAUDE.md symlink is no longer needed. Detect the\ninstalled version once per run before either workflow touches CLAUDE.md:
claude_version=$(claude --version 2>/dev/null | awk '{ print $1; exit }')\nagents_md_native=false\nif [ -n \"$claude_version\" ] &&\n [ \"$(printf '%s\\n' 2.1.277 \"$claude_version\" | sort -V | head -n 1)\" = 2.1.277 ]; then\n agents_md_native=true\nfi\nWhen agents_md_native=true:
git rm when tracked. Leave regular CLAUDE.md and CLAUDE.local.md files untouched and report\nthem: any such file at or above the repository root still suppresses direct AGENTS.md loading unless the user sets\nProject instructions to claude-md-and-agents-md in /config.When claude is missing or older, keep the pre-native behavior: create or refresh a sibling symlink only where\nCLAUDE.md is missing or already a symlink, and never delete one.
Snapshot git status --short before broad edits. Preserve unrelated pre-existing changes and re-check expected paths\nafter generators or broad commands.
Use git-aware discovery, canonicalize every candidate beneath repo_root, and exclude VCS, dependency, environment, and\nbuild outputs. Deliberately include ignored .agents/skills/*/SKILL.md only when project skills are selected. Discover\ngit-tracked, non-ignored, non-symlinked skills/*/SKILL.md only outside managed agent-config roots and only when\nsource-catalog skills are selected. Parse each selected skill's YAML frontmatter. Inspect only a project-installed\nskill's declared write boundary before deciding whether it qualifies for a coordination exemption. Prefer fd, fall\nback once on suspiciously narrow results, and synthesize independent repository evidence before writing.
Discover context docs by following Markdown links from README.md, AGENTS.md, CLAUDE.md, and SKILL.md files, then by\nscanning remaining tracked Markdown whose content qualifies. Classify by content, never by file name or location.\nExclude changelogs, licenses, legal and policy notices, generated or vendored documentation, and prose that is product\ncontent rather than guidance. When classification is uncertain, leave the file out of scope and report it as a\ncandidate.
\nAfter writes, run repository-defined Markdown formatting or checks when present. If skill frontmatter or\nagents/openai.yaml changed in a project-installed skill, run its invocation metadata check. Verify that no CLAUDE.md\nsymlink remains when agents_md_native=true, and that every retained or created symlink resolves to its sibling\nAGENTS.md otherwise. In --dry-run, report commands that would depend on planned files instead of running them.
Lead with ### ✅ Context updated only after writes and required validation pass,\n### ⚠️ Context updated — validation failed when files were written but required checks fail,\n### \uD83D\uDD0E Context preview — no files written in dry-run mode, or ### ⛔ Context blocked — no files written for a\npre-write stop. Follow with the workflow and scope, material changes, exact validation commands and outcomes, and any\nremaining limitation. Use short prose for a small change; add headings or tables only when they organize repeated\ninformation, and a tree only when directory ownership matters. Follow the user's requested report format.
When issues need a separate section, group verified fixes with evidence as Resolved and remaining problems as Open,\nwith impact and next action. Omit empty groups and report each item once. Reserve blocker for something preventing\nrequired work and risk for a specific potential adverse outcome. A workaround leaves the underlying issue open.
Keep paths, commands, guard-rail errors, symlink targets, and user-authored content exact and undecorated. Omit empty\ndetail and stop once the selected targets meet the completion bar.
\npolish: read references/polish.md.create: read references/create-docs.md.