blog: guiding your agents

.agents/skills/blog-post-feedback/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: blog-post-feedback
+description: "Provides writing coaching and feedback for blog posts. Helps improve clarity, grammar, structure, and flow while preserving the author's voice. Use when reviewing blog post content with the author."
+---
+
+# Blog Post Feedback
+
+Provides iterative writing coaching for blog posts. The agent acts as a helpful editor and writing coach, NOT a content writer—preserving the author's voice, style, and creative vision is essential.
+
+## Core Principle
+
+**The author writes the content; the agent coaches from the sidelines.**
+
+## Agent Responsibilities
+
+Offer suggestions to improve:
+- **Clarity and understandability** – Is the idea clear to readers?
+- **Grammar and punctuation** – Fix errors without changing voice
+- **Structure and flow** – Organization, pacing, transitions, logical progression
+- **Readability and conciseness** – Remove unnecessary words, simplify
+
+Additional coaching:
+- Suggest ways to improve transitions between ideas
+- Ask clarifying questions to help strengthen ideas
+- Point out inconsistencies, unclear passages, or confusing areas
+- Act as a sounding board for ideas and structure
+- Suggest reorganization or rephrasing for better impact (with author approval)
+
+## What the Agent MUST NOT Do
+
+- **NEVER** write new content or paragraphs
+- **NEVER** suggest rewrites (they introduce AI-generated language and change voice)
+- **NEVER** rewrite passages to add new information or ideas
+- **NEVER** change tone or voice without explicit discussion and approval
+- **NEVER** edit blog files without explicit permission
+- **NEVER** make assumptions about what the author meant
+
+## Feedback Workflow
+
+1. **Author updates the blog post**
+2. **Author requests feedback** on specific areas or the whole post
+3. **Agent re-reads relevant sections** to understand the latest version
+4. **Agent provides suggestions** on clarity, flow, structure, grammar without writing new content
+5. **Author updates the file** based on feedback they find helpful
+6. **Repeat** as needed
+
+Keep re-reads focused—only read necessary lines to reduce token usage while maintaining context.

AGENTS.md

@@ -1,70 +1,17 @@
 # AGENTS
 
-## General Guidelines
-- Always work from the repository root when running commands.
-- The project uses Astro; use the existing npm scripts for development, build, and preview workflows.
-- Avoid modifying files outside the repo unless explicitly requested.
+## Guidelines
 
-## Accuracy and Interaction Guidelines
-- If the user asks to “re-read” a specific line/section, **always** call the `Read` tool on the relevant range before responding.
-- Do not claim “it currently says …” (or similar) unless you have re-read the file in the current thread.
+### Always Do (No Asking)
 
-## Blog Post Editing Guidelines
+- Work from the repository root when running commands.
+- Use `just` recipes for running development commands.
+- Re-read relevant sections when the user asks to "re-read" a specific line/section.
 
-### Core Principle
-**The author writes the content; the agent coaches from the sidelines.** The agent is a helpful editor and writing coach, NOT a content writer. Preserving the author's voice, style, and creative vision is absolutely essential.
+### Ask First (Pause for Approval)
 
-### Agent Responsibilities
-- Offer suggestions and tips to improve:
-  - Clarity and understandability
-  - Grammar and punctuation
-  - Structure and flow (organization, pacing, transitions, logical progression)
-  - Readability and conciseness
-- Suggest ways to improve flow and transitions between ideas
-- Ask clarifying questions to help the author strengthen their ideas
-- Suggest reorganization or rephrasing for better impact
-- Point out inconsistencies, unclear passages, or areas that might confuse readers
-- Act as a sounding board for ideas and structure
-- Surprise the author with occasional on-point jokes related to the content
+- Any changes that might alter tone or voice of content.
 
-### What the Agent MUST NOT Do
-- **NEVER** write new content or paragraphs for the author
-- **NEVER** suggest rewrites (even if explicitly requested) since they introduce AI-generated language
-- **NEVER** rewrite passages to add new information or ideas
-- **NEVER** change the author's voice or tone without explicit discussion
-- **NEVER** edit blog files without explicit permission
-- **NEVER** make assumptions about what the author meant to say
+### Never Do (Hard Stop)
 
-### When the Agent Can Edit
-Only when ALL of the following are true:
-1. The author has explicitly given permission for a specific change
-2. The change has been discussed and agreed upon together
-3. The edit improves wording, structure, or formatting
-4. **NO new content is introduced by the agent**
-5. The author's original meaning and voice are preserved
-
-### Examples of Allowed Edits
-- ✅ Fixing grammar, spelling, or punctuation
-- ✅ Restructuring paragraphs for better flow (author approved)
-- ✅ Removing redundant sentences (author approved)
-- ✅ Improving clarity by rewording existing ideas (author approved)
-- ✅ Formatting adjustments (lists, headings, etc.)
-
-### Examples of NOT Allowed
-- ❌ Writing new sentences or paragraphs
-- ❌ Adding examples or details not discussed
-- ❌ Changing tone or voice without explicit permission
-- ❌ Reinterpreting the author's ideas
-- ❌ Making edits without explicit discussion first
-
-### Feedback Workflow
-The iterative editing process works as follows:
-
-1. **Author makes a change** - Author updates the blog post file
-2. **Author asks for feedback** - Author requests feedback on specific areas or the whole post
-3. **Agent re-reads file** - Agent reads the relevant sections (or full file) to provide current feedback. Re-reading is important to understand the latest version and provide accurate suggestions.
-4. **Agent gives feedback and suggestions** - Agent provides tips on clarity, flow, structure, grammar, or other improvements without writing new content
-5. **Author makes changes** - Author updates the file based on feedback they find helpful
-6. **Repeat** - Cycle returns to step 2 as needed
-
-The agent should re-read only the necessary lines to reduce token usage while maintaining context of the changes.
+- Modify files outside the repository.

justfile

@@ -7,5 +7,5 @@ deps:
 	npm install
 
 # Run development server
-dev:
+run:
 	npm run dev

src/content/docs/blog/guiding-your-agents.md

@@ -0,0 +1,43 @@
+---
+title: Guiding Your Agents
+date: 2026-03-16
+authors:
+  name: Addison Emig
+  title: Lead Software Engineer
+  picture: https://avatars.githubusercontent.com/u/17209828?s=200
+---
+
+`AGENTS.md` files are a great way to persist long-term "memory" for your coding agents. However, it's easy for them to become bloated and/or outdated. A [recent study](https://arxiv.org/abs/2602.11988) has shown this is actually worse than having no `AGENTS.md` at all.
+
+## Best Practices
+
+### Avoid Summarizing the Codebase
+
+There is no need to list your tech stack, file structure, or list of [`just`](/blog/just-is-just-great) recipes in your `AGENTS.md`. This is redundant and can be harmful to your agents' effectiveness when this information becomes outdated. Modern coding agents can quickly figure out the essential details of your codebase for themselves. If you put these details in your `AGENTS.md` file, you are wasting context space and putting yourself at a high risk of documentation rot - when you update your tech stack or file structure, will you remember to also update `AGENTS.md`?
+
+### Focus on Guidelines
+
+In our experience, the best usage of `AGENTS.md` is for recording guidelines that help your coding agents stay on the right path. Think of it as building some guardrails for your agents. When your agents make mistakes, be sure to update the guidelines to help point them in the right direction for future work.
+
+#### Three-tier System
+
+We've found that the following [three-tier system](https://addyosmani.com/blog/good-spec/#:~:text=Use%20three%2Dtier%20boundaries) works well for organizing agent guidelines:
+
+- Always Do (no asking)
+  - A list of things the agent is allowed to do (and **must do**) without asking.
+- Ask First (pause for approval)
+  - A list of things the agent should pause and ask for permission for.
+- Never Do (hard stop)
+  - A list of things the agent **should never** do.
+
+### Long Term Memory
+
+Sometimes you need to record facts that don't fit well into the three-tier guidelines system. For these, it works well to add a **Long Term Memory** section to your `AGENTS.md`. Be careful to prune this list frequently. Often your agent will want to add items here that provide no value for future situations.
+
+### Use Skills Wherever Possible
+
+It's easy for your `AGENTS.md` to become polluted with information related to specific workflows or tasks (for example, running automated tests or accessing GitLab issues). [Agent Skills](https://agentskills.io) are a much better fit for this. Whenever possible, move non-essential information from `AGENTS.md` to your skill files.
+
+## Summary
+
+In general, be very strict about what is in your `AGENTS.md` file. It takes up valuable context space and biases every coding agent session. Be sure that your guidelines provide positive benefits with useful guardrails rather than redundant or outdated documentation.