mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-09 16:35:27 +02:00
DottaandPaperclip
efe8b3b707
## 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 <!-- Feature request (no public GitHub issue). Described inline per CONTRIBUTING.md → "Link Issues or Describe Them In-PR". --> **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 <noreply@paperclip.ing>