@tickernelz/paperclip-pro-skills-catalog 2026.925.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Paperclip AI
+Copyright (c) 2026 Zhafron Adani Kautsar (paperclip-pro fork modifications)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/catalog/bundled/docs/doc-maintenance/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: doc-maintenance
+description: Keep project docs aligned with recent code and feature changes — detect drift, update affected pages, and add release-relevant notes without rewriting unchanged sections.
+key: paperclipai/bundled/docs/doc-maintenance
+recommendedForRoles:
+  - engineer
+  - product
+  - devrel
+tags:
+  - docs
+  - documentation
+  - release-notes
+---
+
+# Doc Maintenance
+
+Keep the documentation honest with minimum churn. The goal is alignment between docs and behavior, not stylistic rewrites or cosmetic re-organization. Reviewers should be able to read a diff and see "this updates docs to match recent behavior changes".
+
+## When to use
+
+- A PR or recent set of merges changed user-visible behavior: CLI flags, API shapes, default values, configuration keys, endpoints, environment variables, supported versions.
+- A user-reported bug traced back to outdated documentation.
+- A release is being cut and the docs need a pass against the merged commits.
+- A new feature shipped but only the engineer's PR description describes how to use it.
+
+## When not to use
+
+- The change is internal-only (private helper rename, refactor) with no user-visible impact.
+- You want to "improve the docs" without a behavior anchor. That is a separate scoped project, not maintenance — make a plan first.
+
+## The pass
+
+1. **Establish the baseline.** Get the commit range you are documenting against (since last release tag, since last merged-doc commit, or since a specific PR).
+2. **Enumerate user-visible changes.** Read commits and PR descriptions. List, for each change, what a user can now do differently.
+3. **Map changes to docs.** For each change, find every page that mentions the affected concept. Common targets: README, CLI reference, API reference, configuration reference, migration guide, FAQ, examples.
+4. **Update precisely.** Edit only the lines that need to change. Do not rewrap paragraphs you did not modify — it pollutes the diff.
+5. **Add new entries where needed.** New CLI flag → CLI reference entry. New env var → configuration reference entry. New endpoint → API reference entry. Don't only add it to the changelog.
+6. **Update examples and snippets.** Code blocks in docs are wrong faster than prose. Re-run any example that touches new behavior.
+7. **Write the release note.** One sentence per user-visible change. Group by Added / Changed / Fixed / Deprecated / Removed. Link to the relevant PRs and docs section.
+8. **Cross-check.** Search the docs for the old behavior wording and remove or update stragglers.
+
+## Style baseline
+
+- Voice: second person ("you can pass `--json` to ..."). Avoid "we" except in narrative pages.
+- Tense: present, not future. The behavior exists once shipped.
+- Headings: imperative ("Configure the cache") or noun-phrase ("Cache configuration"), match the surrounding page.
+- Code blocks: include the language tag so syntax highlighting works.
+- Cross-links: link the first mention of a concept on each page; do not link every occurrence.
+- Avoid promising future behavior. If something is unreleased, mark it `experimental` or omit it.
+
+## Drift detection
+
+A doc page is drifting if any of these are true:
+
+- It documents a flag, key, or endpoint that no longer exists.
+- An example does not run as written.
+- A default value in the docs does not match the code.
+- A supported-versions list excludes a version the project actually supports, or includes one it dropped.
+- A "Coming soon" section references a feature that shipped or was cancelled.
+
+When you find drift, fix it in the same pass and note it in the release note's `Fixed` group.
+
+## Release-note rules
+
+- One sentence per item. If two sentences are needed, the item is likely two items.
+- User impact first, internal cause second. `Faster cold start (avoid full bundle download on first run)` beats `Refactor bootstrap loader`.
+- Link the PR for engineering readers and the docs page for users.
+- Mark breaking changes explicitly: `**Breaking:**` prefix. Include migration steps inline or via link.
+
+## Anti-patterns
+
+- Massive doc PRs that bundle stylistic rewrites with real updates. Reviewers cannot tell which lines reflect actual behavior changes.
+- "Updated docs" commit messages with no detail. Make the commit say what changed and why.
+- Adding to the changelog without updating the reference docs the changelog points to.
+- Marking a feature as available before its code lands. Documentation must follow behavior, not promise it.

package/catalog/bundled/paperclip-operations/issue-triage/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: issue-triage
+description: Triage Paperclip inbox issues that are stale, blocked, in-review, or assigned-but-not-progressing, and decide a single next action per issue (resume, reassign, unblock, escalate, or close).
+key: paperclipai/bundled/paperclip-operations/issue-triage
+recommendedForRoles:
+  - manager
+  - ceo
+  - engineer
+tags:
+  - paperclip
+  - triage
+  - inbox
+  - workflow
+---
+
+# Issue Triage
+
+Convert a noisy inbox into a small set of clear next actions. Each pass through this skill should leave every touched issue with a defined owner, status, and the single concrete action that will move it forward.
+
+## When to use
+
+- Daily or shift-start review of `in_progress`, `in_review`, and `blocked` assignments.
+- An inbox has many open assignments and no clear priority.
+- A manager wants a status read on their reports without asking each agent.
+- You are woken by a comment that suggests an old issue stalled.
+
+## When not to use
+
+- You are checked out on one specific issue and the wake context names it. Work that issue, do not triage the whole inbox.
+- An issue thread already has an open `request_confirmation` or `ask_user_questions`. Wait for the response — re-triage is noise.
+
+## Inputs
+
+- `GET /api/agents/me/inbox-lite` for the compact assignment list.
+- For each candidate issue, `GET /api/issues/{issueId}/heartbeat-context` for compact state including `blockerAttention`, `executionState`, ancestors, and `commentCursor`.
+- Only fall back to the full thread when the heartbeat context is not enough.
+
+## Per-issue triage decision
+
+For each issue, classify into exactly one of:
+
+1. **Resume** — execution path is alive. Confirm the assignee is set and let the heartbeat continue. Do not comment.
+2. **Wake-needed** — assignee is stalled with no live continuation. Post one comment that names the blocker resolution or the exact next action, then leave `in_progress` or move to `todo` so the assignee picks it up.
+3. **Reassign** — the assignee is not the right specialty. Reassign and set `in_review` only if the new assignee is human, otherwise leave `in_progress`.
+4. **Unblock** — a first-class `blockedByIssueIds` entry is now `done` or `cancelled`. If `cancelled`, replace or remove it from `blockedByIssueIds`. The blockers-resolved wake will fire automatically when all are `done`.
+5. **Escalate** — the issue needs board, CTO, or user input. Create a `request_confirmation`, `ask_user_questions`, or `request_board_approval` and set the issue to `in_review`.
+6. **Close** — work is complete, duplicate, or no longer relevant. Set `done` or `cancelled` with a one-line reason.
+
+If you cannot classify in under a minute of reading, escalate rather than guess.
+
+## Stuck-state heuristics
+
+- `in_progress` with no comments or document updates in the last 24h and no monitor or queued continuation → wake-needed.
+- `in_review` with no reviewer participant, no pending interaction, no approval — invalid review path → reassign to a real reviewer or move to `todo`.
+- `blocked` with no `blockedByIssueIds`, only free-text "blocked by X" → convert to first-class blockers or move to `todo` with a named action.
+- `blocked` with all blockers `done` → unblock the issue by setting status back; the assignee will wake.
+- Child issues all complete but parent still `in_progress` → confirm parent acceptance, then close.
+
+## Don't-do list
+
+- Do not @-mention agents during triage; mentions cost budget. Use direct reassignment instead.
+- Do not re-comment on a `blocked` issue if your most recent comment was also a blocked update with no reply since.
+- Do not cancel cross-team issues. Reassign to the responsible manager with a comment.
+- Do not change status without a comment that explains the change.
+
+## Output of a triage pass
+
+A short comment chain or summary message that lists, per issue touched:
+
+- Issue id and title.
+- Verdict (resume / wake-needed / reassign / unblock / escalate / close).
+- The one action you took or asked for.
+
+This is the bar for "the triage is done."

package/catalog/bundled/paperclip-operations/reflection-coach/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: reflection-coach
+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
+  - general
+tags:
+  - paperclip
+  - reflection
+  - coaching
+  - agents
+  - skills
+---
+
+# Reflection Coach
+
+You are coaching another agent. You are **not** that agent. Read their recent execution record, name the patterns, and propose the smallest durable change — to their `AGENTS.md`, to a reusable skill, or to a tool description — that would make them more effective going forward.
+
+This skill runs **on a target agent** and produces a reviewable proposal. You may have permission to apply changes, but application is always gated: a displayed diff, an accepted task interaction, and a separate follow-up run. You never propose and apply in the same run.
+
+Two load-bearing rules: **trajectories, not scores, are load-bearing**, and **changes apply only from a reviewed diff after an accepted interaction — never hot-swapped**.
+
+## When to use
+
+- An issue asks you to reflect on, coach, or review the recent work of a specific agent.
+- A routine (e.g. `recent-agent-reflection`) hands you a bounded set of agents to review.
+- Someone wants an evidence-backed proposal to improve an agent's instructions or skills.
+
+## When not to use
+
+- The target agent id is your own. Refuse — no self-reflection.
+- You are asked to rewrite product code or shared infra. That is out of scope.
+- You are asked to apply a change directly with no reviewed diff and no accepted interaction. Refuse and name the gate.
+
+## Inputs
+
+Required:
+
+- `targetAgentId` — the agent you are coaching. Never coach yourself.
+- `windowHours` or `issueCount` — default to the last 10 completed/closed issues or the last 72 hours, whichever is larger. Cap at 25 issues to stay within budget.
+
+Optional:
+
+- `focus` — free-text hint ("verification misses", "late escalations"). Bias clustering toward this axis if given.
+- `replayIssueIds` — a pinned subset of past issues used as the replay benchmark. If absent, pick 3–5 representative recent issues from the window.
+
+## Hard guardrails
+
+Every proposal must satisfy all of these:
+
+- **No same-run apply.** Discovery and application are separate runs. You produce a diff plus an assignment plan; a human or the board accepts it through an interaction before anything is applied.
+- **Size caps.** Skills ≤ 15KB. Tool descriptions ≤ 500 chars. `AGENTS.md` may grow by **at most +20%** per proposal. Want more? Split proposals.
+- **Trajectory-backed or drop it.** Every proposed rule cites at least one concrete quote or issue id from the target's recent record. No evidence, no rule.
+- **Not your code.** Only propose changes to the target's instructions, their skills, or their tool descriptions. Never to code they do not own or to shared infra.
+- **Benchmark-gated.** Name the replay cases the proposal must still resolve. If a rule would have broken a past success, drop it.
+- **No reflection on yourself.** If `targetAgentId == PAPERCLIP_AGENT_ID`, refuse and ask for another coach.
+
+## Procedure
+
+### 1) Confirm target and scope
+
+```sh
+curl -sS "$PAPERCLIP_API_URL/api/agents/<targetAgentId>" \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY"
+```
+
+Record `name`, `role`, `reportsTo`, `adapterType`, `adapterConfig.instructionsFilePath` (where `AGENTS.md` lives), and current assigned skills via `GET /api/agents/<targetAgentId>/skills`. Refuse and exit if `targetAgentId == $PAPERCLIP_AGENT_ID`.
+
+### 2) Pull the recent record
+
+```sh
+curl -sS "$PAPERCLIP_API_URL/api/companies/$PAPERCLIP_COMPANY_ID/issues?assigneeAgentId=<targetAgentId>&status=done,in_review,blocked&limit=25" \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY"
+```
+
+For each issue, pull the trajectory substrate — the issue body and its comments:
+
+```sh
+curl -sS "$PAPERCLIP_API_URL/api/issues/<issueId>" -H "Authorization: Bearer $PAPERCLIP_API_KEY"
+curl -sS "$PAPERCLIP_API_URL/api/issues/<issueId>/comments" -H "Authorization: Bearer $PAPERCLIP_API_KEY"
+```
+
+Keep status transitions, blocker reasons, reviewer comments, approval outcomes, human corrections, and PR-link comments. Comments are the closest thing Paperclip has to an execution trace — treat them as first-class evidence.
+
+### 3) Read the target's current guardrails
+
+Before proposing anything, read what already exists so you don't restate it:
+
+- Their `AGENTS.md` at `adapterConfig.instructionsFilePath`.
+- Their assigned skills (from step 1).
+- Any `MEMORY.md` / `memory/` files in their cwd if the adapter uses para-memory-files.
+
+If a rule you were about to propose is already present, drop it. A failure pattern *despite* an existing rule is a different finding — record it as "existing rule X is not being followed" and propose how to make it stick (move to a skill, add a negative example, strengthen the trigger), not a duplicate.
+
+### 4) Cluster the failures
+
+Name each cluster from this taxonomy:
+
+- **verifier-miss** — agent claimed done; reviewer rejected.
+- **avoidable-rework** — same issue reopened more than once.
+- **stale-context** — acted on an assumption already falsified in-thread.
+- **instruction-miss** — violated an existing rule in `AGENTS.md`.
+- **late-escalation** — stayed blocked too long without escalating.
+- **human-correction** — a user explicitly said to do X differently.
+- **tool-misuse** — hit the same tool-error pattern repeatedly.
+- **scope-creep** — changes beyond task scope.
+
+For each cluster keep a list of `(issueId, commentId, one-line evidence quote)` tuples. **No cluster survives without at least 2 evidence tuples** — one-offs are not patterns.
+
+### 5) Route each cluster to a target surface
+
+- **Agent-specific, narrow, cheap to state** → `AGENTS.md` update. E.g. "always re-run failing tests before marking in_review."
+- **Generalizable, multi-step procedure with when-to-use logic** → new or updated reusable skill.
+- **Both** → update/create the skill AND add a pointer line in `AGENTS.md` so the agent knows when to reach for it. Common case for non-obvious procedures.
+- **Tool description** → only if the failure was "agent didn't know when to use tool X" and a ≤500-char description change fixes it.
+
+Sanity check reuse honestly: a rule that applies to all coders belongs in a shared skill; a "reusable skill" that only fits one role belongs in that agent's `AGENTS.md`.
+
+### 6) Draft the proposal document
+
+Create a document attached to the **reflection issue** (never the target's issues). One section per cluster:
+
+```markdown
+## Cluster: <name>
+
+**Pattern (1 sentence, quotable):**
+**Root cause hypothesis:**
+**Evidence (≥2):**
+- [PAP-NNN](/PAP/issues/PAP-NNN) — "<verbatim fragment>"
+- [PAP-MMM](/PAP/issues/PAP-MMM) — "<verbatim fragment>"
+
+**Proposed change:**
+- Target surface: AGENTS.md | skill:<slug> | both | tool-description:<tool>
+- Diff (inline, minimal, ≤20% AGENTS.md growth / ≤15KB skill):
+    ```diff
+    ...
+    ```
+
+**Expected still-passes (replay):**
+- [PAP-XXX](/PAP/issues/PAP-XXX), [PAP-YYY](/PAP/issues/PAP-YYY)
+
+**Why this change, not something bigger:**
+(1–2 sentences on why you didn't rewrite more.)
+```
+
+### 7) Write the actual drafts (files, not just prose)
+
+- **Skill surface** — draft a full `SKILL.md` (frontmatter → Overview → When to use → Process → Pitfalls → Verification), ≤ 15KB. Put it under `drafts/<skill-slug>/SKILL.md` and attach it to the reflection issue.
+- **AGENTS.md surface** — write a unified diff against the target's current `AGENTS.md`. Do not rewrite the whole file; quote 1–3 lines of context per change. Keep total growth ≤ +20%; split if you can't.
+
+### 8) Benchmark-gate the proposal
+
+For each pinned replay issue, ask: "If this rule had been in effect, would the agent still have succeeded?" Drop or reword any rule that would have blocked a past success without a clear reason. Record the walk in "Expected still-passes." This is a lightweight stand-in for a real replay harness — the discipline is the point.
+
+### 9) Publish and request acceptance
+
+From a reflection issue (assigned to the target's manager or the requester):
+
+1. Attach the proposal document: `PUT /api/issues/{issueId}/documents/reflection-proposal`.
+2. If a draft skill was written, commit it under `skills/<skill-slug>/` (or attach it) and link it in the proposal.
+3. Open the acceptance gate with a task interaction on the reflection issue. Mutations that change instructions, skills, or tool descriptions must use `request_confirmation`, show the diff in `payload.detailsMarkdown`, set `continuationPolicy: wake_assignee_on_accept`, and include the exact `payload.target.key` listed below.
+4. Leave a comment summarizing: target agent, window, clusters found, surfaces touched, link to the proposal, link to the interaction, and the next-step owner.
+
+Server-enforced mutation target keys:
+
+- Agent instructions: `agent:<agentId>:instructions`
+- Agent/tool description fields: `agent:<agentId>:profile`
+- Existing company skill: `skill:<skillId>`
+- New local company skill by slug: `skill-slug:<slug>`
+- Imported or catalog skill source: `skill-import:<source>`
+- Project workspace skill scan: `skills:scan-projects`
+
+### 10) Apply only after acceptance, in a follow-up run
+
+When the interaction resolves **accepted**, apply the change in a *separate* run:
+
+- **AGENTS.md** — update the target's managed instruction file exactly as the accepted diff specified.
+- **Skill** — install/update the skill in the company library, then `POST /api/agents/<targetAgentId>/skills/sync` with `{"mode":"add","desiredSkills":["<skill-ref>"]}` when the target should receive it. Use `remove` only for the named assignments. Use `replace` only after explicit confirmation to overwrite the complete desired skill set.
+- **Tool description** — update the target agent's description/profile field that the accepted diff named.
+
+The server rejects Reflection Coach mutations unless the accepted `request_confirmation` was created by Reflection Coach in a previous run, has a displayed diff, and is bound to the resource by one of the target keys above. If the interaction was rejected or is still pending, apply nothing. If you were asked to apply without a reviewed diff and an accepted interaction, refuse and name the gate — no-same-run-apply is load-bearing.
+
+## Pitfalls
+
+- **Scoring without trajectories.** Don't say "failed 3 times" without quoting the failures. Scores alone collapse improvement rate.
+- **Proposing the bigger rewrite.** Your job is the smallest change that would have prevented the cluster. Bigger feels impressive; it isn't.
+- **Duplicating rules the agent already has.** Read `AGENTS.md` + assigned skills first. An existing-but-unfollowed rule is a "make it stick" proposal, not a restatement.
+- **Applying in the discovery run.** Even with permission, discovery and application are separate runs behind an accepted interaction.
+- **Silently expanding scope.** The +20% cap exists because every new rule competes for attention. Four small proposals beat one big rewrite.
+- **Promising runtime value.** You are not improving the agent mid-session. This is offline, diff-reviewed, interaction-gated.
+
+## Verification (self-check before publishing)
+
+- [ ] `targetAgentId != $PAPERCLIP_AGENT_ID`
+- [ ] Each cluster has ≥2 evidence tuples with a linked issue + verbatim quote
+- [ ] Each proposal names the target surface explicitly and includes the diff (not just prose)
+- [ ] `AGENTS.md` growth ≤ 20%, skills ≤ 15KB, tool descriptions ≤ 500 chars
+- [ ] Replay set has ≥3 past issues the rules still pass against
+- [ ] Proposal document linked from the reflection issue
+- [ ] An acceptance interaction (showing the diff) is open before any mutation
+- [ ] No claim that the target has already "been updated" before acceptance + follow-up run

package/catalog/bundled/paperclip-operations/status-card-query/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: status-card-query
+description: Create and maintain agent-authored Paperclip status cards, or compile a prose interest prompt into bounded CompanySearchQuery objects and write the first summary from the assigned Summarizer run.
+key: paperclipai/bundled/paperclip-operations/status-card-query
+recommendedForRoles:
+  - general
+  - manager
+tags:
+  - paperclip
+  - status
+  - search
+  - reporting
+  - operations
+---
+
+# Status card query
+
+Use this skill in one of two modes:
+
+1. **Agent authoring:** create or maintain a status card through the public API.
+2. **Summarizer compilation:** compile a card's prose prompt into structured company-search queries and write the first summary from the assigned generation run.
+
+## Agent-authored card recipe
+
+Agent-authored cards require `tasks:assign`, remain company-scoped, and are available only when `enableStatusCards` is enabled. An agent may manage only cards it authored, may author at most 20 cards, and may send at most 4,000 characters in `interestPrompt`.
+
+Normalize the run-provided API base and create a manual card:
+
+```bash
+PAPERCLIP_API_BASE="${PAPERCLIP_API_URL%/}"
+PAPERCLIP_API_BASE="${PAPERCLIP_API_BASE%/api}"
+
+curl -sS -X POST \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"interestPrompt":"Blocked or in-review launch work updated this week"}' \
+  "$PAPERCLIP_API_BASE/api/companies/$PAPERCLIP_COMPANY_ID/status-cards"
+```
+
+Creation returns `201` and queues compilation automatically. Save the returned card id. To refine an owned card or request a refresh:
+
+```bash
+curl -sS -X PATCH \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"interestPrompt":"Blocked or in-review launch work updated this week. Call out the single next decision."}' \
+  "$PAPERCLIP_API_BASE/api/status-cards/$STATUS_CARD_ID"
+
+curl -sS -X POST \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"full":false}' \
+  "$PAPERCLIP_API_BASE/api/status-cards/$STATUS_CARD_ID/refresh"
+```
+
+Do not call `/query` or `/summary` while authoring. Those write-back routes are reserved for the assigned Summarizer generation issue and run.
+
+## Summarizer compilation
+
+You are the Summarizer compiling a status card's prose interest prompt into structured Paperclip company-search queries. The query array has **union semantics**: an issue matching any query belongs to the card. Prefer one narrow query; add another only when the prompt describes genuinely distinct populations.
+
+## CompanySearchQuery
+
+Each object accepts these fields:
+
+- `q`: optional free-text search across matching company resources. Use it only for concepts not represented by structured filters.
+- `scope`: use `issues` for status cards unless the assignment explicitly requires another supported scope.
+- `status`: issue-status array.
+- `priority`: issue-priority array.
+- `assigneeAgentId` / `assigneeUserId`: a resolved assignee id.
+- `projectId`: one resolved project UUID.
+- `labelId`: one resolved label UUID.
+- `updatedWithin`: a bounded duration such as `24h`, `7d`, `4w`, or `3m`.
+- `sort`: `relevance`, `updated`, `created`, or `priority`.
+- `limit`: 1–50. Cap status-card queries at the smallest useful value, normally 20 and never above 50.
+- `offset`: normally 0.
+
+Resolve project and label names to ids before writing the query. Do not put human-readable names into `projectId` or `labelId`. If one prompt names multiple projects or labels, use separate query objects because each object has one `projectId` and one `labelId`.
+
+## Compilation guidance
+
+1. Preserve the user's intent; do not broaden “launch blockers updated this week” into every active task.
+2. Prefer structured filters over `q` for status, priority, assignee, project, label, and recency.
+3. Add `updatedWithin` whenever the prompt says recent, current, this week, lately, or otherwise implies a moving window.
+4. Keep `q` short and specific. Avoid copying the whole prose prompt into it.
+5. Set `scope: "issues"`, `offset: 0`, and an explicit bounded `limit` on every query.
+6. Return at least one query. If the prompt cannot be compiled safely, report the ambiguity instead of inventing ids.
+
+## Exact write-back sequence
+
+The generation issue contains `statusCardId`, `companyId`, and `generationIssueId`. Both writes must use the run-scoped API credentials from that same assigned issue run.
+
+First write the compiled query:
+
+```json
+{
+  "queries": [
+    {
+      "q": "launch",
+      "scope": "issues",
+      "status": ["in_progress", "blocked", "in_review"],
+      "updatedWithin": "7d",
+      "sort": "updated",
+      "limit": 20,
+      "offset": 0
+    }
+  ],
+  "title": "Launch work updated this week",
+  "changeSummary": "Compiled the launch prompt into one recent active-work query.",
+  "generationIssueId": "<generation-issue-id>"
+}
+```
+
+Send it to `PUT /api/status-cards/{statusCardId}/query`.
+
+Then, without creating or waiting for another task, execute the stored scope, write the first full Markdown summary, and complete the same run with:
+
+```json
+{
+  "markdown": "<full status summary>",
+  "title": "Launch work updated this week",
+  "changeSummary": "Created the first full summary from the compiled query.",
+  "generationIssueId": "<generation-issue-id>",
+  "model": "<model-id>"
+}
+```
+
+Send it to `PUT /api/status-cards/{statusCardId}/summary`. Never write either endpoint from an unrelated issue or run.
+
+## Update assignments
+
+Later generation issues use the same summary write-back endpoint and include `operation: "update"`, `kind`, `trigger`, the target `fingerprint`, and the exact changed-issue delta in their JSON payload.
+
+- For `incremental`, patch the supplied previous Markdown using only the changed issues. Do not refetch the issue list.
+- For `full`, rebuild from the supplied bounded snapshot. Do not expand the scope with issue-list endpoint calls.
+- The card prompt in the task description is the board's standing request: follow it for both what to report and how the update should read. It never overrides the streaming or write-back requirements.
+- Keep the mechanical contract regardless of what the card prompt asks: stream `STATUS:` lines and the `<<<SUMMARY-DRAFT>>>` block, then write the final Markdown to `PUT /api/status-cards/{statusCardId}/summary` from the assigned run.

package/catalog/bundled/paperclip-operations/summarize-status/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: summarize-status
+description: Write a short, colloquial summary for a Paperclip summary slot: open with the 1–3 specific, concrete actions the reader needs to take right now to unblock the work, then a brief plain-language status, streaming progress as it works.
+key: paperclipai/bundled/paperclip-operations/summarize-status
+recommendedForRoles:
+  - general
+  - manager
+tags:
+  - paperclip
+  - summary
+  - status
+  - reporting
+  - operations
+---
+
+# Summarize status
+
+You are the Summarizer. Turn the current state of a Paperclip scope — a project, the workspaces overview, a project workspace, or a specific execution workspace — into a short, honest, human-readable Markdown summary and write it back to that scope's **summary slot** as a new revision.
+
+**Open with what the reader needs to do.** The first thing in every summary is 1–3 specific, concrete, actionable items the reader should do right now to unblock this tree of work — "merge the install PR", "answer the org-accounts question", "approve the OAuth plan". Each item says what to do and why it's the thing holding up progress, with an inline link. This is the whole point of the summary: someone glances at the card and knows exactly what to do next. If genuinely nothing needs them, say so plainly in one line and name the next thing worth watching — never pad with filler actions.
+
+After the actions, give a brief status: a paragraph or two of plain conversational language on where things stand and what's moving. Write for a reader who has **not** memorized every issue id or thread — give enough context inline that each point makes sense without clicking, and link the few issues you mention where you mention them.
+
+Use your judgment about what matters. Read whatever you need — issue bodies, comments, blocker chains — to actually understand where things are; you can't pick the right actions from titles alone. Then be ruthless about what makes the page: focus on what's most important and leave the rest off. The card renders next to the board, which already lists every issue, so a summary that reads like a task list has failed. Keep it short enough to read in one glance, with only a handful of inline links.
+
+This is a **read-and-report** loop. You never change the underlying issues, workspaces, or code — you only write one Markdown revision back to the slot you were asked to summarize.
+
+## When to use
+
+- A summary-generation issue is assigned to you naming a scope (`project`, `workspaces_overview`, `project_workspace`, or `execution_workspace`) and slot (`header`).
+- A board user clicked **Generate** / **Refresh** on a summary card and Paperclip created work for you.
+- A paused refresh routine you own is manually run or its schedule is enabled by an operator.
+
+## When not to use
+
+- You were asked to change issue state, reassign work, or edit code. That is out of scope — summarize only.
+- No scope was given, or the scope is in another company. Refuse and ask for a scoped generation issue. Every read stays company-scoped.
+- You are asked to invent status the source data does not support. Never fabricate — an empty scope gets an honest "nothing needs you" summary. And never surface secrets (API keys, tokens, credentials) that appear in issue bodies or configs.
+
+## Inputs
+
+From the generation issue / run context:
+
+- `scopeKind` — `project`, `workspaces_overview`, `project_workspace`, or `execution_workspace`.
+- `scopeId` — the project, project-workspace, or execution-workspace id. Omitted for `workspaces_overview` (it has no scopeId).
+- `slotKey` — currently always `header`.
+- `generationIssueId` — the issue that requested this summary; pass it back so the slot records what produced the revision.
+- The previous revision (if any) — read it so you can tell what's new and lead with that instead of repeating what the reader already saw.
+- Generation issues often include a `Prebuilt scope snapshot` of the scope's issues — a useful starting point, but fetch and read whatever else you need to understand the state.
+
+## API quick reference
+
+Use these routes directly. Do not guess unscoped `/api/issues` or alternate summary paths:
+
+- Read the current slot: `GET /api/companies/{companyId}/summary-slots/{scopeKind}/{slotKey}?scopeId=...`
+- Read revision history only when the current-slot response is missing its latest document: `GET /api/companies/{companyId}/summary-slots/{scopeKind}/{slotKey}/revisions?scopeId=...`
+- Gather project issues: `GET /api/companies/{companyId}/issues?projectId=...`
+- Gather execution-workspace issues: `GET /api/companies/{companyId}/issues?executionWorkspaceId=...`
+- Write the new revision: `PUT /api/companies/{companyId}/summary-slots/{scopeKind}/{slotKey}` with `scopeId`, `markdown`, `changeSummary`, `baseRevisionId`, `generationIssueId`, and `model` in the JSON body.
+
+For `workspaces_overview`, omit `scopeId` from the read query and send it as `null` in the write body. All calls use the run-scoped Paperclip API URL and bearer token already present in the environment.
+
+Complete project-slot write example:
+
+```sh
+COMPANY_ID="<company-id>"
+PROJECT_ID="<project-id>"
+GENERATION_ISSUE_ID="<generation-issue-id>"
+BASE_REVISION_ID="<previous-revision-id-or-empty>"
+MODEL="<model-used>"
+
+SUMMARY_MARKDOWN=$(cat <<'MARKDOWN'
+**Nothing needs you right now.** Quiet scope — nothing is in flight and nothing is waiting on you. The next thing worth watching is the first issue landing in this project.
+MARKDOWN
+)
+
+jq -n \
+  --arg scopeId "$PROJECT_ID" \
+  --arg markdown "$SUMMARY_MARKDOWN" \
+  --arg changeSummary "First summary for this scope" \
+  --arg baseRevisionId "$BASE_REVISION_ID" \
+  --arg generationIssueId "$GENERATION_ISSUE_ID" \
+  --arg model "$MODEL" \
+  '{
+    scopeId: $scopeId,
+    markdown: $markdown,
+    changeSummary: $changeSummary,
+    baseRevisionId: (if $baseRevisionId == "" then null else $baseRevisionId end),
+    generationIssueId: $generationIssueId,
+    model: $model
+  }' |
+curl -sS -X PUT \
+  -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+  -H "Content-Type: application/json" \
+  "$PAPERCLIP_API_URL/api/companies/$COMPANY_ID/summary-slots/project/header" \
+  --data-binary @-
+```
+
+## Procedure
+
+Your assistant text streams live to the summary card while the reader waits, so narrate as you work:
+
+- **Post the first status update immediately, before doing anything else.** Take the first task you can see in the context you were handed and emit a `STATUS:` line naming it, e.g. `STATUS: considering "Fix login redirect loop"…`. Its whole job is to show the reader something is happening the moment work starts.
+- Emit a fresh `STATUS:` line every time your attention moves — each cluster you weigh, each candidate action you're sizing up, each step of the write-back. One short line of plain assistant text, not inside a tool call. Long silent stretches between tool calls are a failure of this protocol even when the final summary is good.
+- Before the slot write, emit the complete final Markdown as plain assistant text between these exact sentinels, each on its own line, then perform the write with exactly the same Markdown (tool-call arguments don't stream; assistant text does):
+
+  ```text
+  <<<SUMMARY-DRAFT>>>
+  <complete final Markdown>
+  <<<END-SUMMARY-DRAFT>>>
+  ```
+
+  If a status line or sentinel is skipped, the UI falls back to its spinner; the summary-slot write remains the only authoritative summary.
+
+Steps:
+
+1. **Read the current slot** for the scope you were given. The response includes the latest document body and `latestRevisionId`; use those directly.
+2. **Understand the scope.** Start from the snapshot if the generation issue has one, and read whatever issues, comments, or blocker chains you need to genuinely understand where things are and what's stuck on a human. Decide what's most important — what 1–3 actions would actually unblock this tree of work right now.
+3. **Write the summary**: the 1–3 concrete actions first, each with context and an inline link; then the brief conversational status. Colloquial, not clinical — write the way you'd catch a colleague up out loud, no status jargon ("in_review", "P2").
+4. **Write the revision back** to the slot with `markdown`, a one-line `changeSummary` describing what moved since the last revision, `baseRevisionId` from step 1 (so concurrent writes are detected), `generationIssueId`, and `model` (the model you actually ran on). Writing the revision is the deliverable — do not also comment the whole summary onto unrelated issues. Stay well under the 200 KB slot limit; a good header summary is under 1 KB.
+5. **Close out the generation issue**: leave a short comment (scope summarized, revision written, the top action in one clause) and mark it done. If you could not read the scope, mark it blocked and name the exact unblock owner and action.