Automatically check and update folder-specific AGENTS.md during research. Before investigating a domain, read nearest AGENTS.md for existing context. After discovering valuable patterns, append learnings to that file.
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.
A direct command skips the review prompt. Inspect the source before running it.
Automatically check and update folder-specific AGENTS.md during research. Before investigating a domain, read nearest AGENTS.md for existing context. After discovering valuable patterns, append learnings to that file.
allowed-tools
Read Edit Glob
Research Compound
Compound learnings into folder-specific AGENTS.md files during research work.
Trigger Conditions
Activate this behavior when:
Investigating a specific domain (jobs, models, services, controllers, etc.)
Using research agents (repo-analyst, docs-researcher, etc.)
Reading multiple files in the same folder hierarchy
User asks to "understand", "investigate", or "research" a subsystem
Pre-Research: Check Existing Context
Before diving into code, find and read the nearest AGENTS.md:
# From target folder, traverse up to find nearest AGENTS.md# Example: researching app/jobs/cash_app/# Check: app/jobs/cash_app/AGENTS.md# app/jobs/AGENTS.md# app/AGENTS.md# AGENTS.md (root)
What to Extract
From existing AGENTS.md, note:
Known patterns and conventions
Documented gotchas
File organization rules
Testing approaches
Previous learnings (avoid re-discovering)
Pre-Research Output
Briefly acknowledge:
Found existing context in app/jobs/AGENTS.md:
- Jobs use Sidekiq with retry configuration
- Naming: *Job suffix required
- Testing: Use perform_inline in specs
Post-Research: Evaluate Learnings
After research, evaluate each discovery:
Worth Recording (YES)
Criteria
Example
Applies to multiple files in domain
"All jobs inherit from ApplicationJob"
Non-obvious convention
"Jobs must call super before custom logic"
Gotcha that caused confusion
"CashApp jobs require merchant_id, not user_id"
Integration pattern
"Jobs trigger webhooks via WebhookService"
Testing insight
"Use freeze_time for scheduled job specs"
Skip Recording (NO)
Criteria
Example
One-off implementation detail
"ProcessPaymentJob has 3 retries"
Already documented
Pattern exists in AGENTS.md
Too specific to single file
"Line 42 has a TODO"
Obvious from code
"Job processes payments"
Update Protocol
Step 1: Locate Target AGENTS.md
Use nearest-wins hierarchy:
If {domain}/AGENTS.md exists → update it
If not, check parent folder
If no AGENTS.md in hierarchy → create at domain level
# Find existing AGENTS.md files
find . -name "AGENTS.md" -type f | head -20
## Gotchas-**Existing gotcha**: Description
-**NEW: Merchant ID required**: CashApp jobs use `merchant_id`, not `user_id` - Example: `app/jobs/cash_app/process_payment_job.rb:15`
Creating New AGENTS.md
If no AGENTS.md exists in the domain hierarchy, create one:
User: "Investigate how background jobs work in this app"
Claude:
1. Target domain: app/jobs/
2. Check for AGENTS.md...
- Found: app/jobs/AGENTS.md
3. Read existing context:
"Jobs use Sidekiq, ApplicationJob base class, *Job suffix"
4. Proceed with research, avoiding re-discovery of known patterns
Example 2: Post-Research Update
After researching app/jobs/cash_app/:
Discovered:
- CashApp jobs require merchant_id (not user_id) ← WORTH RECORDING
- ProcessPaymentJob has 3 retries ← SKIP (too specific)
- All CashApp jobs log to separate channel ← WORTH RECORDING
Update app/jobs/cash_app/AGENTS.md:
## Gotchas
+ - **Merchant ID required**: Use `merchant_id`, not `user_id` for CashApp jobs
+ - Example: `app/jobs/cash_app/process_payment_job.rb:15`
## Patterns
+ - **Separate logging**: CashApp jobs use `CashAppLogger` channel
+ - Example: `app/jobs/cash_app/base_job.rb:8`
Example 3: Creating New AGENTS.md
Researching app/services/webhooks/ (no existing AGENTS.md)
After research, create app/services/webhooks/AGENTS.md:
# Webhooks
## Purpose
Outbound webhook delivery and retry management.
## Patterns
- **Delivery service**: All webhooks go through `WebhookDeliveryService`
- Example: `app/services/webhooks/delivery_service.rb`
- **Payload builders**: Each event type has a `*PayloadBuilder`
- Example: `app/services/webhooks/payment_payload_builder.rb`
## Gotchas
- **Idempotency required**: Webhooks may retry; receivers must handle duplicates
- **Timeout**: 30-second timeout on delivery attempts
Quality Checks
Before updating AGENTS.md, verify:
Learning is generalizable (applies beyond single file)
Not already documented
Concrete enough to act on
Has file reference for examples
Matches existing AGENTS.md style/structure
Best Practices Research
When research requires external best practices (not just codebase analysis), use this methodology.
Research Process
Clarify the query - Identify the technology AND version (ask if not provided)
Search with version specificity - Always include version in queries (e.g., "Rails 8 API authentication" not "Rails authentication")
Use Perplexity MCP (mcp__perplexity-ask__perplexity_ask) to search for:
Official documentation for [technology] [version]
"[technology] [version] best practices [current year]"
Well-regarded open source examples
Evaluate sources - Prioritize: official docs > widely-adopted standards > community guides
Note version-specific guidance - Flag when practices apply only to certain versions
Best Practices Output Format
## [Topic] Best Practices### Must Have-**[Practice name]**: [Description]
> "[Direct quote from source]"
-- Source: [Link or reference]
### Recommended-**[Practice name]**: [Description]
### Anti-patterns to Avoid-**[Anti-pattern]**: [Why it's problematic]
### Sources- [All referenced sources with links]
Research Constraints
Research only -- do not implement or write code
Cite everything -- no unsourced recommendations
Note conflicts -- if sources disagree, present both views with trade-offs
