Skip to content
Back to search

earthspoken

MarketplaceWorks with Claude CodeGitHub

Plain-language Claude Code: clear names instead of cryptic IDs, and progress reports anyone can read.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mina-yousry--earthspoken/badge.svg)](/listings/mina-yousry--earthspoken)

HTML

<a href="/listings/mina-yousry--earthspoken"><img src="/api/listings/mina-yousry--earthspoken/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Inside Claude Code:

/plugin marketplace add mina-yousry/earthspoken
/plugin install earthspoken@earthspoken
/reload-plugins

Or from your terminal:

claude plugin marketplace add mina-yousry/earthspoken
claude plugin install earthspoken@earthspoken

Skills-only edition

[`plugins/earthspoken-lite`](plugins/earthspoken-lite) has the same rules and progress report with no hooks. It's the edition submitted to the Claude directory. The rules load when Claude picks up the skill, not at every session start, and helper agents only get them if Claude passes them on. Install one edition, not both.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 51 lines
  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "earthspoken",
  4. "description": "Plain-language Claude Code: clear names instead of cryptic IDs, and progress reports anyone can read.",
  5. "owner": {
  6. "name": "Mina Yousry",
  7. "url": "https://github.com/mina-yousry"
  8. },
  9. "plugins": [
  10. {
  11. "name": "earthspoken",
  12. "source": "./plugins/earthspoken",
  13. "description": "Makes Claude Code talk like a teammate, not a terminal: clear names, no invented abbreviations, and progress reports a product owner can read in ten seconds.",
  14. "version": "1.2.0",
  15. "author": {
  16. "name": "Mina Yousry"
  17. },
  18. "homepage": "https://github.com/mina-yousry/earthspoken",
  19. "repository": "https://github.com/mina-yousry/earthspoken",
  20. "license": "MIT",
  21. "keywords": [
  22. "communication",
  23. "naming",
  24. "status-report",
  25. "product-owner",
  26. "plain-language"
  27. ],
  28. "category": "productivity"
  29. },
  30. {
  31. "name": "earthspoken-lite",
  32. "source": "./plugins/earthspoken-lite",
  33. "description": "Skills-only edition of Earthspoken (no hooks): clear names and progress reports anyone can read, loaded when Claude picks up the skill.",
  34. "version": "1.1.1",
  35. "author": {
  36. "name": "Mina Yousry"
  37. },
  38. "homepage": "https://github.com/mina-yousry/earthspoken",
  39. "repository": "https://github.com/mina-yousry/earthspoken",
  40. "license": "MIT",
  41. "keywords": [
  42. "communication",
  43. "naming",
  44. "status-report",
  45. "product-owner",
  46. "plain-language"
  47. ],
  48. "category": "productivity"
  49. }
  50. ]
  51. }
README.md · README · 151 lines
  1. # 🌍 Earthspoken
  2. **Plain-language status reports for Claude Code.**
  3. A [Claude Code](https://code.claude.com/docs) plugin that makes Claude talk like a teammate, not a terminal.
  4. No invented IDs, no made-up acronyms. You get clear names, and status updates anyone can read in ten seconds, whether they're a product owner or a developer.
  5. [![Validate](https://github.com/mina-yousry/earthspoken/actions/workflows/validate.yml/badge.svg)](https://github.com/mina-yousry/earthspoken/actions/workflows/validate.yml)
  6. ---
  7. ## Before and after
  8. | Without Earthspoken | With Earthspoken |
  9. |---|---|
  10. | "TC-03 failing, WS-2 blocked on T5." | "Test case 3 (login with wrong password) is failing. The checkout work is blocked until the discount fix is merged." |
  11. | "Spawning agent_7 for phase 2b." | "Starting a helper to fix the discount not applying on the checkout page." |
  12. | "Done. Ready for the next part?" | A short report: Done (and how it was verified), In progress, Blocked (and how to unblock it), Risks, Next up, Decisions needed from you. |
  13. ## What it does
  14. - **🏷️ Clear names, always.** Tasks, plan steps, helper agents and tests get descriptive names you'll recognise later.
  15. It keeps the IDs you and your project already use (ticket keys, your own numbered lists). It also follows your repo's branch and commit conventions.
  16. - **📋 Progress reports anyone can read.** Ask *"where are we?"* or run `/earthspoken:progress` to get:
  17. - ✅ **Done**: described by the result, and whether it was tested, built only, or not verified
  18. - 🔄 **In progress**: how far along, and what "done" looks like
  19. - ⛔ **Blocked**: why, how to unblock it, and *who* should do it
  20. - ⚠️ **Risks**: anything that could break or slip, even if it's not blocking yet
  21. - ⏭️ **Next up**
  22. - 🅿️ **Parked**: side tasks set aside for later
  23. - 🙋 **Decisions needed from you**: with options and a recommendation
  24. Small updates stay short: two to four lines, with empty sections skipped.
  25. - **🎯 Focused on the main task.** Side tasks go on a Parked list instead of pulling Claude off course, and nothing is dropped. After every detour Claude says the main goal and the next step. For work spread across chats, it can keep the goal and Parked list in `FOCUS.md` (only with your OK). Run `/earthspoken:focus` to set or show the main goal.
  26. - **✂️ Short, never incomplete.** No filler, but risks, blockers and decisions are never cut.
  27. - **🤝 Plays well with others.** If your CLAUDE.md or another style plugin asks for a different tone, that wins. Two rules always apply: clear names, and risks and blockers are never dropped.
  28. - **🔁 Always on.** The rules load at every session start and again after the conversation is compacted. Helper agents get a short version too.
  29. ## Install
  30. Inside Claude Code:
  31. ```
  32. /plugin marketplace add mina-yousry/earthspoken
  33. /plugin install earthspoken@earthspoken
  34. /reload-plugins
  35. ```
  36. Or from your terminal:
  37. ```bash
  38. claude plugin marketplace add mina-yousry/earthspoken
  39. ```
  40. ```bash
  41. claude plugin install earthspoken@earthspoken
  42. ```
  43. ### Skills-only edition
  44. [`plugins/earthspoken-lite`](plugins/earthspoken-lite) has the same rules and progress report with no hooks. It's the edition submitted to the Claude directory. The rules load when Claude picks up the skill, not at every session start, and helper agents only get them if Claude passes them on. Install one edition, not both.
  45. ## Try it
  46. 1. Run `/plugin` and check that **earthspoken** shows as enabled.
  47. 2. Start any task, then ask **"where are we?"** or run `/earthspoken:progress`.
  48. 3. To focus the report, add a topic: `/earthspoken:progress checkout page`.
  49. ## Update
  50. ```bash
  51. claude plugin update earthspoken@earthspoken
  52. ```
  53. Auto-update is off by default for community marketplaces. Turn it on for `earthspoken` in `/plugin` → Marketplaces to get new versions automatically.
  54. ## Roll it out to your team
  55. Add this to your project's `.claude/settings.json` and commit it:
  56. ```json
  57. {
  58. "extraKnownMarketplaces": {
  59. "earthspoken": {
  60. "source": { "source": "github", "repo": "mina-yousry/earthspoken" }
  61. }
  62. },
  63. "enabledPlugins": {
  64. "earthspoken@earthspoken": true
  65. }
  66. }
  67. ```
  68. This makes the marketplace known and marks the plugin as enabled for the project, but it does **not** install it.
  69. Each teammate runs this once, after trusting the project folder:
  70. ```bash
  71. claude plugin install earthspoken@earthspoken --scope project
  72. ```
  73. ## Pause or remove it
  74. | To | Run |
  75. |---|---|
  76. | Pause it | `/plugin disable earthspoken@earthspoken` |
  77. | Turn it back on | `/plugin enable earthspoken@earthspoken` |
  78. | Remove it | `/plugin uninstall earthspoken@earthspoken` |
  79. | Remove the marketplace too | `/plugin marketplace remove earthspoken` |
  80. For team installs, also delete the `earthspoken` entries from `.claude/settings.json`.
  81. ## Make it yours
  82. Fork this repo, then edit:
  83. - `plugins/earthspoken/rules/plain-language.md`: the naming and brevity rules.
  84. - `plugins/earthspoken/skills/progress/SKILL.md`: the layout of the progress report. Prefer plain-text headings? Remove the emoji there, or just tell Claude "no emoji".
  85. - `plugins/earthspoken/rules/subagent-context.json`: the short rules given to helper agents.
  86. Install your fork with `/plugin marketplace add <your-github-user>/earthspoken`.
  87. ## How it works
  88. ```
  89. .claude-plugin/marketplace.json lists the plugin so people can install it
  90. plugins/earthspoken/
  91. .claude-plugin/plugin.json plugin name, version, description
  92. hooks/hooks.json loads the rules at session start and helper-agent start
  93. rules/plain-language.md the naming and brevity rules (about 280 words)
  94. rules/subagent-context.json the short version for helper agents
  95. skills/progress/SKILL.md the progress report (/earthspoken:progress)
  96. skills/focus/SKILL.md main goal and Parked list (/earthspoken:focus)
  97. plugins/earthspoken-lite/ skills-only edition for the Claude directory (no hooks)
  98. tests/trigger-cases.md prompts to check the report triggers correctly
  99. ```
  100. A `SessionStart` hook reads the rules file into Claude's context (on startup, resume, clear and compaction).
  101. A `SubagentStart` hook gives every helper agent a short version.
  102. The `progress` skill runs when you ask about status, or when you call it directly.
  103. **Privacy:** no network calls and no scripts. The hooks only read local files with `cat`. The `focus` skill writes `FOCUS.md` in your project only after you agree. Like any prompt, the rules are sent to Claude as part of your conversation.
  104. ## Contributing
  105. Issues and pull requests are welcome, especially before-and-after examples where Claude still slipped into shorthand.
  106. Check `tests/trigger-cases.md` before opening a pull request. Bump `version` in both `plugin.json` and `marketplace.json` for every release, or users won't get the update.
  107. See [CHANGELOG.md](CHANGELOG.md) for what changed.
  108. ## License
  109. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.