Skip to content

Instantly share code, notes, and snippets.

@ngbrown

ngbrown/create-agents.md

Created April 17, 2026 23:23
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save ngbrown/92979778b8ec973a148a0a65be6cda8c to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save ngbrown/92979778b8ec973a148a0a65be6cda8c to your computer and use it in GitHub Desktop.
Download ZIP
Update and create AGENTS.md
Raw
create-agents.md

Analyze this codebase to generate a new AGENTS.md file in project root for guiding AI coding agents.

Focus on discovering the essential knowledge that would help AI agents be immediately productive in this codebase. Consider aspects like:

  • The "big picture" architecture that requires reading multiple files to understand - major components, service boundaries, data flows, and the "why" behind structural decisions
  • Critical developer workflows (builds, tests, debugging) especially commands that aren't obvious from file inspection alone
  • Project-specific conventions and patterns that differ from common practices
  • Integration points, external dependencies, and cross-component communication patterns

Source existing AI conventions from **/{.github/copilot-instructions.md,AGENT.md,AGENTS.md,CLAUDE.md,.cursorrules,.windsurfrules,.clinerules,.cursor/rules/**,.windsurf/rules/**,.clinerules/**,README.md} (do one glob search).

Guidelines (read more at https://agents.md/):

  • Write concise, actionable instructions (~20-50 lines) using markdown structure
  • Include specific examples from the codebase when describing patterns
  • Avoid generic advice ("write tests", "handle errors") - focus on THIS project's specific approaches
  • Document only discoverable patterns, not aspirational practices
  • Reference key files/directories that exemplify important patterns

Generate AGENTS.md first. After creating it, summarize what was included so the user is aware of the content.

Raw
update-agents.md

Update the existing AGENTS.md in the project root for guiding AI coding agents.

Read the existing AGENTS.md in full BEFORE doing anything else. Understand its structure, sections, and content thoroughly. This is your baseline — everything here is assumed correct unless proven otherwise.

Analyze the codebase to identify ONLY what has changed or is missing compared to the existing AGENTS.md. Focus on the essential aspects that would help AI agents be immediately productive in this codebase, e.g.,:

  • Architecture changes: new/removed components, altered service boundaries or data flows
  • Workflow changes: new build commands, changed test procedures, updated debugging steps
  • Convention changes: new patterns, deprecated practices, renamed files/directories
  • New integration points or external dependencies

Source existing AI conventions from **/{.github/copilot-instructions.md,AGENT.md,AGENTS.md,CLAUDE.md,.cursorrules,.windsurfrules,.clinerules,.cursor/rules/**,.windsurf/rules/**,.clinerules/**,README.md} (do one glob search).

Apply minimal, surgical updates. Follow these guidelines (read more at https://agents.md/):

  • Do NOT rewrite or rephrase sections that are still accurate — leave them exactly as they are
  • Preserve the existing structure, section ordering, and formatting
  • When adding content, place it in the most logical existing section rather than creating new sections
  • Write concise, actionable instructions using markdown structure
  • Include specific examples from the codebase when describing patterns
  • Avoid generic advice ("write tests", "handle errors") - focus on THIS project's specific approaches
  • Document only discoverable patterns, not aspirational practices
  • Reference key files/directories that exemplify important patterns

Apply the updates to AGENTS.md. After updating, summarize what was added, modified, or removed so the user is aware of the changes.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment