## 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>
efe8b3b707