fix(skills): comprehensive README requirements for polish agent

6e2e1b3c982b892fe40f7869a00b8cc98cf6c9d5 · 2026-04-04 16:03:57 -0700 · Trevin Chow

The agent was guessing flag names (--start-time instead of --start),
leaving HTML placeholders unfilled, and skipping auth/config docs.

New instructions:
- Cardinal rule: run --help for EVERY command before putting it in README
- Fill or remove all <!-- --> placeholders
- 12 required sections with specific content requirements (title, auth,
  quick start, commands, cookbook with verified flags, config env vars)
- 4 optional sections at agent's discretion
- Cookbook must use verified flag names, not guesses

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Files touched

M agents/polish-worker.md

Diff

commit 6e2e1b3c982b892fe40f7869a00b8cc98cf6c9d5
Author: Trevin Chow <trevin@trevinchow.com>
Date:   Sat Apr 4 16:03:57 2026 -0700

    fix(skills): comprehensive README requirements for polish agent
    
    The agent was guessing flag names (--start-time instead of --start),
    leaving HTML placeholders unfilled, and skipping auth/config docs.
    
    New instructions:
    - Cardinal rule: run --help for EVERY command before putting it in README
    - Fill or remove all <!-- --> placeholders
    - 12 required sections with specific content requirements (title, auth,
      quick start, commands, cookbook with verified flags, config env vars)
    - 4 optional sections at agent's discretion
    - Cookbook must use verified flag names, not guesses
    
    Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 agents/polish-worker.md | 59 +++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 47 insertions(+), 12 deletions(-)

diff --git a/agents/polish-worker.md b/agents/polish-worker.md
index ad16f71d..d91b8820 100644
--- a/agents/polish-worker.md
+++ b/agents/polish-worker.md
@@ -107,18 +107,53 @@ For each command that fails verify dry-run or exec:
 
 ### Priority 4: README
 
-If README uses template placeholders or generic examples, rewrite with:
-- Title matching CLI name
-- One-line description matching root Short
-- Install section
-- Quick Start with the commands someone will actually use first. Pick
-  commands that are both **most useful** (what you'd run daily) and
-  **show the CLI's value** (why install this over curl). Usually:
-  `doctor` → `sync` → a transcendence command like `today` or `health`
-  → `search`. Avoid raw list commands as the first example — they dump
-  data without demonstrating why the CLI exists.
-- Command list by category
-- Output format section
+**Cardinal rule: run `<cli> <cmd> --help` for EVERY command you put in the
+README.** Never guess flag names, argument formats, or valid values. If you
+write `--start-time` but the flag is `--start`, the README is wrong and
+users will get errors on their first try.
+
+**Fill or remove all `<!-- ... -->` HTML comment placeholders.** Replace
+`<!-- HELP_OUTPUT -->` with real `--help` output (or remove the section).
+Replace `<!-- DOCTOR_OUTPUT -->` with real `doctor` output. Empty
+placeholders signal an unfinished product.
+
+#### Required sections (must be present and correct)
+
+1. **Title**: "# <Product Name> CLI" — use the product's real name with
+   correct casing/punctuation (e.g., "Cal.com" not "Cal Com")
+2. **Subtitle**: one sentence describing what the CLI does for the user,
+   matching the root `Short` field. NOT a description of the API.
+3. **Install**: correct install command. Use the printing-press-library
+   repo URL, not a per-CLI repo that doesn't exist.
+4. **Authentication**: how to set `<API>_API_KEY` env var, where to get
+   a key (link to the provider's settings page), self-hosted URL override
+   if supported. Read `config.go` to find all env vars.
+5. **Quick Start**: 3-5 commands someone will actually run first. Pick
+   commands that are both **most useful** (what you'd run daily) and
+   **show the CLI's value** (why install this over curl). Usually:
+   `doctor` → `sync` → transcendence command (`today`, `health`) →
+   `search`. Avoid raw list commands — they dump data without
+   demonstrating why the CLI exists.
+6. **Commands**: categorized table. Group by domain function (Scheduling,
+   Analytics, Account, Utilities), not by implementation structure.
+7. **Output Formats**: show `--json`, `--select`, `--csv`, `--compact`,
+   `--dry-run`, `--agent`. Use a real command, not a placeholder.
+8. **Agent Usage**: agent-native properties and exit codes.
+9. **Cookbook**: 8-15 recipes using **verified flag names** from `--help`.
+   Show the CLI's unique capabilities: transcendence commands, filters,
+   SQL queries, pipes. Include at least one mutation example.
+10. **Health Check**: show actual `doctor` output, not a placeholder.
+11. **Configuration**: list ALL env vars from config.go with descriptions.
+    Include config file path.
+12. **Troubleshooting**: common errors mapped to exit codes with fixes.
+
+#### Optional sections (add at your discretion)
+
+- **Rate Limits**: if the API has documented limits
+- **Self-Hosting**: if the CLI supports `--api-url` or `BASE_URL` override
+- **Pagination**: if the API has notable pagination behavior
+- **Sources & Inspiration**: credits to community projects (generated by
+  the machine, preserve if present)
 
 ### Priority 5: Remaining dogfood issues

← afcd3bd6 fix(skills): polish agent picks useful Quick Start commands, · back to Cli Printing Press · fix(cli): dogfood uses cobra Use: fields and recursive help b80d3140 →