From 38d2fe1a5e40abdc525fda5d476e98df8ac8aa35 Mon Sep 17 00:00:00 2001 From: letsrokk Date: Sat, 12 Sep 2026 22:09:14 +0200 Subject: [PATCH] docs: clarify descriptions for all plugins --- README.md | 14 +++++++------- plugins/agent-doctor/.claude-plugin/plugin.json | 2 +- plugins/agent-doctor/.codex-plugin/plugin.json | 6 +++--- plugins/agent-doctor/README.md | 2 +- plugins/agent-doctor/plugin.json | 2 +- plugins/code-simplifier/.codex-plugin/plugin.json | 4 ++-- plugins/code-simplifier/README.md | 2 +- plugins/code-simplifier/plugin.json | 2 +- plugins/copywriter/.claude-plugin/plugin.json | 2 +- plugins/copywriter/.codex-plugin/plugin.json | 6 +++--- plugins/copywriter/README.md | 2 +- plugins/copywriter/plugin.json | 2 +- plugins/eli5/.codex-plugin/plugin.json | 6 +++--- plugins/eli5/README.md | 2 +- plugins/eli5/plugin.json | 2 +- plugins/papercuts/.claude-plugin/plugin.json | 2 +- plugins/papercuts/.codex-plugin/plugin.json | 6 +++--- plugins/papercuts/README.md | 2 +- plugins/papercuts/plugin.json | 2 +- .../pr-review-toolkit/.codex-plugin/plugin.json | 6 +++--- plugins/pr-review-toolkit/README.md | 2 +- plugins/pr-review-toolkit/plugin.json | 2 +- plugins/read-the-room/.claude-plugin/plugin.json | 2 +- plugins/read-the-room/.codex-plugin/plugin.json | 6 +++--- plugins/read-the-room/README.md | 2 +- plugins/read-the-room/plugin.json | 2 +- 26 files changed, 45 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index 0d2d2fc..7a131bb 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ Papercuts and Read the Room require Node.js 24 or later on your client’s `PATH #### papercuts ![Codex](assets/agent-badges/codex.svg) ![Claude Code](assets/agent-badges/claude-code.svg) -Keep a local record of the tool failures, confusing instructions, and recurring snags your agent encounters, so they are available to review later. +Keep a local record of tool failures, confusing instructions, and recurring workflow problems. Review what keeps getting in the way and track which issues have been resolved. Codex: @@ -44,7 +44,7 @@ Claude: #### agent-doctor ![Codex](assets/agent-badges/codex.svg) ![Claude Code](assets/agent-badges/claude-code.svg) -Make sense of your agent’s settings and see which plugins and skills it actually uses. Inspect configuration and local session history without changing your files. +Understand your agent’s settings and inspect plugin and skill usage in local Codex and Claude Code sessions. Get a report with suggested fixes without changing your files. Codex: @@ -60,7 +60,7 @@ Claude: #### read-the-room ![Codex](assets/agent-badges/codex.svg) ![Claude Code](assets/agent-badges/claude-code.svg) -Help your agent write for the person reading: clear updates, useful reviews, readable documentation, and chat messages that get to the point. +Help your agent write clear updates, reviews, documentation, and chat messages suited to the reader. Preserve the facts, uncertainty, and detail people need. Codex: @@ -76,7 +76,7 @@ Claude: #### copywriter ![Codex](assets/agent-badges/codex.svg) ![Claude Code](assets/agent-badges/claude-code.svg) -Turn source material into clear, engaging taglines, READMEs, landing pages, editable pitch decks, illustrated articles, and social posts. +Turn your source material into clear, engaging product copy, editable pitch decks, articles, and social posts. Articles and social posts start from your draft, outline, or notes. Codex: @@ -94,7 +94,7 @@ Claude: #### eli5 ![Codex](assets/agent-badges/codex.svg) -Make an unfamiliar topic easier to grasp with big visuals and a few well-chosen words. +Make unfamiliar topics easier to understand with a concrete analogy, simple visuals, and few words. Codex: @@ -104,7 +104,7 @@ codex plugin add eli5@rokk-club-codex-plugins #### pr-review-toolkit ![Codex](assets/agent-badges/codex.svg) -Get actionable reviews of pull requests and local changes, covering bugs, tests, comments, error handling, and types. Reviews are advisory; code simplification needs an explicit request. +Review pull requests and local changes for bugs, gaps in test coverage, unclear comments, and error-handling and type issues. Get actionable findings; code simplification requires an explicit request. Codex: @@ -114,7 +114,7 @@ codex plugin add pr-review-toolkit@rokk-club-codex-plugins #### code-simplifier ![Codex](assets/agent-badges/codex.svg) -Make the code you choose easier to read and maintain while preserving what it does. +Make the code you choose easier to read and maintain while preserving its behavior. Codex: diff --git a/plugins/agent-doctor/.claude-plugin/plugin.json b/plugins/agent-doctor/.claude-plugin/plugin.json index 464f519..8174458 100644 --- a/plugins/agent-doctor/.claude-plugin/plugin.json +++ b/plugins/agent-doctor/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agent-doctor", "version": "0.2.0", - "description": "Inspect and troubleshoot Codex and Claude configuration, plugin usage, and agent problems.", + "description": "Understand your agent's configuration and inspect plugin and skill usage in local Codex and Claude Code sessions.", "author": { "name": "Rokk Club", "url": "https://github.com/letsrokk" diff --git a/plugins/agent-doctor/.codex-plugin/plugin.json b/plugins/agent-doctor/.codex-plugin/plugin.json index 48a9581..164cab0 100644 --- a/plugins/agent-doctor/.codex-plugin/plugin.json +++ b/plugins/agent-doctor/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "agent-doctor", "version": "0.2.0", - "description": "Inspect and troubleshoot Codex and Claude configuration, plugin usage, and agent problems.", + "description": "Understand your agent's configuration and inspect plugin and skill usage in local Codex and Claude Code sessions.", "author": { "name": "Rokk Club", "url": "https://github.com/letsrokk" @@ -20,8 +20,8 @@ "skills": "./skills/", "interface": { "displayName": "Agent Doctor", - "shortDescription": "Diagnose agent configuration and usage", - "longDescription": "Inspect Codex and Claude configuration and recent session history to diagnose configuration, plugin usage, and invocation problems.", + "shortDescription": "Understand agent settings and skill usage", + "longDescription": "Inspect Codex and Claude Code settings, instructions, and local session history to report configuration problems and observed plugin and skill usage. Get suggested fixes without changing your files.", "developerName": "Rokk Club", "category": "Developer Tools", "capabilities": [ diff --git a/plugins/agent-doctor/README.md b/plugins/agent-doctor/README.md index e0ab370..94d968a 100644 --- a/plugins/agent-doctor/README.md +++ b/plugins/agent-doctor/README.md @@ -1,6 +1,6 @@ # Agent Doctor -Inspect Codex and Claude Code configuration and see how often your plugins and skills are used. +Understand your agent's settings and see which plugins and skills it uses in local Codex and Claude Code sessions. ```text $inspect-agent-config audit this project's settings and instructions diff --git a/plugins/agent-doctor/plugin.json b/plugins/agent-doctor/plugin.json index 3a2d235..f5d7704 100644 --- a/plugins/agent-doctor/plugin.json +++ b/plugins/agent-doctor/plugin.json @@ -2,7 +2,7 @@ "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "agent-doctor", "version": "0.2.0", - "description": "Inspect and troubleshoot Codex and Claude configuration, plugin usage, and agent problems.", + "description": "Understand your agent's configuration and inspect plugin and skill usage in local Codex and Claude Code sessions.", "author": { "name": "Rokk Club", "url": "https://github.com/letsrokk" diff --git a/plugins/code-simplifier/.codex-plugin/plugin.json b/plugins/code-simplifier/.codex-plugin/plugin.json index b4a052c..db396e3 100644 --- a/plugins/code-simplifier/.codex-plugin/plugin.json +++ b/plugins/code-simplifier/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "code-simplifier", "version": "0.1.4", - "description": "Simplify a precise code scope without changing observable behavior.", + "description": "Make the code you choose easier to read and maintain while preserving its behavior.", "author": { "name": "Rokk Club", "url": "https://github.com/letsrokk" @@ -19,7 +19,7 @@ "interface": { "displayName": "Code Simplifier", "shortDescription": "Simplify code without changing behavior", - "longDescription": "Resolve a precise code scope, simplify it for clarity and maintainability, and preserve its observable behavior.", + "longDescription": "Simplify the files or changes you specify for clearer, more maintainable code while preserving observable behavior. Get a summary of the edits and verification results.", "developerName": "Rokk Club", "category": "Developer Tools", "capabilities": [ diff --git a/plugins/code-simplifier/README.md b/plugins/code-simplifier/README.md index 614cec5..571efd9 100644 --- a/plugins/code-simplifier/README.md +++ b/plugins/code-simplifier/README.md @@ -1,6 +1,6 @@ # Code Simplifier -Simplify existing code for clarity while preserving its behavior. +Make the code you choose easier to read and maintain while preserving its behavior. ```text $code-simplifier simplify my local changes diff --git a/plugins/code-simplifier/plugin.json b/plugins/code-simplifier/plugin.json index 67f3434..c2fa1e9 100644 --- a/plugins/code-simplifier/plugin.json +++ b/plugins/code-simplifier/plugin.json @@ -2,7 +2,7 @@ "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "code-simplifier", "version": "0.1.4", - "description": "Simplify a precise code scope without changing observable behavior.", + "description": "Make the code you choose easier to read and maintain while preserving its behavior.", "author": { "name": "Rokk Club", "url": "https://github.com/letsrokk" diff --git a/plugins/copywriter/.claude-plugin/plugin.json b/plugins/copywriter/.claude-plugin/plugin.json index 7d2ce30..e0dcd11 100644 --- a/plugins/copywriter/.claude-plugin/plugin.json +++ b/plugins/copywriter/.claude-plugin/plugin.json @@ -1,5 +1,5 @@ { "name": "copywriter", "version": "0.3.0", - "description": "Transform source material into grounded product copy, articles, social posts, and illustrated pitch decks." + "description": "Turn your source material into clear product copy, editable pitch decks, articles, and social posts." } diff --git a/plugins/copywriter/.codex-plugin/plugin.json b/plugins/copywriter/.codex-plugin/plugin.json index 6f95e4f..2878489 100644 --- a/plugins/copywriter/.codex-plugin/plugin.json +++ b/plugins/copywriter/.codex-plugin/plugin.json @@ -1,15 +1,15 @@ { "name": "copywriter", "version": "0.3.0", - "description": "Transform source material into grounded product copy, articles, social posts, and illustrated pitch decks.", + "description": "Turn your source material into clear product copy, editable pitch decks, articles, and social posts.", "skills": "./skills/", "author": { "name": "Rokk Club" }, "interface": { "displayName": "Copywriter", - "shortDescription": "Turn source material into grounded product writing", - "longDescription": "Create taglines, READMEs, local landing pages, editable pitch decks, articles, and social posts from substantive source material.", + "shortDescription": "Shape source material into engaging writing", + "longDescription": "Create taglines, READMEs, local landing pages, editable pitch decks, articles, and social posts from source material. Keep claims supported and use your draft, outline, or notes as the basis for articles and social writing.", "developerName": "Rokk Club", "category": "Productivity", "capabilities": [ diff --git a/plugins/copywriter/README.md b/plugins/copywriter/README.md index b497a21..10a0182 100644 --- a/plugins/copywriter/README.md +++ b/plugins/copywriter/README.md @@ -1,6 +1,6 @@ # Copywriter -Turn substantive source material into clear, well-structured taglines, READMEs, landing pages, editable pitch decks, articles, and social posts. Copywriter prioritizes the argument, wording, voice, and text formatting, with illustrations, diagrams, charts, and deck graphics to support the message. Articles and social posts require your draft, outline, or substantive notes; a topic alone is insufficient. +Turn your source material into clear, engaging taglines, READMEs, landing pages, editable pitch decks, articles, and social posts. Copywriter shapes the argument, wording, and voice, with visuals to support the message. Articles and social posts start from your draft, outline, or substantive notes; a topic alone is not enough. The default voice is warm, engaging, and accessible to the general public, with marketing language used in moderation. Copywriter explains why the subject matters, keeps promises grounded, and adapts to specialist audiences when the task calls for it. All writing skills prefer natural punctuation and avoid em dashes and formulaic agent-style formatting while preserving quotations, code, and explicit author choices. diff --git a/plugins/copywriter/plugin.json b/plugins/copywriter/plugin.json index 758552b..5172398 100644 --- a/plugins/copywriter/plugin.json +++ b/plugins/copywriter/plugin.json @@ -2,7 +2,7 @@ "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "copywriter", "version": "0.3.0", - "description": "Transform source material into grounded product copy, articles, social posts, and illustrated pitch decks.", + "description": "Turn your source material into clear product copy, editable pitch decks, articles, and social posts.", "keywords": [ "copywriting", "readme", diff --git a/plugins/eli5/.codex-plugin/plugin.json b/plugins/eli5/.codex-plugin/plugin.json index a1a2b1e..e462668 100644 --- a/plugins/eli5/.codex-plugin/plugin.json +++ b/plugins/eli5/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "eli5", "version": "0.1.2", - "description": "Explain any topic like I'm 5: a dead-simple visual explainer with big pictures and few words.", + "description": "Make unfamiliar topics easier to understand with a concrete analogy, simple visuals, and few words.", "author": { "name": "Thariq Shihipar" }, @@ -18,8 +18,8 @@ "skills": "./skills/", "interface": { "displayName": "ELI5", - "shortDescription": "Explain topics with big pictures and few words", - "longDescription": "Turn an unfamiliar topic into a dead-simple visual explainer for someone who knows nothing about it.", + "shortDescription": "Understand topics through simple visuals", + "longDescription": "Get a beginner-friendly explanation built around one concrete analogy, a simple visual, and a few well-chosen words. Essential terms are explained and the underlying mechanism stays accurate.", "developerName": "Rokk Club", "category": "Education", "capabilities": [ diff --git a/plugins/eli5/README.md b/plugins/eli5/README.md index aa07a61..6977e5c 100644 --- a/plugins/eli5/README.md +++ b/plugins/eli5/README.md @@ -1,6 +1,6 @@ # eli5 -Explain any topic like I'm 5. +Make unfamiliar topics easier to understand with a concrete analogy, simple visuals, and few words. ```text $eli5 how does DNS work diff --git a/plugins/eli5/plugin.json b/plugins/eli5/plugin.json index ffebb4f..fdc4f15 100644 --- a/plugins/eli5/plugin.json +++ b/plugins/eli5/plugin.json @@ -2,7 +2,7 @@ "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "eli5", "version": "0.1.2", - "description": "Explain any topic like I'm 5: a dead-simple visual explainer with big pictures and few words. Use $eli5 .", + "description": "Make unfamiliar topics easier to understand with a concrete analogy, simple visuals, and few words.", "author": { "name": "Rokk Club", "url": "https://github.com/letsrokk" diff --git a/plugins/papercuts/.claude-plugin/plugin.json b/plugins/papercuts/.claude-plugin/plugin.json index feb606d..9f3c7d2 100644 --- a/plugins/papercuts/.claude-plugin/plugin.json +++ b/plugins/papercuts/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "papercuts", "version": "0.4.4", - "description": "Give Claude Code a durable complaint journal for workflow friction.", + "description": "Keep a local record of tool failures, confusing instructions, and recurring workflow problems for later review.", "author": { "name": "Rokk Club", "url": "https://github.com/letsrokk" diff --git a/plugins/papercuts/.codex-plugin/plugin.json b/plugins/papercuts/.codex-plugin/plugin.json index c66a4a8..253fc98 100644 --- a/plugins/papercuts/.codex-plugin/plugin.json +++ b/plugins/papercuts/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "papercuts", "version": "0.4.4", - "description": "Give Codex a durable complaint journal for workflow friction.", + "description": "Keep a local record of tool failures, confusing instructions, and recurring workflow problems for later review.", "author": { "name": "Rokk Club", "url": "https://github.com/letsrokk" @@ -27,8 +27,8 @@ }, "interface": { "displayName": "Papercuts", - "shortDescription": "Track and resolve workflow friction", - "longDescription": "Record material engineering friction in a durable local journal, then review, resolve, reopen, and explicitly prune it.", + "shortDescription": "Track recurring workflow problems locally", + "longDescription": "Record tool failures, confusing instructions, and other workflow problems in a local journal. Review recurring issues and track which ones have been resolved.", "developerName": "Rokk Club", "category": "Developer Tools", "capabilities": [ diff --git a/plugins/papercuts/README.md b/plugins/papercuts/README.md index 5176fa6..6380513 100644 --- a/plugins/papercuts/README.md +++ b/plugins/papercuts/README.md @@ -1,6 +1,6 @@ # Papercuts -Papercuts gives Codex and Claude Code a durable local journal for material engineering friction. During an engineering task, the shared skill searches open complaints in the active project, votes for a clear match, or lodges a concise new complaint. It then continues the task without announcing routine logging. +Keep a local record of tool failures, confusing instructions, and recurring workflow problems in Codex and Claude Code. During a task, Papercuts records a new issue or adds an encounter to an existing one, then continues without announcing routine logging. Review the journal later to see what keeps getting in the way. The skill records dead-end tool calls, misleading documentation, missing helpers, repeated recovery work, configuration footguns, unclear repository instructions, and failures that consume meaningful time. It excludes expected validation failures, corrected typing mistakes, and ordinary unsuccessful searches unless an interface made the failure predictably misleading. diff --git a/plugins/papercuts/plugin.json b/plugins/papercuts/plugin.json index 0245aa4..e25d0e6 100644 --- a/plugins/papercuts/plugin.json +++ b/plugins/papercuts/plugin.json @@ -1,7 +1,7 @@ { "name": "papercuts", "version": "0.4.4", - "description": "Give coding agents a durable complaint journal for workflow friction.", + "description": "Keep a local record of tool failures, confusing instructions, and recurring workflow problems for later review.", "author": { "name": "Rokk Club", "url": "https://github.com/letsrokk" diff --git a/plugins/pr-review-toolkit/.codex-plugin/plugin.json b/plugins/pr-review-toolkit/.codex-plugin/plugin.json index edca215..c50cfcf 100644 --- a/plugins/pr-review-toolkit/.codex-plugin/plugin.json +++ b/plugins/pr-review-toolkit/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "pr-review-toolkit", "version": "0.1.2", - "description": "Review pull requests and local changes with focused specialist guidance.", + "description": "Review pull requests and local changes for bugs, gaps in test coverage, unclear comments, and error-handling and type issues.", "author": { "name": "Rokk Club", "url": "https://github.com/letsrokk" @@ -19,8 +19,8 @@ "skills": "./skills/", "interface": { "displayName": "PR Review Toolkit", - "shortDescription": "Review changes with focused specialists", - "longDescription": "Review a pull request or local change set for bugs, test coverage, comments, error handling, and type invariants. Simplify code only when requested.", + "shortDescription": "Find bugs and coverage gaps in code changes", + "longDescription": "Get actionable findings with file locations and suggested corrections across code, tests, comments, error handling, and type invariants. Reviews are advisory; code simplification requires an explicit request.", "developerName": "Rokk Club", "category": "Developer Tools", "capabilities": [ diff --git a/plugins/pr-review-toolkit/README.md b/plugins/pr-review-toolkit/README.md index 04ace4a..9d9fdf4 100644 --- a/plugins/pr-review-toolkit/README.md +++ b/plugins/pr-review-toolkit/README.md @@ -1,6 +1,6 @@ # PR Review Toolkit -Review pull requests and local changes for bugs, test coverage, comments, error handling, and type invariants. +Review pull requests and local changes for bugs, gaps in test coverage, unclear comments, and error-handling and type issues. ```text $pr-review-toolkit review my local changes diff --git a/plugins/pr-review-toolkit/plugin.json b/plugins/pr-review-toolkit/plugin.json index 0382516..a15a502 100644 --- a/plugins/pr-review-toolkit/plugin.json +++ b/plugins/pr-review-toolkit/plugin.json @@ -2,7 +2,7 @@ "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "pr-review-toolkit", "version": "0.1.2", - "description": "Review pull requests and local changes with focused specialist guidance.", + "description": "Review pull requests and local changes for bugs, gaps in test coverage, unclear comments, and error-handling and type issues.", "author": { "name": "Rokk Club", "url": "https://github.com/letsrokk" diff --git a/plugins/read-the-room/.claude-plugin/plugin.json b/plugins/read-the-room/.claude-plugin/plugin.json index b47d45b..f8de5f0 100644 --- a/plugins/read-the-room/.claude-plugin/plugin.json +++ b/plugins/read-the-room/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "read-the-room", "version": "0.3.0", - "description": "Help Claude shape clear communication for the human and channel in front of it.", + "description": "Help your agent write clear updates, reviews, documentation, and chat messages suited to the reader.", "author": { "name": "Rokk Club", "url": "https://github.com/letsrokk" diff --git a/plugins/read-the-room/.codex-plugin/plugin.json b/plugins/read-the-room/.codex-plugin/plugin.json index 84295bc..1ab2b50 100644 --- a/plugins/read-the-room/.codex-plugin/plugin.json +++ b/plugins/read-the-room/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "read-the-room", "version": "0.3.0", - "description": "Help Codex shape clear communication for the human and channel in front of it.", + "description": "Help your agent write clear updates, reviews, documentation, and chat messages suited to the reader.", "author": { "name": "Rokk Club", "url": "https://github.com/letsrokk" @@ -19,8 +19,8 @@ "hooks": "./hooks/hooks.json", "interface": { "displayName": "Read the Room", - "shortDescription": "Clear communication shaped for the channel", - "longDescription": "Help agents write direct, useful responses and artifacts for human readers across agent sessions, version control, issue trackers, knowledge bases, and chat applications.", + "shortDescription": "Write clearly for the reader and channel", + "longDescription": "Help your agent adapt its writing to the reader and channel, from session updates and pull requests to issue trackers, documentation, and chat. Preserve facts, uncertainty, and the detail readers need.", "developerName": "Rokk Club", "category": "Productivity", "capabilities": [ diff --git a/plugins/read-the-room/README.md b/plugins/read-the-room/README.md index 4c2b529..5dd2d04 100644 --- a/plugins/read-the-room/README.md +++ b/plugins/read-the-room/README.md @@ -1,6 +1,6 @@ # Read the Room -Help agents shape clear communication for the human and channel in front of them. +Help your agent write clear updates, reviews, documentation, and chat messages suited to the reader. Read the Room packages a shared human-facing communication contract as one portable skill. [`skills/make-it-make-sense/SKILL.md`](skills/make-it-make-sense/SKILL.md) is the canonical policy. Channel references contain only the rules specific to each artifact. diff --git a/plugins/read-the-room/plugin.json b/plugins/read-the-room/plugin.json index 587ca72..2efbf1b 100644 --- a/plugins/read-the-room/plugin.json +++ b/plugins/read-the-room/plugin.json @@ -1,7 +1,7 @@ { "name": "read-the-room", "version": "0.3.0", - "description": "Help agents shape clear communication for the human and channel in front of them.", + "description": "Help your agent write clear updates, reviews, documentation, and chat messages suited to the reader.", "author": { "name": "Rokk Club", "url": "https://github.com/letsrokk"