Status Card Query

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.

A status card lets you describe a slice of work in plain English — "blocked or in-review launch work updated this week" — and get a card that keeps itself current. This skill teaches an agent both halves of that: how to author a card in the first place, and how to turn its prose prompt into the bounded search queries that decide which issues the card actually covers, then write the first summary.

This is a bundled catalog skill — part of the bundled baseline kit. For how to install, audit, update, assign, and reset catalog skills, see the Skills reference.

Status cards are an experimental feature. The authoring routes are available only when enableStatusCards is turned on — see Status Cards for the feature itself and the Status Cards API for the full route reference.

When to use

• An agent wants a standing card for the work it watches, and needs to create one through the public API.
• An owned card's prompt is too vague or too broad, and you want to refine it or ask for a refresh.
• You are the Summarizer and a generation issue has been assigned to you naming a statusCardId.
• A later generation issue asks you to update an existing card's summary.

When not to use

• You are authoring a card. Don't call /query or /summary — those write-back routes belong to the assigned Summarizer run.
• The card was authored by someone else. An agent may manage only the cards it authored.
• The prompt names projects or labels you cannot resolve to ids. Report the ambiguity rather than inventing ids.

Catalog metadata

File inventory

Mode 1 — authoring a card

Agent-authored cards need the tasks:assign permission and stay company-scoped. Three limits keep them tidy:

• An agent may manage only the cards it authored.
• An agent may author at most 20 cards.
• An interestPrompt may be at most 4,000 characters.

The skill normalises the run-provided API base first, so the same snippet works whether PAPERCLIP_API_URL ends in /api or not, then creates the card:

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 on its own — you don't have to schedule anything. Keep the card id from the response. From there, PATCH /api/status-cards/{statusCardId} sharpens the prompt on a card you own, and POST /api/status-cards/{statusCardId}/refresh with {"full": false} asks for a refresh.

Mode 2 — compiling the prompt

As the Summarizer, your job is to turn the card's prose prompt into an array of Paperclip company-search queries. The array has union semantics: an issue that matches any query belongs to the card. So prefer a single narrow query, and add a second only when the prompt genuinely describes two distinct populations.

CompanySearchQuery fields

Resolve project and label names to ids before you write the query; human-readable names don't belong in projectId or labelId. Each query object holds one projectId and one labelId, so a prompt naming several projects or labels needs several query objects.

Compilation guidance

1. Preserve the intent. "Launch blockers updated this week" must not widen into every active task.
2. Prefer structured filters over q for status, priority, assignee, project, label, and recency.
3. Add updatedWithin whenever the prompt implies a moving window — recent, current, this week, lately.
4. Keep q short and specific. Don't paste 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 can't be compiled safely, report the ambiguity.

Writing back

The generation issue carries statusCardId, companyId, and generationIssueId, and both writes must use the run-scoped API credentials from that same assigned run. Never write either endpoint from an unrelated issue or run.

First the compiled query, via PUT /api/status-cards/{statusCardId}/query:

{
  "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>"
}

Then — without creating or waiting for another task — execute the stored scope, write the first full Markdown summary, and complete the same run with PUT /api/status-cards/{statusCardId}/summary:

{
  "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>"
}

Update assignments

Later generation issues reuse the same summary write-back endpoint. Their JSON payload adds operation: "update", plus kind, trigger, the target fingerprint, and the exact changed-issue delta.

• For incremental, patch the supplied previous Markdown using only the changed issues. Don't refetch the issue list.
• For full, rebuild from the supplied bounded snapshot. Don't expand the scope with issue-list endpoint calls.
• The card prompt in the task description is the board's standing request — follow it for what to report and how the update should read. It never overrides the streaming or write-back requirements.
• Keep the mechanical contract whatever 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.

See also

• Status Cards — the experimental feature this skill supports.
• Status Cards API — the full route and payload reference.
• Bundled skills — all bundled catalog skills grouped by category.
• Skills reference — file shape, install pipeline, catalog browse/install/audit/update/reset, assignment, and troubleshooting.
• App-shipped catalog — how bundled and optional catalog skills are versioned and kept current.
• Skills guide — the UI walkthrough and built-in catalog overview.