// This skill should be used when the user asks to "update readme", "review readme", "refresh readme", "audit readme", "fix the main readme", "改 readme", "檢查 readme", or when the root README.md needs to reflect new plugin changes, version bumps, or feature additions.
| name | readme-refresh |
| description | This skill should be used when the user asks to "update readme", "review readme", "refresh readme", "audit readme", "fix the main readme", "改 readme", "檢查 readme", or when the root README.md needs to reflect new plugin changes, version bumps, or feature additions. |
Audit and update the marketplace README.md to maximize value for prospective users while keeping internal details out.
The README is a storefront, not a technical spec. Every section must answer one question: "Why should a dbt developer install this?"
Read the root README.md and gather context:
plugin.json for current version and descriptionEvaluate every section using the value audit checklist in references/audit-checklist.md. Flag sections that fail any check.
Present findings as a structured report:
## README Audit
| Section | Status | Issue |
|---------|--------|-------|
| Intro | PASS | — |
| Plugins table | WARN | Lists internal plugin visible to public |
| recce details | FAIL | Exposes agent names, MCP port numbers |
| Requirements | FAIL | Lists Recce prereqs, not plugin prereqs |
Proposed changes:
1. Remove recce-dev from plugins table
2. Replace implementation details with user-facing behavior
3. ...
GATE — Wait for user confirmation before editing.
Apply the writing principles from references/audit-checklist.md:
After editing, re-run the audit checklist to confirm all sections pass. Read the final README end-to-end and check:
| Pattern | Why it's wrong | Fix |
|---|---|---|
| Listing agent/hook/script names | Users don't invoke these directly | Describe the behavior they enable |
| Hardcoding MCP tool list | Tools change across Recce versions | Link to Recce docs |
| Documenting Installation Scopes | Generic Claude Code knowledge | Remove or link to Claude Code docs |
| Mixing product prereqs with plugin prereqs | Confuses what to install | Plugin needs Recce; Recce needs Python/dbt — link to Recce install guide |
| Internal plugins in public README | Noise for external visitors | Move to CLAUDE.md or plugin's own README |
| Troubleshooting with implementation details | Couples README to internals | Keep plugin-level issues only, link elsewhere for product issues |
| Fabricating version pins | Cannot be verified, erodes trust | Describe capability requirement instead; link to install guide |
references/audit-checklist.md — Section-by-section audit criteria and writing principles for value-focused README content.Lightweight pre-commit verification for dbt model changes in the single-environment dev loop — when the user has a warehouse-connected dbt project but no `target-base/` artifacts. Triggers when: user asks to verify a model change, check whether an edit is safe to commit, sanity-check a filter/aggregation/join change without setting up a base environment, or asks for a quick risk read before running /recce-review. Uses Tier-1 evidence only — column lineage, AST analysis, and targeted current-env SQL probes. Routes to /recce-review when `target-base/` is fresh.
Automatically provide Recce guidance in dbt projects. Triggers when: working in dbt project directory, discussing PRs or data changes, after dbt command execution, or when user asks about data validation.
Review dbt model data changes using Recce. Triggers when: user asks to review data changes, check data impact, run recce review, validate model changes before committing, review a Recce Cloud PR session, connect MCP to a cloud session, pastes a GitHub PR / GitLab MR URL, or pastes a Recce Cloud session/launch URL for cloud-mode review.
Use when the user asks to "run eval", "recce eval", "evaluate plugin", "benchmark recce", "compare with plugin", "compare without plugin", "eval case", "score eval", "eval report", "eval history", "list eval scenarios", "list eval cases", "show eval history", "run eval case", or wants to measure the Recce Review Agent's effectiveness compared to pure Claude Code without the plugin.
Use when the user asks to "validate MCP", "run MCP E2E", "run E2E validation", "benchmark MCP performance", "test the plugin flow", "test MCP integration", "compare MCP versions", "show benchmark history", "驗證 MCP", "跑 E2E", "看歷史紀錄", or wants to verify the recce plugin's full event chain works end-to-end and measure agent performance metrics.
Use when generating GitHub Actions workflows for dbt, adding dbt build/test/docs steps, or configuring state-based selection with --select state:modified+. Provides templates for both full builds (CD) and incremental builds (CI).