diff --git a/.agents/skills/check-pr/SKILL.md b/.agents/skills/check-pr/SKILL.md index 88d52c10f0..b02e2c941f 100644 --- a/.agents/skills/check-pr/SKILL.md +++ b/.agents/skills/check-pr/SKILL.md @@ -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: diff --git a/.agents/skills/company-creator/SKILL.md b/.agents/skills/company-creator/SKILL.md index b2f4432bcd..afe4be9b62 100644 --- a/.agents/skills/company-creator/SKILL.md +++ b/.agents/skills/company-creator/SKILL.md @@ -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 diff --git a/.agents/skills/create-agent-adapter/SKILL.md b/.agents/skills/create-agent-adapter/SKILL.md index a41318580c..6d11362b09 100644 --- a/.agents/skills/create-agent-adapter/SKILL.md +++ b/.agents/skills/create-agent-adapter/SKILL.md @@ -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 diff --git a/.agents/skills/create-issue-interaction-ui/SKILL.md b/.agents/skills/create-issue-interaction-ui/SKILL.md index 9a3bdde25c..9c46dacd46 100644 --- a/.agents/skills/create-issue-interaction-ui/SKILL.md +++ b/.agents/skills/create-issue-interaction-ui/SKILL.md @@ -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) diff --git a/.agents/skills/deal-with-security-advisory/SKILL.md b/.agents/skills/deal-with-security-advisory/SKILL.md index 0ba122366e..8ddccd52cc 100644 --- a/.agents/skills/deal-with-security-advisory/SKILL.md +++ b/.agents/skills/deal-with-security-advisory/SKILL.md @@ -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 diff --git a/.agents/skills/diagnose-why-work-stopped/SKILL.md b/.agents/skills/diagnose-why-work-stopped/SKILL.md index 001738731b..91caa62fa8 100644 --- a/.agents/skills/diagnose-why-work-stopped/SKILL.md +++ b/.agents/skills/diagnose-why-work-stopped/SKILL.md @@ -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 diff --git a/.agents/skills/doc-maintenance/SKILL.md b/.agents/skills/doc-maintenance/SKILL.md index a597e90ccb..839786bc82 100644 --- a/.agents/skills/doc-maintenance/SKILL.md +++ b/.agents/skills/doc-maintenance/SKILL.md @@ -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 diff --git a/.agents/skills/paperclip-create-plugin/SKILL.md b/.agents/skills/paperclip-create-plugin/SKILL.md index 4dda697d64..7e660eadd6 100644 --- a/.agents/skills/paperclip-create-plugin/SKILL.md +++ b/.agents/skills/paperclip-create-plugin/SKILL.md @@ -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 `, - 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 diff --git a/.agents/skills/paperclip-dev-workspace-run-verify-fix/SKILL.md b/.agents/skills/paperclip-dev-workspace-run-verify-fix/SKILL.md index 1fae60e307..9b41eed6a1 100644 --- a/.agents/skills/paperclip-dev-workspace-run-verify-fix/SKILL.md +++ b/.agents/skills/paperclip-dev-workspace-run-verify-fix/SKILL.md @@ -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 diff --git a/.agents/skills/paperclip-page/SKILL.md b/.agents/skills/paperclip-page/SKILL.md index cf2852466d..e9e74cfe08 100644 --- a/.agents/skills/paperclip-page/SKILL.md +++ b/.agents/skills/paperclip-page/SKILL.md @@ -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 diff --git a/.agents/skills/pr-report/SKILL.md b/.agents/skills/pr-report/SKILL.md index 5064b67c09..3ebe590ee7 100644 --- a/.agents/skills/pr-report/SKILL.md +++ b/.agents/skills/pr-report/SKILL.md @@ -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 diff --git a/.agents/skills/prcheckloop/SKILL.md b/.agents/skills/prcheckloop/SKILL.md index 70d9e19af6..32dc5d5b44 100644 --- a/.agents/skills/prcheckloop/SKILL.md +++ b/.agents/skills/prcheckloop/SKILL.md @@ -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 diff --git a/.agents/skills/release-changelog-discord-message/SKILL.md b/.agents/skills/release-changelog-discord-message/SKILL.md index 374f3a089d..367ee8474d 100644 --- a/.agents/skills/release-changelog-discord-message/SKILL.md +++ b/.agents/skills/release-changelog-discord-message/SKILL.md @@ -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 diff --git a/.agents/skills/terminal-bench-loop/SKILL.md b/.agents/skills/terminal-bench-loop/SKILL.md index 6a3c8d2115..f106f77450 100644 --- a/.agents/skills/terminal-bench-loop/SKILL.md +++ b/.agents/skills/terminal-bench-loop/SKILL.md @@ -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 diff --git a/packages/plugins/plugin-llm-wiki/skills/index-refresh/SKILL.md b/packages/plugins/plugin-llm-wiki/skills/index-refresh/SKILL.md index e0380e67f3..c1e7f32ee5 100644 --- a/packages/plugins/plugin-llm-wiki/skills/index-refresh/SKILL.md +++ b/packages/plugins/plugin-llm-wiki/skills/index-refresh/SKILL.md @@ -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 diff --git a/packages/plugins/plugin-llm-wiki/skills/paperclip-distill/SKILL.md b/packages/plugins/plugin-llm-wiki/skills/paperclip-distill/SKILL.md index fa7b8d60d5..8bbebfb188 100644 --- a/packages/plugins/plugin-llm-wiki/skills/paperclip-distill/SKILL.md +++ b/packages/plugins/plugin-llm-wiki/skills/paperclip-distill/SKILL.md @@ -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 diff --git a/packages/plugins/plugin-llm-wiki/skills/wiki-ingest/SKILL.md b/packages/plugins/plugin-llm-wiki/skills/wiki-ingest/SKILL.md index 3422af806b..fdcadfe372 100644 --- a/packages/plugins/plugin-llm-wiki/skills/wiki-ingest/SKILL.md +++ b/packages/plugins/plugin-llm-wiki/skills/wiki-ingest/SKILL.md @@ -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 ". 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 ". Create durable source, entity, concept, synthesis, index, and log pages; use paperclip-distill for Paperclip bundles. --- # Wiki Ingest diff --git a/packages/plugins/plugin-llm-wiki/skills/wiki-lint/SKILL.md b/packages/plugins/plugin-llm-wiki/skills/wiki-lint/SKILL.md index acaa02557f..345ca995f9 100644 --- a/packages/plugins/plugin-llm-wiki/skills/wiki-lint/SKILL.md +++ b/packages/plugins/plugin-llm-wiki/skills/wiki-lint/SKILL.md @@ -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 diff --git a/packages/plugins/plugin-llm-wiki/skills/wiki-query/SKILL.md b/packages/plugins/plugin-llm-wiki/skills/wiki-query/SKILL.md index ccb2855a7f..fe8d9e57bf 100644 --- a/packages/plugins/plugin-llm-wiki/skills/wiki-query/SKILL.md +++ b/packages/plugins/plugin-llm-wiki/skills/wiki-query/SKILL.md @@ -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 diff --git a/packages/skills-catalog/catalog/bundled/paperclip-operations/reflection-coach/SKILL.md b/packages/skills-catalog/catalog/bundled/paperclip-operations/reflection-coach/SKILL.md index c6786939d7..b516783892 100644 --- a/packages/skills-catalog/catalog/bundled/paperclip-operations/reflection-coach/SKILL.md +++ b/packages/skills-catalog/catalog/bundled/paperclip-operations/reflection-coach/SKILL.md @@ -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 diff --git a/packages/skills-catalog/catalog/bundled/product/paperclip-capsules/SKILL.md b/packages/skills-catalog/catalog/bundled/product/paperclip-capsules/SKILL.md index 059eec505f..f14a7e62ab 100644 --- a/packages/skills-catalog/catalog/bundled/product/paperclip-capsules/SKILL.md +++ b/packages/skills-catalog/catalog/bundled/product/paperclip-capsules/SKILL.md @@ -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 diff --git a/packages/skills-catalog/catalog/bundled/product/wireframe/SKILL.md b/packages/skills-catalog/catalog/bundled/product/wireframe/SKILL.md index cc8af1fbb4..8058c4d48e 100644 --- a/packages/skills-catalog/catalog/bundled/product/wireframe/SKILL.md +++ b/packages/skills-catalog/catalog/bundled/product/wireframe/SKILL.md @@ -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 diff --git a/packages/skills-catalog/generated/catalog.json b/packages/skills-catalog/generated/catalog.json index aa64ff9229..bb0bdfb0eb 100644 --- a/packages/skills-catalog/generated/catalog.json +++ b/packages/skills-catalog/generated/catalog.json @@ -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", diff --git a/packages/skills-catalog/src/shipped-catalog.test.ts b/packages/skills-catalog/src/shipped-catalog.test.ts index 1a29bbb473..0dfe0221b4 100644 --- a/packages/skills-catalog/src/shipped-catalog.test.ts +++ b/packages/skills-catalog/src/shipped-catalog.test.ts @@ -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") diff --git a/skills/paperclip-board/SKILL.md b/skills/paperclip-board/SKILL.md index 55fa03b40c..318fcb72bc 100644 --- a/skills/paperclip-board/SKILL.md +++ b/skills/paperclip-board/SKILL.md @@ -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 diff --git a/skills/paperclip-converting-plans-to-tasks/SKILL.md b/skills/paperclip-converting-plans-to-tasks/SKILL.md index 64d846df39..8e4c4b6d0f 100644 --- a/skills/paperclip-converting-plans-to-tasks/SKILL.md +++ b/skills/paperclip-converting-plans-to-tasks/SKILL.md @@ -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 diff --git a/skills/paperclip/SKILL.md b/skills/paperclip/SKILL.md index bf4d86634b..bb7f746341 100644 --- a/skills/paperclip/SKILL.md +++ b/skills/paperclip/SKILL.md @@ -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 diff --git a/skills/para-memory-files/SKILL.md b/skills/para-memory-files/SKILL.md index 99da806988..b90a1aa8cf 100644 --- a/skills/para-memory-files/SKILL.md +++ b/skills/para-memory-files/SKILL.md @@ -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