From unblocked-skills
Structured, filtered issue retrieval via context_query_issues. Use this instead of context_search_issues when you need a precise filtered list — scoped by project and/or person — rather than semantic relevance matching. TRIGGER when: the user asks "what bugs are open in PROJECT", "what issues is Alice working on", "list in-progress tickets for the payments team", "issues I filed last month"; you need a definitive list rather than a ranked set of relevant items; you already know the project key or person's name and want to enumerate issues under that filter. DO NOT TRIGGER when: the question is conceptual ("is there an issue about X") or you don't have a project/person anchor — use context-search-issues for semantic matching instead.
How this skill is triggered — by the user, by Claude, or both
Slash command
/unblocked-skills:unblocked-context-query-issuesThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Structured issue retrieval. Calls `context_query_issues` with a natural-language query scoped by `--projects` and/or `--user-name` filters — producing a filtered list rather than a ranked semantic match set.
Structured issue retrieval. Calls context_query_issues with a natural-language query scoped by --projects and/or --user-name filters — producing a filtered list rather than a ranked semantic match set.
Sources: Jira, Jira Data Center, Linear, Asana, GitHub Issues.
context_query_issues has no MCP equivalent — it is CLI-only. It does not appear in the MCP tool list regardless of availability. Run command -v unblocked once per session and cache the result. Do not conclude the tool is unavailable from the MCP surface alone. See unblocked-tools-guide for full routing rules.
CLI (preferred):
unblocked context-query-issues --query "<your query>" [--projects PROJ_KEY another-project] [--user-name "Alice Smith"]
MCP fallback (only if CLI is confirmed unavailable): context_query_issues has no true MCP equivalent. context_research with instruction: "Prefer issue tracker results filtered by project and assignee; deprioritize code and messages" will return ranked results — not an enumeration. If the user's request depends on completeness ("list all…", "every open bug…"), stop and surface the CLI requirement rather than silently dropping matches. Use the fallback only for conceptual queries that happen to be scoped to issues.
If neither is available: stop and tell the user Unblocked is not configured in this environment (see unblocked-tools-guide for the full message). Do not substitute with raw Jira/Linear CLIs.
context-search-issuesBoth operate on the same issue tracker data, but they optimize for different questions:
| Use case | Use |
|---|---|
| "Is there an issue about this race condition?" (conceptual) | context-search-issues |
| "List open bugs in PAY project assigned to Alice" (filtered enumeration) | context-query-issues |
| "Has the Stripe webhook dedupe bug been reported?" (semantic match) | context-search-issues |
| "What did Alice complete last week in LINEAR?" (filtered activity) | context-query-issues |
If you don't have a concrete project key or person to filter on, use context-search-issues — context-query-issues shines when the filters are precise.
| Parameter | Required | Description |
|---|---|---|
query | Yes | Structured natural-language query describing the issues to retrieve. Include status, time range, and any intent not covered by projects/user-name. |
projects | No | One or more project names or keys to scope the search. CLI accepts multiple values: --projects PAY INFRA. |
user-name | No | Name or username of a person referenced in the query (assignee, creator, or reporter depending on query phrasing). |
Writing effective queries — lead with a clear list directive and use the filters for scope:
open, in-progress, resolved, closedlast week, since 2025-04-01, this sprintme in the query when the user says "I"/"my"; use the actual name via --user-name for other people| Instead of | Write |
|---|---|
bugs in payments | List open bugs in the PAY project, --projects PAY |
Alice's tickets | Show in-progress issues assigned to Alice, --user-name "Alice Smith" |
what I did | List issues I completed last week (with me implied) |
sprint items | List issues in the current sprint for the payments team, --projects PAY |
me)When the user says "I"/"my"/"me", put me directly in the query — do not pass --user-name me. Use --user-name only for other people.
Right:
query: "List issues I'm currently working on in the payments project", projects: ["PAY"]query: "Show issues assigned to Alice that are in-progress", user-name: "Alice Smith"Wrong:
user-name: "me" — does not resolve correctly; keep me inside the query stringSplit distinct filter sets into separate context-query-issues calls. Run in parallel when independent.
One query, two filters (diluted):
List open bugs in PAY assigned to Alice and also list issues in INFRA resolved this week.
Two parallel queries (focused):
Query 1:
query: "List open bugs",projects: ["PAY"],user-name: "Alice Smith"Query 2:
query: "List issues resolved this week",projects: ["INFRA"]
context-search-issuescontext-researchreferences/query-patterns.md — query examples organized by use caseGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub unblocked/skills --plugin unblocked-skills