0 Fork 0

mirror of https://github.com/paperclipai/paperclip.git synced 2026-10-27 19:35:13 +01: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.4 KiB

Raw Permalink Blame History

name, description

name	description
wiki-lint	Use when an LLM Wiki operation issue is a lint or health check. Audit for contradictions, orphans, weak provenance, broken links, missing concept pages, and index/log drift; return triage findings without auto-fixing.

Wiki Lint

Audit, do not edit. Return findings the maintainer (human or agent) can triage.

Inputs

An operation issue with operationType: "lint".
The operation issue's target wikiId, spaceSlug, and space root. Lint only that space unless the issue explicitly says this is a multi-space sweep.

Workflow

Walk the target space's wiki/index.md and wiki tree with wiki_search and wiki_read_page, always passing the operation issue's wikiId and spaceSlug. Build a mental map of: pages that exist, pages referenced from index.md, pages referenced from other pages, and raw sources.
Check for the seven recurring issues, in this order:
1. Contradictions — two pages making incompatible claims about the same entity, decision, or status. Flag both pages, name the conflicting claims, and quote evidence.
2. Stale claims — a page asserts X, but a newer source under raw/ has superseded it. Flag the older page; never overwrite.
3. Orphan pages — a wiki/ page is not linked from index.md and not referenced from any other wiki page. Either it should be linked, removed, or merged.
4. Concept gaps — a term appears on three or more pages but has no dedicated wiki/concepts/<slug>.md. Recommend creating one.
5. Broken [[wiki-links]] — a link target file does not exist.
6. Weak provenance — a non-trivial claim is uncited or cites only the wiki itself in a circle. The original source ref should be findable.
7. Index / log drift — pages exist that are not in index.md, or index.md lists pages that no longer exist. Recent operations in wiki/log.md that did not produce a corresponding page change.
Return a triage list, grouped by severity:
- critical: contradictions, broken links to active pages, fabricated citations.
- medium: stale claims, weak provenance, large concept gaps.
- low: orphans, log drift, small index gaps. Each item has: file path, evidence (a 1–2 line quote), suggested fix, and the operation that should follow up (ingest, paperclip-distill, index-refresh, manual review).
Do not write to wiki/. Lint is read-only by design — the maintainer or the routine that follows decides which findings to act on.

Append a log entry describing the run:

## [YYYY-MM-DD] lint | <N findings, M critical>
- operation issue: <issue identifier>
- critical: <count>
- medium: <count>
- low: <count>

Voice

Lead with the count by severity.
Each finding is one bullet. Resist commentary.
When in doubt about severity, say so and surface it as medium with a "verify" note.

Verification

Before closing the operation issue:

Findings are grouped by severity with file paths, evidence, and suggested fix per item.
No files under raw/ were modified. No files under wiki/ were modified except wiki/log.md.
If the run found nothing, the issue is closed with "no findings" and the log entry still exists so future audits can see this run happened.

Tools

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

3.4 KiB Raw Permalink Blame History Unescape Escape