History

Dotta 953b315dfb Shorten skill frontmatter descriptions (#9353 ) ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Paperclip agents can load repository and catalog skills, and Codex renders skill names and frontmatter descriptions into startup context. > - Long descriptions consume the fixed skill metadata budget before Codex can use the progressively disclosed skill bodies. > - The repo `.agents/skills` descriptions and a few shipped catalog descriptions had grown into operational documentation instead of short trigger metadata. > - This pull request keeps the strongest trigger language in frontmatter while leaving detailed procedures in each skill body. > - The benefit is lower prompt overhead, more reliable skill triggering, and a regression guard that prevents description drift from returning. ## Linked Issues or Issue Description No public GitHub issue found for this maintenance item. ### Pre-submission checklist - [x] I have searched existing open and closed issues and this is not a duplicate. - [x] I am working against `master`. - [x] I have confirmed the issue originates in Paperclip's shipped skill metadata, not in a local agent adapter or provider. ### What happened? Codex startup renders discovered skill names and frontmatter descriptions into a fixed skill metadata budget. Several repository skill descriptions and one shipped catalog description had grown into long-form operational guidance, which can force Codex to truncate descriptions before the model has enough trigger signal to select the right skill. ### Expected behavior Skill frontmatter descriptions should stay short trigger summaries: one capability sentence plus a “use when” clause. Detailed procedures should stay in the skill body and load only after the skill triggers. ### Steps to reproduce 1. Inspect `.agents/skills//SKILL.md` and `packages/skills-catalog/catalog//SKILL.md` frontmatter descriptions. 2. Measure folded YAML `description` values. 3. Observe descriptions above the intended short-trigger range, including descriptions above 300 characters. 4. Run the new shipped catalog test to verify future descriptions stay capped. ### Paperclip version or commit Reproduced on `master` at `cc81eefb6047d8eaf57faf785f421c03dc97073c`. ### Deployment mode Local dev / source checkout metadata inspection. This is not database-related. ### Installation method Built from source. ### Agent adapter(s) involved Codex, because Codex startup uses the skill metadata prompt budget. The metadata source itself is core repository/catalog content. ### Database mode Not database-related. ### Access context Not applicable; this is static repository metadata. ### Node.js version `v22.22.2` in the verification environment. ### Operating system Linux container environment. ### Relevant logs or output Final measurement after this PR: 29 source `SKILL.md` files, max description length 215 chars, 5,449 total description chars, estimated 1,363 description tokens at 4 chars/token. ### Relevant config None. ### Additional context The shipped catalog manifest was regenerated so the generated package metadata matches the edited catalog `SKILL.md` sources. ### Privacy checklist - [x] I have reviewed all pasted output for PII and redacted where necessary. ## What Changed - Shortened long `.agents/skills//SKILL.md` frontmatter descriptions to concise capability plus use-when trigger clauses. - Shortened the over-budget shipped skills catalog descriptions for wireframe, Paperclip capsules, and reflection coach. - Regenerated `packages/skills-catalog/generated/catalog.json` so shipped metadata matches source skill frontmatter. - Added a Vitest regression guard that caps repo skill source descriptions and generated catalog descriptions at 300 characters. ## Verification - `pnpm --filter @paperclipai/skills-catalog build:manifest` - `pnpm --filter @paperclipai/skills-catalog test` — 5 files passed, 19 tests passed - `pnpm --filter @paperclipai/skills-catalog typecheck` - Final measurement: 29 source `SKILL.md` files, max description length 215 chars, 5,449 total description chars, estimated 1,363 description tokens at 4 chars/token. Note: the clean PR worktree was created from `origin/master` and contains only this commit, but it does not have `node_modules`; running `pnpm --filter @paperclipai/skills-catalog test` there failed at tool/package resolution (`vitest`, `tsc`, `@paperclipai/shared`). The dependency-equipped workspace passed the commands above before the commit was cherry-picked onto the clean branch. ## Risks Low risk. This changes skill metadata and tests only. The main risk is over-trimming a useful trigger phrase, mitigated by keeping explicit “use when” clauses and leaving detailed guidance in the skill bodies. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used OpenAI GPT-5 Codex coding agent via Paperclip/Codex, with shell and file-edit tool use. Exact API model ID and context window were not exposed in the runtime. ## 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 (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [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>		2026-07-10 08:46:20 -05:00
..
index-refresh	Shorten skill frontmatter descriptions (#9353 )	2026-07-10 08:46:20 -05:00
paperclip-distill	Shorten skill frontmatter descriptions (#9353 )	2026-07-10 08:46:20 -05:00
wiki-ingest	Shorten skill frontmatter descriptions (#9353 )	2026-07-10 08:46:20 -05:00
wiki-lint	Shorten skill frontmatter descriptions (#9353 )	2026-07-10 08:46:20 -05:00
wiki-maintainer	[codex] Add LLM Wiki plugin package to master (#5716 )	2026-05-11 20:45:41 -05:00
wiki-query	Shorten skill frontmatter descriptions (#9353 )	2026-07-10 08:46:20 -05:00
README.md	[codex] Add LLM Wiki plugin package to master (#5716 )	2026-05-11 20:45:41 -05:00

README.md

LLM Wiki Maintainer Skills

This folder is the plugin-level source for LLM Wiki managed company skills. Paperclip installs these skills into the company skill library and syncs them onto the Wiki Maintainer agent. The Wiki Maintainer's identity and operating loop live in agents/wiki-maintainer/AGENTS.md; the wiki-root AGENTS.md remains the wiki schema for page layout, citation style, and log format.

Each skill is an isolated SKILL.md describing one job — when to invoke it, the inputs that must be true before starting, the steps, and the durable output the operation must leave behind.

Skill registry

Skill	When to invoke
`wiki-maintainer`	General LLM Wiki maintenance and tool-use guidance shared by the operation skills.
`wiki-ingest`	A new file landed in `raw/` and the operation issue says "ingest" — turn the source into durable wiki pages.
`wiki-query`	The user asked the wiki a question; answer with citations and offer to file durable synthesis back into `wiki/`.
`wiki-lint`	A lint or health-check operation — audit for contradictions, orphan pages, weak provenance, broken links, missing concept pages.
`paperclip-distill`	Cursor-window, distill, or backfill operation on Paperclip activity — write a wiki-insightful project page, decisions log, and history note.
`index-refresh`	Refresh `wiki/index.md` so each entry has a tight, scannable summary; flag drift between the index and recent log activity.

Layering

AGENTS.md (wiki root)                              ← schema for the wiki itself: page conventions, frontmatter, voice
  agents/wiki-maintainer/AGENTS.md                 ← agent identity and operating loop
  skills/<skill>/SKILL.md                          ← plugin-managed company skills installed onto the maintainer

When a skill conflicts with the wiki-root AGENTS.md, the wiki schema wins for page format/voice and the skill wins for operation flow. When a skill conflicts with the agent's AGENTS.md, the agent file wins for identity and the skill wins for the operation procedure.

Skill conventions

Front matter has name (kebab-case) and description (one or two sentences with the trigger condition).
Each skill names the input it expects (e.g. an operation issue with originKind ending in :ingest, a captured raw/ path, a Paperclip source bundle).
Each skill ends with a verification checklist — what must be true before the operation issue is closed done.
Skills cite the wiki-plugin tools they rely on (wiki_search, wiki_read_page, wiki_write_page, wiki_read_source, wiki_list_sources).
Skills do not duplicate the page conventions from the wiki root AGENTS.md. They reference it instead.