← back to Cli Printing Press
fix(skill): always research, polish, and score - never skip the brain
4ee089526400c638ef4fd92dbbf889af9e85a180 · 2026-03-25 13:08:58 -0700 · Matt Van Horn
The skill was skipping research, polish, and scoring when an OpenAPI
spec was found (going straight to generate -> done). Now ALL runs get
the full treatment:
- Step 1.5: Research competitors ALWAYS runs (WebSearch, analyze READMEs)
- Step 4: Polish ALWAYS runs (improve help text, examples, README)
- Step 5: Score ALWAYS runs (Steinberger scorecard)
- Step 6: Report ALWAYS includes competitor comparison
Before: /printing-press Notion -> found spec -> generate -> done (dumb)
After: /printing-press Notion -> research competitors -> generate ->
polish -> score -> report with comparison (smart)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Files touched
A docs/plans/2026-03-25-fix-skill-always-research-polish-score-plan.mdM skills/printing-press/SKILL.md
Diff
commit 4ee089526400c638ef4fd92dbbf889af9e85a180
Author: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Date: Wed Mar 25 13:08:58 2026 -0700
fix(skill): always research, polish, and score - never skip the brain
The skill was skipping research, polish, and scoring when an OpenAPI
spec was found (going straight to generate -> done). Now ALL runs get
the full treatment:
- Step 1.5: Research competitors ALWAYS runs (WebSearch, analyze READMEs)
- Step 4: Polish ALWAYS runs (improve help text, examples, README)
- Step 5: Score ALWAYS runs (Steinberger scorecard)
- Step 6: Report ALWAYS includes competitor comparison
Before: /printing-press Notion -> found spec -> generate -> done (dumb)
After: /printing-press Notion -> research competitors -> generate ->
polish -> score -> report with comparison (smart)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
...-fix-skill-always-research-polish-score-plan.md | 88 ++++++++++++++++++++++
skills/printing-press/SKILL.md | 81 +++++++++++++-------
2 files changed, 143 insertions(+), 26 deletions(-)
diff --git a/docs/plans/2026-03-25-fix-skill-always-research-polish-score-plan.md b/docs/plans/2026-03-25-fix-skill-always-research-polish-score-plan.md
new file mode 100644
index 00000000..7c791144
--- /dev/null
+++ b/docs/plans/2026-03-25-fix-skill-always-research-polish-score-plan.md
@@ -0,0 +1,88 @@
+---
+title: "Fix Skill: Always Research, Polish, and Score"
+type: fix
+status: active
+date: 2026-03-25
+---
+
+# Fix: Always Research, Polish, and Score
+
+## The Problem
+
+`/printing-press Notion` found an OpenAPI spec and jumped straight to generate. No research, no competitor analysis, no polish, no scorecard. The skill only does the brain work when there's NO spec. But the brain work should happen EVERY time.
+
+## The Fix
+
+Change the skill flow from:
+
+```
+Found spec? -> YES -> generate -> done (dumb)
+ -> NO -> research -> write spec -> generate -> polish -> score (smart)
+```
+
+To:
+
+```
+Always: research competitors -> find/write spec -> generate -> polish -> score -> report
+```
+
+Every run gets the full brain treatment regardless of how we got the spec.
+
+## What to Change in SKILL.md
+
+### Step 1 stays: Parse intent and find spec
+
+No change. Still search for OpenAPI spec first.
+
+### NEW Step 1.5: Research competitors (ALWAYS runs)
+
+Even when we have an OpenAPI spec, Claude Code should:
+
+```
+WebSearch: "<api-name> cli" site:github.com
+```
+
+For each competitor found:
+- Note name, stars, language, last updated
+- WebFetch their README if < 5 competitors
+- Count their commands
+- Identify what they have that we should match
+
+Report to user: "Found N competing CLIs. Best: X (Y stars). They have Z commands."
+
+### Step 2-3 stay: Write spec or use OpenAPI
+
+No change to spec acquisition.
+
+### Step 4 becomes MANDATORY (was optional): Polish
+
+After generating, Claude Code ALWAYS:
+
+a. Reads the generated `--help` output and checks command count
+b. If help descriptions are jargon-heavy, rewrites them via Edit
+c. If README description is generic spec text, rewrites it
+d. If competitor has features we're missing, notes it in the report
+
+### Step 5 becomes MANDATORY: Score
+
+Always run the scorecard. Always report the grade.
+
+### Step 6 enhanced: Report includes comparison
+
+```
+Generated notion-cli: 7 resources, 20 commands
+Steinberger score: 65/90 (72%, Grade B)
+
+Competitors:
+- 4ier/notion-cli (87 stars, Go) - 15 commands
+- notion-cli (bash, 2025 API) - 12 commands
+
+We beat competitors on: commands (20 vs 15), auth, output formats
+We're missing: database query support (complex body params were skipped)
+```
+
+## Implementation
+
+One file change: `skills/printing-press/SKILL.md`
+
+Move Steps 1.5 (research), 4 (polish), and 5 (score) from conditional to mandatory in ALL workflows.
diff --git a/skills/printing-press/SKILL.md b/skills/printing-press/SKILL.md
index ae0ef2cf..67d371fe 100644
--- a/skills/printing-press/SKILL.md
+++ b/skills/printing-press/SKILL.md
@@ -62,10 +62,30 @@ Extract the API name. Then search for an OpenAPI spec:
3. WebSearch: `"<api-name>" openapi spec site:github.com`
4. Try common URLs: `https://raw.githubusercontent.com/<org>/openapi/main/openapi.yaml`
+**Step 1.5: Research competitors (ALWAYS runs, regardless of spec source)**
+
+This runs EVERY time, even when an OpenAPI spec was found. Claude Code IS the brain.
+
+a. **Search for competing CLIs:**
+```
+WebSearch: "<api-name> cli" site:github.com
+```
+For each competitor found, note: name, stars, language, last updated, URL.
+
+b. **Analyze top competitors (if any found):**
+For the top 1-3 competitors by stars, WebFetch their README and note:
+- What commands they have
+- What auth methods they support
+- What features they highlight
+- What issues/complaints users have (check their GitHub issues if notable)
+
+c. **Report findings before generating:**
+Tell the user: "Found N competing CLIs. Best: X (Y stars, Z commands). Generating a CLI that matches or beats them."
+
If OpenAPI spec found: go to Step 3 (generate from spec).
-If no spec found: go to Step 2 (research and write spec).
+If no spec found: go to Step 2 (research and write spec from docs).
-**Step 2: Research the API and write a spec (Claude Code does this)**
+**Step 2: Write a spec from API docs (only when no OpenAPI spec exists)**
This is where Claude Code IS the brain. No regex. No shelling out to another LLM.
@@ -74,13 +94,7 @@ a. **Fetch the API docs:**
WebFetch the API documentation URL (e.g., developers.notion.com/reference)
```
-b. **Research competitors:**
-```
-WebSearch: "<api-name> cli" site:github.com
-```
-For each competitor found, note: name, stars, language, last updated.
-
-c. **Read the docs and identify EVERY endpoint:**
+b. **Read the docs and identify EVERY endpoint:**
Read the fetched docs content. List every API endpoint you find:
- HTTP method (GET, POST, PUT, PATCH, DELETE)
- Path (/v1/databases, /v1/pages/{id})
@@ -126,25 +140,35 @@ Use `--lenient` for specs with broken $refs (PagerDuty, Intercom).
If all 7 quality gates pass: go to Step 4 (polish).
If gates fail: read error, fix, retry (max 3).
-**Step 4: Polish (Claude Code does this)**
+**Step 4: Polish (ALWAYS runs - Claude Code does this)**
+
+After generating, Claude Code improves the output directly. This is NOT optional.
-Read the generated code and improve it directly:
+a. **Check the generated CLI:**
+```bash
+cd <output> && go build -o <name>-cli ./cmd/*/ && ./<name>-cli --help
+```
+Count commands and resources. Compare against competitors found in Step 1.5.
-a. **Improve help descriptions:**
+b. **Improve help descriptions:**
Read each command file in `<output>/internal/cli/*.go`. Find `Short:` strings. If any are jargon-heavy spec descriptions, use Edit to rewrite them to be developer-friendly (under 80 chars, starts with a verb).
-b. **Improve examples:**
+c. **Improve examples:**
Read each command's `Example:` string. If it uses generic values like "value" or "<id>", use Edit to replace with realistic values (e.g., "usr_abc123", "2026-01-01", "user@example.com").
-c. **Improve README:**
-Read `<output>/README.md`. If the description is generic spec text, use Edit to rewrite:
+d. **Improve README:**
+Read `<output>/README.md`. Rewrite it:
- Add a one-line hook that makes developers want to install it
-- Add "Why This Exists" if there's no official CLI for this API
-- Ensure Quick Start has real 3-command workflow
+- Add "Why This Exists" section (mention that no official CLI exists, if true)
+- If competitors exist, note: "Inspired by X, with Y improvements"
+- Ensure Quick Start has a real 3-command workflow with realistic values
-d. **Note: this step is optional.** If the user doesn't want polish, skip it. If the generated output is already good, skip it. Use judgment.
+e. **Verify polish didn't break anything:**
+```bash
+cd <output> && go build ./... && go vet ./...
+```
-**Step 5: Score (optional)**
+**Step 5: Score (ALWAYS runs)**
Run the Steinberger scorecard:
```bash
@@ -156,13 +180,18 @@ Report the score to the user.
**Step 6: Present result**
-Show:
-1. What was generated (directory, resources, commands)
-2. Example commands to try
-3. How to install: `cd <name>-cli && go install ./cmd/<name>-cli`
-4. Steinberger score if computed
-5. Competitors found (if any)
-6. Note if spec was auto-written vs from OpenAPI
+Show ALL of these:
+1. What was generated (directory, resources, commands, endpoint count)
+2. Steinberger score and grade (ALWAYS - from Step 5)
+3. Competitor comparison (ALWAYS - from Step 1.5):
+ - How many competitors found
+ - Our command count vs best competitor
+ - What we beat them on
+ - What we're missing (if anything)
+4. Example commands to try (use realistic values, not placeholders)
+5. How to install: `cd <name>-cli && go install ./cmd/<name>-cli`
+6. Spec source (OpenAPI URL vs hand-written from docs)
+7. Any limitations (skipped complex body fields, truncated endpoints)
### Workflow 1: From Spec File
← 6e934000 refactor(skill): Claude Code IS the brain, not the Go binary
·
back to Cli Printing Press
·
feat(skill): restore plan-execute-plan-execute loop - the pr 68f63167 →