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>
This commit is contained in:
Dotta
GitHub
parent
0f5f461729
commit
953b315dfb
|
|
@ -1,11 +1,9 @@
|
|||
---
|
||||
name: check-pr
|
||||
description: >
|
||||
Checks a GitHub, GitLab, or Perforce (p4) pull request (or merge request, or shelved changelist)
|
||||
for unresolved review comments, failing status checks, and incomplete PR descriptions. Waits for
|
||||
pending checks to complete, categorizes issues as actionable or informational, and optionally fixes
|
||||
and resolves them. Use when the user wants to check a PR/MR/CL, address review feedback, or prepare
|
||||
a change for submission.
|
||||
Check a GitHub, GitLab, or Perforce PR/MR/CL for review comments, failing
|
||||
checks, and PR-body gaps. Use when asked to inspect, fix, or prepare a change
|
||||
for submission.
|
||||
license: MIT
|
||||
compatibility: Requires git and gh (GitHub CLI), glab (GitLab CLI), or p4 (Perforce CLI) installed and authenticated.
|
||||
metadata:
|
||||
|
|
|
|||
|
|
@ -1,15 +1,9 @@
|
|||
---
|
||||
name: company-creator
|
||||
description: >
|
||||
Create agent company packages conforming to the Agent Companies specification
|
||||
(agentcompanies/v1). Use when a user wants to create a new agent company from
|
||||
scratch, build a company around an existing git repo or skills collection, or
|
||||
scaffold a team/department of agents. Triggers on: "create a company", "make me
|
||||
a company", "build a company from this repo", "set up an agent company",
|
||||
"create a team of agents", "hire some agents", or when given a repo URL and
|
||||
asked to turn it into a company. Do NOT use for importing an existing company
|
||||
package (use the CLI import command instead) or for modifying a company that
|
||||
is already running in Paperclip.
|
||||
Create agent company packages that conform to agentcompanies/v1. Use when asked
|
||||
to create a company, scaffold an agent team, hire agents, or turn a repo/skills
|
||||
collection into a company package.
|
||||
---
|
||||
|
||||
# Company Creator
|
||||
|
|
|
|||
|
|
@ -1,11 +1,9 @@
|
|||
---
|
||||
name: create-agent-adapter
|
||||
description: >
|
||||
Technical guide for creating a new Paperclip agent adapter. Use when building
|
||||
a new adapter package, adding support for a new AI coding tool (e.g. a new
|
||||
CLI agent, API-based agent, or custom process), or when modifying the adapter
|
||||
system. Covers the required interfaces, module structure, registration points,
|
||||
and conventions derived from the existing claude-local and codex-local adapters.
|
||||
Create or modify Paperclip agent adapters across server, UI, and CLI surfaces.
|
||||
Use when adding support for a new CLI agent, API agent, custom process, or
|
||||
adapter package.
|
||||
---
|
||||
|
||||
# Creating a Paperclip Agent Adapter
|
||||
|
|
|
|||
|
|
@ -1,15 +1,9 @@
|
|||
---
|
||||
name: create-issue-interaction-ui
|
||||
description: >
|
||||
Developer/maintainer skill for adding a new issue-thread interaction kind to
|
||||
the Paperclip codebase end-to-end: shared contract, server service/routes,
|
||||
UI card, fixtures/Storybook, CLI/MCP/plugin SDK helpers, agent guidance, and
|
||||
tests. Use when a Paperclip contributor is asked to introduce a new
|
||||
interaction family (something analogous to `request_confirmation`,
|
||||
`request_checkbox_confirmation`, `ask_user_questions`, or `suggest_tasks`)
|
||||
or to extend the issue-thread interaction system with a new card type. Do
|
||||
NOT install this on production Paperclip agents — it is for repo work, not
|
||||
agent runtime behavior.
|
||||
Add a new Paperclip issue-thread interaction kind end-to-end. Use when repo
|
||||
work introduces or extends interaction cards like request_confirmation,
|
||||
checkbox confirmations, ask_user_questions, or suggest_tasks.
|
||||
---
|
||||
|
||||
# Create a new issue-thread interaction UI (developer skill)
|
||||
|
|
|
|||
|
|
@ -1,10 +1,9 @@
|
|||
---
|
||||
name: deal-with-security-advisory
|
||||
description: >
|
||||
Handle a GitHub Security Advisory response for Paperclip, including
|
||||
confidential fix development in a temporary private fork, human coordination
|
||||
on advisory-thread comments, CVE request, synchronized advisory publication,
|
||||
and immediate security release steps.
|
||||
Handle confidential GitHub Security Advisory response for Paperclip. Use when
|
||||
coordinating advisory triage, private-fork fixes, CVE/publication steps, and
|
||||
immediate security releases.
|
||||
---
|
||||
|
||||
# Security Vulnerability Response Instructions
|
||||
|
|
|
|||
|
|
@ -1,13 +1,9 @@
|
|||
---
|
||||
name: diagnose-why-work-stopped
|
||||
description: >
|
||||
How to handle "why did this work stop / why is this looping?" assignments.
|
||||
Forensics first on the named tree, surface the exact stop-point, frame the
|
||||
fix as a general product rule that respects three invariants (productive
|
||||
work continues, only real blockers stop work, no infinite loops), and
|
||||
deliver a plan — no code changes — gated by board/CTO approval before
|
||||
child issues are created. Use whenever the issue title or body asks for
|
||||
forensics on a stalled, looping, or "went too deep" tree.
|
||||
Diagnose stalled, looping, or over-recovered Paperclip issue trees and propose
|
||||
a no-code product-rule plan. Use when asked why work stopped, why it looped, or
|
||||
how to prevent a tree from going too deep.
|
||||
---
|
||||
|
||||
# Diagnose Why Work Stopped
|
||||
|
|
|
|||
|
|
@ -1,11 +1,9 @@
|
|||
---
|
||||
name: doc-maintenance
|
||||
description: >
|
||||
Audit top-level documentation (README, SPEC, PRODUCT) against recent git
|
||||
history to find drift — shipped features missing from docs or features
|
||||
listed as upcoming that already landed. Proposes minimal edits, creates
|
||||
a branch, and opens a PR. Use when asked to review docs for accuracy,
|
||||
after major feature merges, or on a periodic schedule.
|
||||
Audit README, SPEC, and PRODUCT docs against recent git history for drift and
|
||||
make minimal PR-ready edits. Use when asked to review docs for accuracy, after
|
||||
major feature merges, or on a schedule.
|
||||
---
|
||||
|
||||
# Doc Maintenance Skill
|
||||
|
|
|
|||
|
|
@ -1,11 +1,9 @@
|
|||
---
|
||||
name: paperclip-create-plugin
|
||||
description: >
|
||||
Create and develop external Paperclip plugins with the CLI-first workflow.
|
||||
Use when scaffolding a new plugin, working on a local plugin against a running
|
||||
Paperclip instance, or updating plugin authoring docs. Covers `paperclipai
|
||||
plugin init`, the local install loop via `paperclipai plugin install <path>`,
|
||||
worker/UI rebuild and reload semantics, and the required success checklist.
|
||||
Create and develop external Paperclip plugins with the CLI-first workflow. Use
|
||||
when scaffolding a plugin, iterating on a local plugin, installing it into
|
||||
Paperclip, or updating plugin authoring docs.
|
||||
---
|
||||
|
||||
# Create and develop a Paperclip plugin
|
||||
|
|
|
|||
|
|
@ -1,12 +1,9 @@
|
|||
---
|
||||
name: paperclip-dev-workspace-run-verify-fix
|
||||
description: >
|
||||
Run, verify, reseed, and repair a Paperclip isolated dev workspace service.
|
||||
Use when asked to start or fix a Paperclip project/worktree service and prove
|
||||
that it is managed by the Paperclip runtime, has the full bootstrapped cloned
|
||||
database, is healthy, accepts normal dev credentials, exposes populated app
|
||||
data, and is visible as running from both the control-plane and the served
|
||||
workspace app.
|
||||
Run, verify, reseed, and repair Paperclip isolated dev workspace services. Use
|
||||
when asked to start or fix a managed project/worktree service and prove health,
|
||||
login readiness, cloned data, and runtime visibility.
|
||||
---
|
||||
|
||||
# Paperclip Dev Workspace Run / Verify / Fix
|
||||
|
|
|
|||
|
|
@ -1,10 +1,9 @@
|
|||
---
|
||||
name: paperclip-page
|
||||
description: >
|
||||
Publish static HTML pages and asset folders to the Paperclip-approved S3 and
|
||||
CloudFront website host. Use when asked to deploy, publish, host, or share a
|
||||
persistent Paperclip page, wireframe viewer, prototype, report, or other static
|
||||
site without using here.now.
|
||||
Publish static HTML pages and asset folders to the Paperclip S3/CloudFront page
|
||||
host. Use when asked to deploy, host, or share a persistent page, viewer,
|
||||
prototype, report, or static site without here.now.
|
||||
---
|
||||
|
||||
# Paperclip Page
|
||||
|
|
|
|||
|
|
@ -1,10 +1,9 @@
|
|||
---
|
||||
name: pr-report
|
||||
description: >
|
||||
Review a pull request or contribution deeply, explain it tutorial-style for a
|
||||
maintainer, and produce a polished report artifact such as HTML or Markdown.
|
||||
Use when asked to analyze a PR, explain a contributor's design decisions,
|
||||
compare it with similar systems, or prepare a merge recommendation.
|
||||
Produce a maintainer-grade PR or contribution report as HTML or Markdown. Use
|
||||
when asked to deeply review a PR, explain a design, compare systems, or prepare
|
||||
a merge recommendation.
|
||||
---
|
||||
|
||||
# PR Report Skill
|
||||
|
|
|
|||
|
|
@ -1,12 +1,9 @@
|
|||
---
|
||||
name: prcheckloop
|
||||
description: >
|
||||
Iteratively gets a GitHub pull request's checks green. Detects the PR for the
|
||||
current branch or uses a provided PR number, waits for every check on the
|
||||
latest head SHA to appear and finish, investigates failing checks, fixes
|
||||
actionable code or test issues, pushes, and repeats. Escalates with a precise
|
||||
blocker when failures are external, flaky, or not safely fixable. Use when a
|
||||
PR still has unsuccessful checks after review fixes, including after greploop.
|
||||
Iterate on a GitHub PR until latest-head checks are green or a precise blocker
|
||||
is named. Use when a PR still has failing or pending checks after review fixes,
|
||||
including after greploop.
|
||||
---
|
||||
|
||||
# PRCheckloop
|
||||
|
|
|
|||
|
|
@ -1,11 +1,9 @@
|
|||
---
|
||||
name: release-changelog-discord-message
|
||||
description: >
|
||||
Write the Discord release announcement for a stable Paperclip release. Companion
|
||||
to `release-changelog` — that skill produces the file at `releases/vYYYY.MDD.P.md`;
|
||||
this one turns that file into a single copy-pasteable Discord post in dotta's
|
||||
voice and attaches it as the `discord_announcement` document on the release
|
||||
issue.
|
||||
Write the Discord announcement for a stable Paperclip release from the release
|
||||
changelog. Use when a release issue needs a copy-pasteable dotta-voice Discord
|
||||
post or refreshed discord_announcement document.
|
||||
---
|
||||
|
||||
# Release Discord Announcement Skill
|
||||
|
|
|
|||
|
|
@ -1,17 +1,9 @@
|
|||
---
|
||||
name: terminal-bench-loop
|
||||
description: >
|
||||
Run a single Terminal-Bench problem through Paperclip in a bounded,
|
||||
human-in-the-loop improvement cycle until the smoke passes, the board
|
||||
rejects the next fix, the iteration budget is exhausted, or a real
|
||||
blocker is named. Each iteration runs a bounded smoke against an
|
||||
isolated Paperclip App worktree, captures artifacts, diagnoses the
|
||||
exact stop point with `/diagnose-why-work-stopped`, requests board
|
||||
confirmation before any product fix, then reruns against the same
|
||||
worktree. Use whenever an issue asks to "run Terminal-Bench in a
|
||||
loop", "drive Terminal-Bench until it passes", "loop fix-git through
|
||||
Paperclip", or otherwise points at a Terminal-Bench task and asks for
|
||||
bounded iteration with diagnosis.
|
||||
Run one Terminal-Bench task through a bounded Paperclip smoke/diagnosis/fix
|
||||
loop. Use when asked to drive Terminal-Bench until it passes, rerun a
|
||||
Terminal-Bench loop, or iterate with board-gated fixes and diagnosis.
|
||||
---
|
||||
|
||||
# Terminal-Bench Loop
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: index-refresh
|
||||
description: Use when an operation issue is an index refresh — typically the hourly index-refresh routine. Rebuild `wiki/index.md` so each entry has a tight, scannable one-line summary and the catalog tracks the actual contents of `wiki/`. Resolve drift between the index and recent log activity, but do not edit page content.
|
||||
description: 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
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: paperclip-distill
|
||||
description: Use when an operation issue is a Paperclip cursor-window, distill, or backfill — `operationType: "distill"` or `"backfill"` and the body references a Paperclip source bundle for a project or root issue. Turn raw Paperclip activity into a wiki-insightful project page, decisions log, and history note. This skill exists specifically to replace the stiff, datestamp-heavy templated output that the deterministic distiller produces.
|
||||
description: Use when an operation issue is a Paperclip cursor-window, distill, or backfill. Turn source-bundled Paperclip activity into wiki-insightful project standups, durable project pages, decisions, and history without asset dereferencing.
|
||||
---
|
||||
|
||||
# Paperclip Distill
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: wiki-ingest
|
||||
description: Use when an operation issue asks you to ingest a captured source from `raw/` into the LLM Wiki, or when the user explicitly says "ingest <slug>". The issue body will name a file under `raw/` (e.g. `raw/karpathy-llm-wiki.md`) and ask for durable wiki pages. Do not invoke this skill for Paperclip activity bundles — those use `paperclip-distill` instead.
|
||||
description: Use when an operation issue asks to ingest a captured `raw/` source into the LLM Wiki, or the user says "ingest <slug>". Create durable source, entity, concept, synthesis, index, and log pages; use paperclip-distill for Paperclip bundles.
|
||||
---
|
||||
|
||||
# Wiki Ingest
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: wiki-lint
|
||||
description: Use when an operation issue is a lint or health-check (`operationType: "lint"`) — typically the nightly lint routine or a manual "Run lint" from the UI. Audit the wiki for contradictions, orphans, weak provenance, broken links, and missing concept pages, and return a triage list — do not auto-fix.
|
||||
description: 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
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: wiki-query
|
||||
description: Use when an operation issue asks you to answer a question from the LLM Wiki — `operationType: "query"` and a question in the issue body. Answer with citations to wiki pages and raw sources, and offer to file durable synthesis back into `wiki/synthesis/` so the work compounds instead of disappearing into a chat thread.
|
||||
description: Use when an LLM Wiki operation issue asks a question. Answer from wiki pages and raw sources with citations, name gaps plainly, and offer to file durable synthesis when the answer should compound.
|
||||
---
|
||||
|
||||
# Wiki Query
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: reflection-coach
|
||||
description: Reflect on another agent's recent execution record, name evidence-backed patterns, and propose the smallest durable change to their AGENTS.md, a reusable skill, or a tool description — as a reviewable, interaction-gated proposal, never a same-run hot-swap.
|
||||
description: Reflect on another agent's recent execution record and propose the smallest durable instruction, skill, or tool-description change. Use for evidence-backed coaching proposals, never hot-swaps.
|
||||
key: paperclipai/bundled/paperclip-operations/reflection-coach
|
||||
recommendedForRoles:
|
||||
- manager
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: paperclip-capsules
|
||||
description: Generate, implement, or review Paperclip capsule visuals. Use when the user asks for Paperclip capsule art, capsule banks, agent capsule visuals, heartbeat status capsules, capsule identicons, capsule graphic-generator output, or validation of Paperclip capsule brand usage.
|
||||
description: Generate, implement, or review Paperclip capsule visuals. Use for capsule art, agent capsules, heartbeat status capsules, identicons, capsule banks, or brand-usage validation.
|
||||
key: paperclipai/bundled/product/paperclip-capsules
|
||||
recommendedForRoles:
|
||||
- designer
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: wireframe
|
||||
description: Produce low-fidelity black-and-white UI wireframes as standalone SVG files, optionally bundled into a single-page HTML viewer and published via the here-now skill. Use when the user asks to "wireframe X", "sketch a screen for", "draft a layout", "low-fi mockup", "rough mock", "make a page to view the wireframes", "build a viewer for these screens", or to "deploy / publish / host the wireframes". Do NOT use when the user wants production UI code, branded designs, hi-fi mockups, or animated/interactive prototypes — use frontend-design or similar instead.
|
||||
description: Produce low-fidelity black-and-white UI wireframes as SVGs or viewer pages. Use when asked to wireframe, sketch a screen, draft a layout, make a low-fi mockup, or publish wireframes.
|
||||
key: paperclipai/bundled/product/wireframe
|
||||
recommendedForRoles:
|
||||
- designer
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
"schemaVersion": 1,
|
||||
"packageName": "@paperclipai/skills-catalog",
|
||||
"packageVersion": "0.3.1",
|
||||
"generatedAt": "2026-07-10T00:27:11.902Z",
|
||||
"generatedAt": "2026-07-10T13:15:25.878Z",
|
||||
"skills": [
|
||||
{
|
||||
"id": "paperclipai:bundled:docs:doc-maintenance",
|
||||
|
|
@ -80,7 +80,7 @@
|
|||
"category": "paperclip-operations",
|
||||
"slug": "reflection-coach",
|
||||
"name": "reflection-coach",
|
||||
"description": "Reflect on another agent's recent execution record, name evidence-backed patterns, and propose the smallest durable change to their AGENTS.md, a reusable skill, or a tool description — as a reviewable, interaction-gated proposal, never a same-run hot-swap.",
|
||||
"description": "Reflect on another agent's recent execution record and propose the smallest durable instruction, skill, or tool-description change. Use for evidence-backed coaching proposals, never hot-swaps.",
|
||||
"path": "catalog/bundled/paperclip-operations/reflection-coach",
|
||||
"entrypoint": "SKILL.md",
|
||||
"trustLevel": "markdown_only",
|
||||
|
|
@ -102,11 +102,11 @@
|
|||
{
|
||||
"path": "SKILL.md",
|
||||
"kind": "skill",
|
||||
"sizeBytes": 11903,
|
||||
"sha256": "ca167eac8d1e89cadc8009b61a204368507e7edb7f2da0688fea6dba8223e189"
|
||||
"sizeBytes": 11837,
|
||||
"sha256": "86d6e382c32c626213b46c010cc7fc1ec460821a8c777cfa5b8e86fa9d6a86b2"
|
||||
}
|
||||
],
|
||||
"contentHash": "sha256:20381a898f05ceb668e305708dd33a03ce36aef0e00b923c01ae20ab785f04d2"
|
||||
"contentHash": "sha256:1c7a82cd9638a1d845b238032da3ff4ad80c5b6a87dca46082f501fa4583db55"
|
||||
},
|
||||
{
|
||||
"id": "paperclipai:bundled:paperclip-operations:task-planning",
|
||||
|
|
@ -150,7 +150,7 @@
|
|||
"category": "product",
|
||||
"slug": "paperclip-capsules",
|
||||
"name": "paperclip-capsules",
|
||||
"description": "Generate, implement, or review Paperclip capsule visuals. Use when the user asks for Paperclip capsule art, capsule banks, agent capsule visuals, heartbeat status capsules, capsule identicons, capsule graphic-generator output, or validation of Paperclip capsule brand usage.",
|
||||
"description": "Generate, implement, or review Paperclip capsule visuals. Use for capsule art, agent capsules, heartbeat status capsules, identicons, capsule banks, or brand-usage validation.",
|
||||
"path": "catalog/bundled/product/paperclip-capsules",
|
||||
"entrypoint": "SKILL.md",
|
||||
"trustLevel": "markdown_only",
|
||||
|
|
@ -175,8 +175,8 @@
|
|||
{
|
||||
"path": "SKILL.md",
|
||||
"kind": "skill",
|
||||
"sizeBytes": 5930,
|
||||
"sha256": "eda40e8f29cae07c2ce8ad1cef3406eae243dbbf52069a85cfb56fe7999a25ff"
|
||||
"sizeBytes": 5831,
|
||||
"sha256": "dd659ccb46e105336eb00fbe689b1d5531347fc69493c3156390d40ee413c93e"
|
||||
},
|
||||
{
|
||||
"path": "references/generator-workflows.md",
|
||||
|
|
@ -203,7 +203,7 @@
|
|||
"sha256": "be1f2eccf96b4d2deefe45b3bc1dd0a3597278472c2ffedadc43c57161e9103d"
|
||||
}
|
||||
],
|
||||
"contentHash": "sha256:e8f502f9556103bd575bb664a9d21b1004869990802e639a188a720012116909"
|
||||
"contentHash": "sha256:a2b26cf6895affeeb70c85567a061094450a59bd3c4fdcf28ee65858599ac12c"
|
||||
},
|
||||
{
|
||||
"id": "paperclipai:bundled:product:wireframe",
|
||||
|
|
@ -212,7 +212,7 @@
|
|||
"category": "product",
|
||||
"slug": "wireframe",
|
||||
"name": "wireframe",
|
||||
"description": "Produce low-fidelity black-and-white UI wireframes as standalone SVG files, optionally bundled into a single-page HTML viewer and published via the here-now skill. Use when the user asks to \"wireframe X\", \"sketch a screen for\", \"draft a layout\", \"low-fi mockup\", \"rough mock\", \"make a page to view the wireframes\", \"build a viewer for these screens\", or to \"deploy / publish / host the wireframes\". Do NOT use when the user wants production UI code, branded designs, hi-fi mockups, or animated/interactive prototypes — use frontend-design or similar instead.",
|
||||
"description": "Produce low-fidelity black-and-white UI wireframes as SVGs or viewer pages. Use when asked to wireframe, sketch a screen, draft a layout, make a low-fi mockup, or publish wireframes.",
|
||||
"path": "catalog/bundled/product/wireframe",
|
||||
"entrypoint": "SKILL.md",
|
||||
"trustLevel": "assets",
|
||||
|
|
@ -235,8 +235,8 @@
|
|||
{
|
||||
"path": "SKILL.md",
|
||||
"kind": "skill",
|
||||
"sizeBytes": 11887,
|
||||
"sha256": "a910d038d8cdd13615b82f44a2195b781ebccf01c49f9c58babd43b0701fe644"
|
||||
"sizeBytes": 11509,
|
||||
"sha256": "6992047cc97b67211cc8c1183718ab9aa26b8afc34c70d54d20558c215daaf48"
|
||||
},
|
||||
{
|
||||
"path": "assets/site-template.html",
|
||||
|
|
@ -275,7 +275,7 @@
|
|||
"sha256": "017260d2216859d57e5fa869e0efc6b88c7ed4d8a8a4f5af04fe89a3ef2445bd"
|
||||
}
|
||||
],
|
||||
"contentHash": "sha256:0bd9a9fdc656d529e3f97c00cd504dcf72d3a4fecb8b0504ca2fe3e00d63287f"
|
||||
"contentHash": "sha256:7106d84fc9db2053090f692706e41cfc586e7dd85a44f568e3319c4eefbdde46"
|
||||
},
|
||||
{
|
||||
"id": "paperclipai:bundled:quality:qa-acceptance",
|
||||
|
|
|
|||
|
|
@ -1,4 +1,6 @@
|
|||
import { readFileSync } from "node:fs";
|
||||
import { readFileSync, readdirSync } from "node:fs";
|
||||
import path from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
import { describe, expect, it } from "vitest";
|
||||
import { catalogManifest, catalogSkills, resolveCatalogSkillRef } from "./index.js";
|
||||
|
||||
|
|
@ -21,7 +23,68 @@ const EXPECTED_OPTIONAL_KEYS = [
|
|||
"paperclipai/optional/research/last30days",
|
||||
];
|
||||
|
||||
const MAX_FRONTMATTER_DESCRIPTION_LENGTH = 300;
|
||||
const REPO_ROOT = path.resolve(fileURLToPath(new URL("../../..", import.meta.url)));
|
||||
const SKILL_FRONTMATTER_ROOTS = [
|
||||
path.join(REPO_ROOT, ".agents"),
|
||||
path.join(REPO_ROOT, "skills"),
|
||||
path.join(REPO_ROOT, "packages/adapters"),
|
||||
path.join(REPO_ROOT, "packages/plugins"),
|
||||
path.join(REPO_ROOT, "packages/skills-catalog/catalog"),
|
||||
path.join(REPO_ROOT, "packages/teams-catalog/catalog"),
|
||||
];
|
||||
|
||||
function listSkillFiles(dir: string): string[] {
|
||||
return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
|
||||
const entryPath = path.join(dir, entry.name);
|
||||
if (entry.isDirectory()) return listSkillFiles(entryPath);
|
||||
if (entry.isFile() && entry.name === "SKILL.md") return [entryPath];
|
||||
return [];
|
||||
});
|
||||
}
|
||||
|
||||
function readFrontmatterDescription(markdown: string): string | null {
|
||||
const match = markdown.match(/^---\r?\n([\s\S]*?)\r?\n---/);
|
||||
if (!match) return null;
|
||||
|
||||
const lines = match[1]!.split(/\r?\n/);
|
||||
const descriptionIndex = lines.findIndex((line) => line.startsWith("description:"));
|
||||
if (descriptionIndex === -1) return null;
|
||||
|
||||
const inlineValue = lines[descriptionIndex]!.slice("description:".length).trim();
|
||||
if (/^[>|][+-]?$/.test(inlineValue)) {
|
||||
const descriptionLines: string[] = [];
|
||||
for (let index = descriptionIndex + 1; index < lines.length; index += 1) {
|
||||
const line = lines[index]!;
|
||||
if (/^[A-Za-z0-9_-]+:/.test(line)) break;
|
||||
descriptionLines.push(line.trim());
|
||||
}
|
||||
return descriptionLines.join(" ").replace(/\s+/g, " ").trim();
|
||||
}
|
||||
|
||||
return inlineValue.replace(/^['"]|['"]$/g, "");
|
||||
}
|
||||
|
||||
describe("shipped skills catalog", () => {
|
||||
it("keeps repo and catalog skill descriptions within the prompt budget cap", () => {
|
||||
const violations: string[] = [];
|
||||
for (const skillFile of SKILL_FRONTMATTER_ROOTS.flatMap(listSkillFiles)) {
|
||||
const description = readFrontmatterDescription(readFileSync(skillFile, "utf8"));
|
||||
if (!description) {
|
||||
violations.push(`${path.relative(REPO_ROOT, skillFile)} is missing a frontmatter description`);
|
||||
} else if (description.length > MAX_FRONTMATTER_DESCRIPTION_LENGTH) {
|
||||
violations.push(`${path.relative(REPO_ROOT, skillFile)} description is ${description.length} chars`);
|
||||
}
|
||||
}
|
||||
for (const skill of catalogSkills) {
|
||||
if (skill.description.length > MAX_FRONTMATTER_DESCRIPTION_LENGTH) {
|
||||
violations.push(`${skill.key} generated description is ${skill.description.length} chars`);
|
||||
}
|
||||
}
|
||||
|
||||
expect(violations).toEqual([]);
|
||||
});
|
||||
|
||||
it("ships the expected bundled and optional skill set", () => {
|
||||
const bundledKeys = catalogSkills
|
||||
.filter((skill) => skill.kind === "bundled")
|
||||
|
|
|
|||
|
|
@ -1,10 +1,9 @@
|
|||
---
|
||||
name: paperclip-board
|
||||
description: >
|
||||
Manage a Paperclip company as a board member via chat. Covers onboarding
|
||||
(company creation, CEO setup, hiring plans), agent management, approvals,
|
||||
task monitoring, cost oversight, and work product review. Use this skill
|
||||
whenever the user wants to interact with their Paperclip control plane.
|
||||
Manage a Paperclip company as a board member via chat. Use when the user wants
|
||||
onboarding, company or agent management, approvals, task monitoring, cost
|
||||
oversight, or work product review in the Paperclip control plane.
|
||||
---
|
||||
|
||||
# Paperclip Board Skill
|
||||
|
|
|
|||
|
|
@ -1,13 +1,9 @@
|
|||
---
|
||||
name: paperclip-converting-plans-to-tasks
|
||||
description: >
|
||||
The Paperclip way of converting a plan into executable tasks. Use whenever
|
||||
you are asked to plan, scope, or break down work inside a Paperclip company.
|
||||
Industry-agnostic guidance on how to translate a plan into assigned issues
|
||||
with the right specialty, dependencies, and parallelization so Paperclip's
|
||||
executor can pick up the work — it does not prescribe a plan format. Pair
|
||||
with the `paperclip` skill, which covers the mechanics of writing the plan
|
||||
document and reassigning the issue.
|
||||
Convert Paperclip plans into executable issue graphs. Use when asked to plan,
|
||||
scope, or break down Paperclip company work into assigned tasks with specialty
|
||||
fit, dependencies, blockers, and parallelization.
|
||||
---
|
||||
|
||||
# Paperclip — Converting Plans to Tasks
|
||||
|
|
|
|||
|
|
@ -1,12 +1,10 @@
|
|||
---
|
||||
name: paperclip
|
||||
description: >
|
||||
Interact with the Paperclip control plane API to manage tasks, coordinate with
|
||||
other agents, and follow company governance. Use when you need to check
|
||||
assignments, update task status, delegate work, post comments, set up or manage
|
||||
routines (recurring scheduled tasks), or call any Paperclip API endpoint. Do NOT
|
||||
use for the actual domain work itself (writing code, research, etc.) — only for
|
||||
Paperclip coordination.
|
||||
Interact with the Paperclip control plane API for task coordination and
|
||||
governance. Use when checking assignments, updating issue status, posting
|
||||
comments, delegating work, managing routines, or calling Paperclip API
|
||||
endpoints.
|
||||
---
|
||||
|
||||
# Paperclip Skill
|
||||
|
|
|
|||
|
|
@ -1,13 +1,9 @@
|
|||
---
|
||||
name: para-memory-files
|
||||
description: >
|
||||
File-based memory system using Tiago Forte's PARA method. Use this skill whenever
|
||||
you need to store, retrieve, update, or organize knowledge across sessions. Covers
|
||||
three memory layers: (1) Knowledge graph in PARA folders with atomic YAML facts,
|
||||
(2) Daily notes as raw timeline, (3) Tacit knowledge about user patterns. Also
|
||||
handles planning files, memory decay, weekly synthesis, and recall via qmd.
|
||||
Trigger on any memory operation: saving facts, writing daily notes, creating
|
||||
entities, running weekly synthesis, recalling past context, or managing plans.
|
||||
Use a file-based PARA memory system to store, retrieve, and organize durable
|
||||
knowledge across sessions. Trigger on saving facts, daily notes, entity
|
||||
records, weekly synthesis, recall, tacit user patterns, or plan memory.
|
||||
---
|
||||
|
||||
# PARA Memory Files
|
||||
|
|
|
|||
Loading…
Reference in New Issue