0 Fork 0

mirror of https://github.com/paperclipai/paperclip.git synced 2026-10-11 05:31:46 +02:00

Files

T

DottaandPaperclip 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

3.9 KiB

Raw Permalink Blame History

name, description

name	description
index-refresh	Use when an LLM Wiki operation issue requests an index refresh. Rebuild `wiki/index.md` from the actual wiki tree, reconcile missing/deleted entries, and log counts without editing page bodies.

Index Refresh

Keep wiki/index.md accurate and scannable. The index is the maintainer's first stop for navigation — its quality determines how cheap every subsequent operation becomes.

Inputs

An operation issue with operationType: "index" (or the index-refresh routine title).
The operation issue's target wikiId, spaceSlug, and space root. Refresh only that space unless the issue explicitly says this is a multi-space sweep.

Workflow

Read the target space's wiki/index.md as it currently stands.
Walk the target space's wiki/. wiki/projects/<slug>/standup.md entries are current-state companions for durable wiki/projects/<slug>/index.md pages; index them only as links attached to the matching project entry. Walk wiki/ by category (sources/, projects/, entities/, concepts/, synthesis/, plus any custom subdirectories the wiki schema added).
Read the target space's last ~50 entries of wiki/log.md to spot pages that were created or substantially changed but never made it to the index.
Per category, produce sorted entries of the form:
```
- [[<path>]] — <one-line summary>
```
The summary is one factual sentence pulled from the page's first paragraph or its title. No status, no datestamps in the index — those belong in the page itself or in the log.

Drop entries whose page no longer exists. Note the deletion in the log:

## [YYYY-MM-DD] index-refresh | reconciled
- removed: [[wiki/old-page]] (page deleted)
- added: [[wiki/new-page]] — <summary>

Add entries for pages that exist on disk but were missing from the index. Skip wiki/log.md and wiki/index.md themselves. For standalone wiki/projects/<slug>/standup.md without a matching durable project page, add it under Projects and flag it for later durable-page distillation.
Write project entries editorially. The Projects section should group work by the project's concept and purpose, not by issue ids, dates, statuses, UUIDs, or source metadata. Link task identifiers only as supporting evidence.
Preserve custom categories. If the wiki has added e.g. wiki/papers/ or wiki/runbooks/, keep its index section. Do not collapse to the default five categories.
Append a log entry with counts:
```
## [YYYY-MM-DD] index-refresh | added=N removed=M
- operation issue: <issue identifier>
```
If the index was already accurate, the log entry says added=0 removed=0 — still write it so future audits can see the run happened.

What this skill does NOT do

Does not change page content.
Does not resolve contradictions, fix broken links, or fill concept gaps. Those go to the next wiki-lint run.
Does not write summaries that are not already supported by the page itself. If a page lacks a clear first paragraph to summarise, flag it for wiki-lint.

Voice

Index entries are one factual line per page, present tense.
No emojis, no statuses, no dates in wiki/index.md. Dates live in the log.

Verification

Before closing the operation issue:

wiki/index.md matches the actual contents of wiki/ — no missing pages, no dangling entries.
Project entries include current wiki/projects/<slug>/standup.md links when standups exist.
Each index line has the form - [[path]] — <summary>.
Custom category sections are preserved.
wiki/log.md has the index-refresh entry with counts (even if the counts are zero).
No page bodies were modified. No file under raw/ was modified.

Tools

wiki_search, wiki_read_page, wiki_write_page (for wiki/index.md and wiki/log.md only). Always include the operation issue's wikiId and spaceSlug.

3.9 KiB Raw Permalink Blame History