## 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>
## Thinking Path
> - Paperclip orchestrates AI agents for zero-human companies.
> - The plugin system is the extension surface for optional product
capabilities without baking every workflow into core.
> - The LLM Wiki plugin package was reviewed in stacked PR #5592, which
targeted `pap-9173-llm-wiki-rest`.
> - The stack base PR #5597 merged to `master` before #5592 was merged
into that branch, so the plugin package never reached `master`.
> - A direct PR from `pap-9173-llm-wiki-rest` back to `master` would be
noisy because that branch has diverged from current `master`.
> - This pull request reapplies the reviewed
`packages/plugins/plugin-llm-wiki/` package onto current `master` and
updates Docker deps-stage manifest coverage.
> - The branch intentionally no longer changes `pnpm-workspace.yaml`
after maintainer feedback; because the new package is now a root
workspace importer, the remaining integration question is how
maintainers want the root lockfile handled under the current PR policy.
## What Changed
- Added the LLM Wiki plugin package under
`packages/plugins/plugin-llm-wiki/` from the merged PR #5592 head.
- Preserved the post-review cleanup from #5592: generated
design/screenshot artifacts are not committed, and `src/ui/index.tsx` /
`src/wiki.ts` are small public entrypoints.
- Added the new plugin package manifest to the Docker deps stage so
policy can validate package manifest coverage.
- Removed the earlier `pnpm-workspace.yaml` exclusion per maintainer
request, so the plugin is included by the existing `packages/plugins/*`
workspace glob.
## Verification
Current head:
- PGlite migration harness: ran migrations 001-003, verified old
non-space distillation unique constraints were removed, inserted
duplicate cursor and work-item keys in a second space, then reran
migration 003 successfully
- `node ./scripts/check-docker-deps-stage.mjs`
- `git diff --check`
Known current-head install result after removing the workspace
exclusion:
- `pnpm install --frozen-lockfile` fails because `pnpm-lock.yaml` has no
importer for `packages/plugins/plugin-llm-wiki/package.json`.
Previously verified on the same plugin source before the
workspace-exclusion removal:
- `pnpm --filter @paperclipai/plugin-sdk build`
- `cd packages/plugins/plugin-llm-wiki && pnpm install --lockfile=false
&& pnpm test`
## Risks
- The branch now includes `packages/plugins/plugin-llm-wiki` in the root
workspace but does not update `pnpm-lock.yaml`. Root frozen install will
fail until maintainers choose a lockfile path that fits repo policy.
- Committing `pnpm-lock.yaml` directly on this PR conflicts with the
current PR policy check, while excluding the package from
`pnpm-workspace.yaml` was rejected in maintainer feedback.
- The package includes UI code already reviewed in #5592; generated
screenshot/design artifacts were intentionally removed per maintainer
request, so visual review should regenerate screenshots locally if
needed.
- The package depends on plugin host support from #5597, which is
already merged to `master`.
> 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 via Codex CLI, tool use and local code execution
enabled; context window not exposed.
## 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 run the targeted checks listed above
- [x] I have added or updated tests where applicable
- [ ] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge
Stack context: #5592 was merged into `pap-9173-llm-wiki-rest` after
#5597 had already merged that branch to `master`, so this follow-up PR
is needed to carry the plugin package itself into `master`.
Co-authored-by: Paperclip <noreply@paperclip.ing>
Dotta