From 8fa188659c5f102894807854bed9d2eee4a711f4 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Mon, 24 Aug 2026 15:16:59 +0100 Subject: [PATCH] feat: add initial retro skill and OpenAI agent configuration --- skills/in-progress/retro/SKILL.md | 43 +++++++++++++++++++++ skills/in-progress/retro/agents/openai.yaml | 5 +++ 2 files changed, 48 insertions(+) create mode 100644 skills/in-progress/retro/SKILL.md create mode 100644 skills/in-progress/retro/agents/openai.yaml diff --git a/skills/in-progress/retro/SKILL.md b/skills/in-progress/retro/SKILL.md new file mode 100644 index 0000000..d0733cd --- /dev/null +++ b/skills/in-progress/retro/SKILL.md @@ -0,0 +1,43 @@ +--- +name: retro +description: "STUB — not functional. Raw design ideas for a retrospective skill, awaiting a /writing-for-agents pass." +disable-model-invocation: true +--- + +The user has asked for a **retrospective**. You are suggesting improvements to the coding agent's **environment** to improve future runs. + +## Steps + +1. Call the Skill tool with `writing-for-agents` for the writing style guide. + +2. Read the primary sources for the session the user specifies. This may mean searching through session logs on this machine. If the user doesn't specify a session, default to the current one. + +3. Look for candidates for improvement in these categories. + +- **Navigation**: how easy was it for the agent to find the right files? Are there hidden dependencies between files? Would a **navigation pointer** make it easier? _Use when_ the session took a long time to find a piece of information. +- **Automated checks**: are there automated checks that could catch errors the agent made? Linting, typing, tests, filesystem linters? _Use when_ the agent made a mistake that could have been caught by an automated check. +- **Coding standards**: should the **reviewer agent** be given a new rule to enforce? Should an existing rule be removed or clarified? _Use when_ the reviewer agent failed to catch a mistake. +- **Global AGENTS.md**: are there any steering instructions that should be moved to coding standards (or automated checks) instead? _Use when_ the AGENTS.md file is particularly large - in the repo OR the user's global scope. +- **Tool economy**: did the agent make expensive tool calls that could be streamlined? Is there any custom tooling (CLI's, MCP's) that is particularly token-inefficient? _Use when_ the agent made an expensive tool call. +- **No-ops**: look for instructions in steering files that don't modify the agent's behavior. _Use when_ the steering files are large and unwieldy. + +4. Present these candidates to the user, in order of severity. + +## Reference + +### Implementation vs Review + +Remember that all work goes through two stages: implementation and review. The implementation agent has the most **context pressure**. They are responsible for exploration, writing code, and debugging failures. + +The review agent has the least context pressure - it receives a diff, so no exploration needed. It often does not need to write code or debug. + +This means that the review agent should be responsible for imposing coding standards, not the implementation agent. + +### Files + +You have access to several files in the repo: + +- `CLAUDE.md`/`AGENTS.md`: these files are pushed to the context window of any agent working in this repo. They should be used incredibly sparingly, usually only for **navigation pointers** to other files. +- `CODING_STANDARDS.md`: this file is read during review, not implementation. Add **navigation pointers** to docs folders if the standards file gets more than 1,000 lines long. +- Docs: use docs as references files, pointed to by other files. Look for existing docs before writing new ones. +- Skills: use skills for docs (since their description goes into the agent's context window), or for user-invoked commands. Follow the advice in the `writing-for-agents` skill. diff --git a/skills/in-progress/retro/agents/openai.yaml b/skills/in-progress/retro/agents/openai.yaml new file mode 100644 index 0000000..be605ed --- /dev/null +++ b/skills/in-progress/retro/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Retro (stub)" + short_description: "Not functional yet — design ideas only" +policy: + allow_implicit_invocation: false