feat(skills): add API/HAR input and data-layer scorecard to create-cli

[gupsammy]

Summary

• feat(skills): add API/HAR input and data-layer scorecard to create-cli

Changes

• .claude-plugin/marketplace.json
• README.md
• plugins/claude-skills/.claude-plugin/plugin.json
• plugins/claude-skills/README.md
• plugins/claude-skills/skills/create-cli/SKILL.md
• plugins/claude-skills/skills/create-cli/references/cli-guidelines.md

Commits

• 3bec4a8 feat(skills): add API/HAR input and data-layer scorecard to create-cli

Diff Stat

.claude-plugin/marketplace.json                    |  2 +-
 README.md                                          |  2 +-
 plugins/claude-skills/.claude-plugin/plugin.json   |  2 +-
 plugins/claude-skills/README.md                    |  2 +-
 plugins/claude-skills/skills/create-cli/SKILL.md   | 21 +++++-
 .../skills/create-cli/references/cli-guidelines.md | 81 ++++++++++++++++++++--
 6 files changed, 100 insertions(+), 10 deletions(-)

[claude]

Claude finished @gupsammy's task in 2m 45s —— View job

---

PR Review

• Gather context and fetch diff
• Read changed files
• Review SKILL.md changes
• Review manifest version sync
• Post review findings

---

What looks good

• Version sync is correct. All four locations bumped consistently: plugins/claude-skills/.claude-plugin/plugin.json, .claude-plugin/marketplace.json, plugins/claude-skills/README.md, and root README.md all move from 0.5.26 → 0.5.27. ✓
• Section cross-references match. SKILL.md references cli-guidelines.md → Wrapping an existing API, cli-guidelines.md → Stateful CLIs, and cli-guidelines.md → Agent Ergonomics — all resolve to real section headers in this PR. ✓
• HAR security guidance is solid. The five non-negotiable checks (secrets, auth model, coverage, fragility, ToS/legal) are comprehensive and security-conscious. ✓
• Data Layer Decision scorecard is well-structured. The signal/weight table with clear decision rules (GATE on signal 5, STRONG on signal 3) is actionable and unambiguous. ✓
• $CLAUDE_PLUGIN_ROOT path refs are correct throughout SKILL.md. ✓
• Commit message follows convention (feat(skills): scope). ✓
• No Python changes — stdlib/WAL/RETURNING rules don't apply here.

---

Must fix before merge

1. Phase 3 Errors in SKILL.md is out of sync with the new exit codes table

SKILL.md line 85 (unchanged in this PR, but now inconsistent with what was added):

- Exit codes: `0` success, `1` runtime error, `2` invalid usage; add command-specific codes only when genuinely useful.

cli-guidelines.md → Exit codes (typed) (added in this PR) now recommends a fixed table (3 not-found, 4 auth, 5 upstream, 7 conflict) applied identically across all subcommands for agent/mixed consumers. The SKILL.md Phase 3 summary still says "only when genuinely useful", which contradicts the prescriptive guidance in the reference doc. Agents following Phase 3 literally will skip the table.

Suggested fix for plugins/claude-skills/skills/create-cli/SKILL.md line 85:

- Exit codes: `0` success, `1` runtime error, `2` invalid usage; for agent/mixed consumers, extend with the typed table from cli-guidelines.md → Exit codes (typed) (`3` not-found, `4` auth, `5` upstream, `7` conflict) — apply identically across all subcommands so agents branch on the code.

Fix this →

---

Optional suggestions

2. Exit code 6 is silently skipped (inline comment posted)

cli-guidelines.md line 279 — the typed table goes 3, 4, 5, 7 with no mention of 6. If 6 is reserved/intentionally excluded, a brief parenthetical prevents readers from treating it as a typo. If unintentional, 6 is a natural slot for timeout/rate-limited (a distinct sub-case of 5 upstream). Inline comment posted on that line.

3. --compact flag not reflected in Phase 3 Flags

cli-guidelines.md → Output defaults adds --compact as an opt-in for high-frequency agent calls. Phase 3 Flags in SKILL.md doesn't mention it. Low priority — it's optional and the reference doc covers it — but worth noting for completeness.

---

[claude]

Exit code 6 is conspicuously absent — the table jumps from 5 → 7. If 6 is deliberately reserved (e.g., to avoid clashing with shell/OS conventions) a brief note here would prevent readers from wondering whether it's a typo. If it's unintentional, 6 could cover timeout or rate-limited (a distinct sub-case of 5).

Suggested change

	of parsing stderr: `3` not-found, `4` auth/permission, `5` upstream/network, `7`
	conflict/precondition. (`6` is reserved; skip it in implementations.) Skip codes that don't apply; never renumber once shipped — the table is

Fix this →

[claude]

Claude finished @gupsammy's task in 1m 38s —— View job

---

Re-review after ce9598f

• Fetch updated diff
• Read SKILL.md changes
• Read cli-guidelines.md changes
• Verify must-fix item resolved (Phase 3 exit codes bullet)
• Verify optional suggestions addressed (code 6, --compact)
• Version sync verified (0.5.28 across all 4 locations)

---

All previous findings resolved ✓

Must-fix (resolved)

Phase 3 exit codes bullet in SKILL.md now reads exactly as suggested — references the typed table (3 not-found, 4 auth, 5 upstream, 7 conflict) and notes that it applies identically across all subcommands for agent/mixed consumers. ✓

Optional suggestions (both addressed)

• cli-guidelines.md Exit codes (typed) now explicitly states `6` is reserved — skip it, eliminating the gap ambiguity. ✓
• SKILL.md Phase 3 Flags now includes the --compact bullet with a cross-reference to cli-guidelines.md → Output defaults. ✓

Version sync is correct — ce9598f incremented from 0.5.27 → 0.5.28, and all four locations agree: plugins/claude-skills/.claude-plugin/plugin.json, .claude-plugin/marketplace.json, plugins/claude-skills/README.md, root README.md. ✓

---

PR is ready to merge.