agent-context-engineering

Stars9

Forks0

UpdatedJuly 15, 2026 at 02:54

Author and maintain agent context markdown — AGENTS.md, rules, skills, memory files. Use when creating, editing, or refactoring any agent-focused doc, or after major codebase exploration to capture learning.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Source

gwenwindflower

gwenwindflower/dotfiles

View GitHub Repository View Creator Repositories

Download

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

name	agent-context-engineering
description	Author and maintain agent context markdown — AGENTS.md, rules, skills, memory files. Use when creating, editing, or refactoring any agent-focused doc, or after major codebase exploration to capture learning.

Agent Context Docs

Every line is loaded on every trigger. If it doesn't change agent behavior, cut it.

[!NOTE] AGENTS.md and .agents/ are both real and stand-ins. They're the shared cross-agent standard adopted by most non-Claude tools, and the generic model for agent-specific equivalents (CLAUDE.md, GEMINI.md, .codex/, etc.). Guidance here applies to all of them.

Principles

Specific and actionable. "Use 2-space indentation in TypeScript" beats "format code properly."
Progressive disclosure. Minimal root file; modular detail loaded on demand.
No redundancy. Don't repeat README, package.json, or anything inferable from code.
Living document. Update after significant exploration to prevent re-crawling.

Authoring AGENTS.md

Include only what an agent can't infer from the code:

1–2 sentence project context (what it is, primary stack)
Goals, priorities, non-goals
Project structure — key directories and their purpose (high token value, prevents repeated fd/tree)
Key commands (build, test, lint) when non-obvious
Architecture: non-obvious patterns, key abstractions, data flow
Conventions that diverge from defaults

Exclude generic language idioms, README content, and vague directives ("write clean code").

Index Pattern

The recommended progressive-disclosure approach:

Put modular docs in docs/ with descriptive filenames (adding-shadcn-components.md)
List them as a tight index in AGENTS.md — plain paths, not @-imports

# Shopping App Agent Guidance

docs/adding-shadcn-components.md
docs/using-drizzle-with-supabase.md
docs/adding-v2-api-endpoints.md

The agent picks what to load. For projects with clear splits (frontend/backend), scope subdirectory indexes:

src/frontend/AGENTS.md → src/frontend/docs/...
src/backend/AGENTS.md  → src/backend/docs/...

Rules vs. docs

Type	Purpose	Scope
Rule	How something should be done, always (workflow, conventions)	User-level if global, project-level if specific
Doc	State of something / how it works (API, architecture)	Skill if cross-project, `docs/` if project-specific

Patterns to Avoid

@reference imports. Most agents inline them fully on encounter. Treat as inlined content; recursive loading (Claude Code: depth 5) compounds bloat.
Rules directories. All files load at session start — equivalent to @-importing every file. Reserve for genuinely universal rules.
Path-scoped frontmatter globs. Better than global, but still automatic rather than agent-driven.

Living Document Workflow

After significant work, update AGENTS.md with new structure, patterns, or decisions. Universally relevant → root; area-specific → docs/ with index entry.

Refactoring Overgrown Files

For AGENTS.md past ~60 lines or with poor structure:

Eliminate conflicting or redundant instructions
Group remaining content by function or path
Move detail into docs/ files; add index entries
Justify each remaining line: does every agent in this directory need it every session?

File Locations

Location	Shared With	Loaded
`AGENTS.md` / `.agents/AGENTS.md`	Team (tracked)	Always
`.agents/rules/*.md`	Team (tracked)	Always
`AGENTS.local.md`	User (untracked)	Always
`~/.agents/AGENTS.md`	User (all projects)	Always
`~/.agents/*`	User (all projects)	Varies by agent

MCP Tool References

Use fully qualified names: ServerName:tool_name (e.g., BigQuery:bigquery_schema). Bare tool names may not resolve when many MCP servers are connected.

More from this repository

same repository

agent-browser

gwenwindflower/dotfiles

Browser automation CLI wrapping Playwright for one-shot tasks like navigation, page interaction, screenshots, and scraping. Use when driving a live browser from the terminal. Skip for repeat automations that warrant a full Playwright script.

2026-07-159

agent-skills

gwenwindflower/dotfiles

Author and audit Agent Skills. Use when creating a new skill, refactoring an existing one, or rewriting skill metadata (name, description, allowed-tools).

2026-07-159

ascii-animations

gwenwindflower/dotfiles

Build ASCII/Unicode animations such as loading spinners, logo reveals, particle effects, and terminal art. Covers character grids, frame loops, per-character state machines, ordering, and performance. Use when designing any character-based visual animation.

2026-07-159

blacksmith-testbox

gwenwindflower/dotfiles

Run tests, builds, migrations, or any command needing real CI secrets/services on Blacksmith. Use when testing or validating code, or before any commit or push that should be verified against CI.

2026-07-159

bun-development

gwenwindflower/dotfiles

Use when editing files in a Bun project (bun.lock or bun.lockb at the root, a packageManager field set to bun in package.json, or imports from the bun namespace) or running bun/bunx commands. Covers Bun-native APIs, the bun test runner, bun build --compile, and the Bun-optimized tsconfig.

2026-07-159

capture-context

gwenwindflower/dotfiles

End-of-session capture of state changes, novel learnings, and durable preferences into project context files. Use when the user runs `/capture-context`, says "capture context" / "update the docs", or when wrapping a session that introduced non-trivial deps, architecture changes, or explicit "remember this" callouts.

2026-07-159

name	agent-context-engineering
description	Author and maintain agent context markdown — AGENTS.md, rules, skills, memory files. Use when creating, editing, or refactoring any agent-focused doc, or after major codebase exploration to capture learning.

Agent Context Docs

Every line is loaded on every trigger. If it doesn't change agent behavior, cut it.

[!NOTE] AGENTS.md and .agents/ are both real and stand-ins. They're the shared cross-agent standard adopted by most non-Claude tools, and the generic model for agent-specific equivalents (CLAUDE.md, GEMINI.md, .codex/, etc.). Guidance here applies to all of them.

Principles

Specific and actionable. "Use 2-space indentation in TypeScript" beats "format code properly."
Progressive disclosure. Minimal root file; modular detail loaded on demand.
No redundancy. Don't repeat README, package.json, or anything inferable from code.
Living document. Update after significant exploration to prevent re-crawling.

Authoring AGENTS.md

Include only what an agent can't infer from the code:

1–2 sentence project context (what it is, primary stack)
Goals, priorities, non-goals
Project structure — key directories and their purpose (high token value, prevents repeated fd/tree)
Key commands (build, test, lint) when non-obvious
Architecture: non-obvious patterns, key abstractions, data flow
Conventions that diverge from defaults

Exclude generic language idioms, README content, and vague directives ("write clean code").

Index Pattern

The recommended progressive-disclosure approach:

Put modular docs in docs/ with descriptive filenames (adding-shadcn-components.md)
List them as a tight index in AGENTS.md — plain paths, not @-imports

# Shopping App Agent Guidance

docs/adding-shadcn-components.md
docs/using-drizzle-with-supabase.md
docs/adding-v2-api-endpoints.md

The agent picks what to load. For projects with clear splits (frontend/backend), scope subdirectory indexes:

src/frontend/AGENTS.md → src/frontend/docs/...
src/backend/AGENTS.md  → src/backend/docs/...

Rules vs. docs

Type	Purpose	Scope
Rule	How something should be done, always (workflow, conventions)	User-level if global, project-level if specific
Doc	State of something / how it works (API, architecture)	Skill if cross-project, `docs/` if project-specific

Patterns to Avoid

@reference imports. Most agents inline them fully on encounter. Treat as inlined content; recursive loading (Claude Code: depth 5) compounds bloat.
Rules directories. All files load at session start — equivalent to @-importing every file. Reserve for genuinely universal rules.
Path-scoped frontmatter globs. Better than global, but still automatic rather than agent-driven.

Living Document Workflow

After significant work, update AGENTS.md with new structure, patterns, or decisions. Universally relevant → root; area-specific → docs/ with index entry.

Refactoring Overgrown Files

For AGENTS.md past ~60 lines or with poor structure:

Eliminate conflicting or redundant instructions
Group remaining content by function or path
Move detail into docs/ files; add index entries
Justify each remaining line: does every agent in this directory need it every session?

File Locations

Location	Shared With	Loaded
`AGENTS.md` / `.agents/AGENTS.md`	Team (tracked)	Always
`.agents/rules/*.md`	Team (tracked)	Always
`AGENTS.local.md`	User (untracked)	Always
`~/.agents/AGENTS.md`	User (all projects)	Always
`~/.agents/*`	User (all projects)	Varies by agent

MCP Tool References

Use fully qualified names: ServerName:tool_name (e.g., BigQuery:bigquery_schema). Bare tool names may not resolve when many MCP servers are connected.