From efe8b3b707533e62dc5bd34819a4c945329124bb Mon Sep 17 00:00:00 2001 From: Dotta <34892728+cryppadotta@users.noreply.github.com> Date: Thu, 30 Jul 2026 15:28:07 -0700 Subject: [PATCH] feat(skills-catalog): add optional /simplified-english skill (#10410) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Agents draw writing behavior from installable skills in the shipped skills catalog (`packages/skills-catalog`) > - Agent-authored comments, plans, and documents are often wordy or ambiguous, which slows human readers > - A small, opt-in skill can set a clear house style for user-facing prose without touching agent code > - This pull request adds an optional `simplified-english` catalog skill that tells agents to write user-facing comments, plans, and documents in ASD-STE100 Simplified Technical English > - The benefit is shorter, unambiguous, one-meaning-per-sentence writing that readers understand on the first pass ## Linked Issues or Issue Description **Problem or motivation** Agent-authored user-facing text (issue comments, plans, documents) is frequently long-winded, uses inconsistent vocabulary, and packs multiple instructions into one sentence. Readers have to re-read it. There is no shared, installable house style for clear technical writing. **Proposed solution** Add an optional content skill, `simplified-english`, to the shipped catalog. It instructs agents to write user-facing comments, plans, and documents using only ASD-STE100 Simplified Technical English (short sentences, one instruction each, approved single-meaning words, active voice, present tense). Orgs opt in by installing it. **Alternatives considered** Baking the guidance into every agent's base instructions (too broad, not opt-in) or a bundled skill (would apply everywhere by default). An optional skill keeps it opt-in per org. **Roadmap alignment** Additive, opt-in catalog content only; no core behavior change. ## What Changed - Add `packages/skills-catalog/catalog/optional/content/simplified-english/SKILL.md` — a short optional skill instructing agents to write user-facing comments, plans, and documents in ASD-STE100 Simplified Technical English. Includes an "Approved words" section that identifies the controlled vocabulary (the ASD-STE100 Dictionary) and gives concrete house-choice substitutions. - Regenerate `packages/skills-catalog/generated/catalog.json` via `build:manifest` so the manifest includes the new skill. - Pin the new catalog key in `packages/skills-catalog/src/shipped-catalog.test.ts`. ## Verification - `pnpm --filter @paperclipai/skills-catalog build:manifest` → wrote manifest with the new skill. - `pnpm --filter @paperclipai/skills-catalog validate` → "Catalog manifest is valid". - `pnpm --filter @paperclipai/skills-catalog test` → the catalog set/count/key pinning tests pass with the new skill included. - Confirmed the generated entry: key `paperclipai/optional/content/simplified-english`, trustLevel `markdown_only`, description within the 300-char budget cap. ## Risks Low risk. Additive, markdown-only optional skill plus a regenerated manifest and a pinning-test update. No runtime code, migrations, or workflow changes. Not installed by default (`defaultInstall: false`). ## Model Used Claude Opus 4.8 (1M context), extended thinking, with tool use / code execution. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links - [x] My branch name describes the change and contains no internal Paperclip ticket id - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip --- .../content/simplified-english/SKILL.md | 40 +++++++++++++++++++ .../skills-catalog/generated/catalog.json | 38 +++++++++++++++++- .../src/shipped-catalog.test.ts | 1 + 3 files changed, 78 insertions(+), 1 deletion(-) create mode 100644 packages/skills-catalog/catalog/optional/content/simplified-english/SKILL.md diff --git a/packages/skills-catalog/catalog/optional/content/simplified-english/SKILL.md b/packages/skills-catalog/catalog/optional/content/simplified-english/SKILL.md new file mode 100644 index 0000000000..5cc7bbeb92 --- /dev/null +++ b/packages/skills-catalog/catalog/optional/content/simplified-english/SKILL.md @@ -0,0 +1,40 @@ +--- +name: simplified-english +description: Write user-facing comments, plans, and documents in ASD-STE100 Simplified Technical English — short, unambiguous sentences with approved words and one meaning each — so readers understand them the first time. +key: paperclipai/optional/content/simplified-english +recommendedForRoles: + - engineer + - product + - writer + - devrel +tags: + - writing + - communication + - clarity + - style +--- + +# Simplified English + +For user-facing comments, plans, and documents, write using only ASD-STE100 Simplified Technical English. + +## Core rules + +- Use short sentences (procedures ≤ 20 words, descriptions ≤ 25 words). +- Give one instruction per sentence. +- Use approved words with one meaning each; avoid synonyms and jargon. +- Use the active voice and the present tense. +- Use articles ("the", "a") and do not drop words to save space. +- Write positive instructions; avoid negative or vague qualifiers. +- Keep paragraphs to one topic. + +## Approved words + +The approved words are the ASD-STE100 controlled vocabulary — the Dictionary in the current ASD-STE100 specification, plus the technical names and technical verbs that your subject needs. When a word is not approved, use the simplest common word that has one meaning. Prefer these house choices: + +- "start" / "stop" (not "initiate", "commence", "terminate", "kill") +- "make" (not "implement", "leverage", "utilize") +- "before" / "after" (not "prior to", "subsequent to") +- "about" (not "regarding", "in relation to") +- "help" (not "facilitate") +- "use" (not "utilize", "employ") diff --git a/packages/skills-catalog/generated/catalog.json b/packages/skills-catalog/generated/catalog.json index 8f423e1dd8..9456225a9e 100644 --- a/packages/skills-catalog/generated/catalog.json +++ b/packages/skills-catalog/generated/catalog.json @@ -2,7 +2,7 @@ "schemaVersion": 1, "packageName": "@paperclipai/skills-catalog", "packageVersion": "0.3.1", - "generatedAt": "2026-07-24T18:19:49.696Z", + "generatedAt": "2026-07-28T22:35:25.645Z", "skills": [ { "id": "paperclipai:bundled:docs:doc-maintenance", @@ -485,6 +485,42 @@ ], "contentHash": "sha256:efe8ea89b552df95222609867c9c75f1b40e16f457d34e7e4a124f54daa33efa" }, + { + "id": "paperclipai:optional:content:simplified-english", + "key": "paperclipai/optional/content/simplified-english", + "kind": "optional", + "category": "content", + "slug": "simplified-english", + "name": "simplified-english", + "description": "Write user-facing comments, plans, and documents in ASD-STE100 Simplified Technical English — short, unambiguous sentences with approved words and one meaning each — so readers understand them the first time.", + "path": "catalog/optional/content/simplified-english", + "entrypoint": "SKILL.md", + "trustLevel": "markdown_only", + "compatibility": "compatible", + "defaultInstall": false, + "recommendedForRoles": [ + "engineer", + "product", + "writer", + "devrel" + ], + "requires": [], + "tags": [ + "writing", + "communication", + "clarity", + "style" + ], + "files": [ + { + "path": "SKILL.md", + "kind": "skill", + "sizeBytes": 1578, + "sha256": "a0f7385599873910e2fabf400346016a07dacbc7ece27c0e3616ae8fd94ebfbb" + } + ], + "contentHash": "sha256:642321f40d51e0125df05c6fbace49aeb07ec30392058756909c259c9c5eac6a" + }, { "id": "paperclipai:optional:finance:ramp", "key": "paperclipai/optional/finance/ramp", diff --git a/packages/skills-catalog/src/shipped-catalog.test.ts b/packages/skills-catalog/src/shipped-catalog.test.ts index 99c6dd4d5d..2c9211f695 100644 --- a/packages/skills-catalog/src/shipped-catalog.test.ts +++ b/packages/skills-catalog/src/shipped-catalog.test.ts @@ -20,6 +20,7 @@ const EXPECTED_BUNDLED_KEYS = [ const EXPECTED_OPTIONAL_KEYS = [ "paperclipai/optional/browser/agent-browser", "paperclipai/optional/content/release-announcement", + "paperclipai/optional/content/simplified-english", "paperclipai/optional/finance/ramp", "paperclipai/optional/product/design-critique", "paperclipai/optional/research/last30days",