Guide · Agent skill
How to use the Status Card Query agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The status-card-query skill teaches an AI agent to create and maintain status cards in a Paperclip company workspace. A status card is a standing summary of work, such as blocked or in-review launch tasks, that is refreshed automatically. This guide explains what the skill does, how to install it, how to ask for a card in plain language, and what to check before you let an agent write to company data.
Status Card Querypaperclipai/paperclip · MIT Download the skill Quick start
- 1Confirm the deployment supports status cards. Check that your Paperclip deployment has enableStatusCards turned on and that the agent run has tasks:assign credentials.
- 2Install the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings, Capabilities, Skills in the Claude apps.
- 3Describe the report you want. Write a plain-English request that names the status, project or label and the time window, such as blocked launch work updated this week.
- 4Create the card. Let the agent send the create request. Save the returned card id, since later refinements and refreshes need it.
- 5Refine or refresh. Ask the agent to tighten the prompt or request a refresh. Only cards the agent authored can be changed.
- 6Review the summary. Check the Markdown summary the Summarizer writes and confirm the queries match what you asked for.
What the status-card-query skill makes the agent do
An agent skill is a folder containing a SKILL.md file with instructions that an AI agent reads when it is relevant to a task. This one covers two modes: agent authoring, where the agent creates or maintains a status card through the public API, and Summarizer compilation, where the agent turns a card's prose prompt into structured company-search queries and writes the first summary.
The agent turns a plain-English request such as blocked or in-review launch work updated this week into size-limited search queries against the company's issues. It then writes a Markdown summary back through the Paperclip API and updates it later. Later updates are either incremental, patching the previous Markdown using only changed issues, or full, rebuilding from a bounded snapshot.
- Creates a status card from a prose interest prompt
- Refines an owned card or requests a refresh
- Compiles the prompt into CompanySearchQuery objects
- Writes the first full Markdown summary and later updates
Install the status-card-query skill
Download the ZIP for this skill from this page. Then either unzip it into your personal skills folder at ~/.claude/skills/, or into a project's .claude/skills/ folder if you want the skill available only in that project.
If you use the Claude apps instead, upload the skill under Settings, then Capabilities, then Skills. Either way, the skill's SKILL.md file must be present in the skill folder for the agent to read it.
- Personal install: unzip into ~/.claude/skills/
- Project install: unzip into .claude/skills/ inside the project
- Claude apps: Settings, then Capabilities, then Skills, then upload
Check the requirements before you use it
The skill only works in a Paperclip deployment that has the enableStatusCards feature enabled. The agent run must provide agent credentials with the tasks:assign permission, along with the environment variables PAPERCLIP_API_KEY, PAPERCLIP_COMPANY_ID and PAPERCLIP_API_URL. The example API calls use curl, so curl must be available in the shell.
Cards are company-scoped. An agent may manage only cards it authored, may author at most 20 cards, and may send at most 4,000 characters in the interest prompt.
- Paperclip deployment with enableStatusCards turned on
- Agent credentials with tasks:assign permission
- PAPERCLIP_API_KEY, PAPERCLIP_COMPANY_ID and PAPERCLIP_API_URL provided by the run
- curl available in the shell
Create a status card with the API
The skill first normalizes the API base URL from PAPERCLIP_API_URL, removing a trailing slash and a trailing /api. It then sends a POST request to the company's status-cards endpoint with your prompt. Creation returns 201 and queues compilation automatically, so save the returned card id for later refinement.
To refine an owned card or request a refresh, the skill sends a PATCH to the card and a POST to its refresh route. The skill does not call the query or summary write-back routes while authoring; those are reserved for the assigned Summarizer generation issue and run.
- Normalize the base URL from PAPERCLIP_API_URL
- POST to /api/companies/{companyId}/status-cards to create
- PATCH /api/status-cards/{statusCardId} to refine
- POST /api/status-cards/{statusCardId}/refresh to request a refresh
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"Trigger the skill with natural requests
You do not need special syntax. Describe the standing report you want in plain language and say how often it should stay current. The agent turns that wording into a card prompt and compiles it into queries. The skill's guidance says to keep the intent intact, so a narrow request such as launch blockers updated this week should not become a report on every active task.
Words such as recent, current, this week or lately tell the agent to add a moving time window. Naming a project or label helps because the agent resolves those names to ids before querying.
- Create a card that lists blocked or in-review launch work updated this week
- Refine the card to call out the single next decision
- Refresh the card now with a full rebuild
- Summarize recently updated issues assigned to a specific agent
Understand how queries are built
Each query object can filter by status, priority, assignee, one project, one label, a time window such as 24h, 7d, 4w or 3m, and a sort order. Results are capped at 50, and status cards default to a small limit of about 20. Because each query object holds one project and one label, a prompt naming several projects needs several query objects. The array uses union semantics, so an issue matching any query belongs to the card.
The skill prefers structured filters over free text. The free-text q field is kept short and used only for concepts that filters cannot express.
- status, priority, assigneeAgentId or assigneeUserId, projectId, labelId, updatedWithin, sort, limit, offset
- limit is 1 to 50; offset is normally 0
- sort can be relevance, updated, created or priority
Safety notes before you enable it
The skill sends a bearer token with every request and writes to company data, and it runs scripts and makes network calls. Give the agent a run credential scoped to the minimum it needs, and avoid sharing one API key across agents. Do not use the skill where a card's key or run credentials are shared or over-scoped.
Writes are tied to the assigned generation issue and run. The skill is designed to refuse writes from unrelated issues or runs, so keep generation issues assigned to the agent you intend to use.
- Use a dedicated, minimally scoped API key per agent
- Review cards before relying on them for decisions
- Keep the 20-card and 4,000-character limits in mind when planning
What people use it for
- A weekly view of blocked or in-review launch tasks updated in the last seven days
- A standing summary of recently updated work assigned to one agent
- A card that calls out the next decision needed on a specific project
- An operator dashboard-style summary scoped to one company
Frequently asked questions
How do I install the status-card-query skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. In the Claude apps, you can upload it under Settings, Capabilities, Skills instead.
What do I need to run the status-card-query skill?
You need a Paperclip deployment with the enableStatusCards feature enabled, agent credentials with tasks:assign permission, and the PAPERCLIP_API_KEY, PAPERCLIP_COMPANY_ID and PAPERCLIP_API_URL variables provided by the run. curl must also be available in the shell.
Is the status-card-query skill free to use?
The source material for this skill does not state pricing or licence terms beyond the MIT licence noted for the repository. Check the licence and any Paperclip deployment terms yourself before relying on it.
What limits does the skill enforce?
An agent may author at most 20 cards and send at most 4,000 characters in the interest prompt. Each query is capped at 50 results, and status-card queries default to a smaller limit, normally 20.
Can I use this skill outside Paperclip?
No. The API endpoints and environment variables it uses only exist in Paperclip, so the skill is not useful in other systems.
Why does my card not update or fail to create?
Check that enableStatusCards is on, that the credentials include tasks:assign, and that the card prompt is within 4,000 characters. Also confirm the agent is only changing cards it authored.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if your team runs Paperclip and wants recurring, company-scoped summaries of blocked, in-review or recently updated work with clear size limits. Pick something else if you do not use Paperclip, need unrestricted data access, or cannot give the agent a tightly scoped credential, since it sends a bearer token with every request and writes to company data.
Download the skill