菜单
Find issues by criteria (status, assignee, priority, etc.) using JQL. Create filters, export results to CSV/JSON, bulk update. Ideal for reporting and automation.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | jira-search-jql |
| description | Find issues by criteria (status, assignee, priority, etc.) using JQL. Create filters, export results to CSV/JSON, bulk update. Ideal for reporting and automation. |
| version | 1.0.0 |
| author | jira-assistant-skills |
| license | MIT |
| allowed-tools | ["Bash","Read","Glob","Grep"] |
Query and discovery operations for JIRA issues using JQL (JIRA Query Language).
| Operation | Risk | Notes |
|---|---|---|
| Query/search | - | Read-only |
| Validate JQL | - | Read-only |
| Export results | - | Read-only (local file) |
| List filters | - | Read-only |
| Create filter | - | Easily reversible (can delete) |
| Update filter | ! | Can be reverted |
| Share filter | ! | Can be unshared |
| Delete filter | !! | Filter lost, but can recreate |
| Bulk update | !! | Use --dry-run first; changes reversible but tedious |
Risk Legend: - Safe, read-only | ! Caution, modifiable | !! Warning, destructive but recoverable | !!! Danger, irreversible
# Find your open issues
jira-as search query "assignee = currentUser() AND status != Done"
# Find bugs in a project
jira-as search query "project = PROJ AND type = Bug AND status = Open"
# Export results to CSV
jira-as search export "project = PROJ" --output report.csv
# Save a filter for reuse
jira-as search filter create -n "My Bugs" -j "type = Bug AND assignee = currentUser()" -f
For detailed setup, see docs/QUICK_START.md.
IMPORTANT: Always use the jira-as CLI. Never run Python scripts directly.
| Command | Purpose | Example |
|---|---|---|
jira-as search query | Execute JQL queries | jira-as search query "project = PROJ" |
jira-as search export | Export to CSV/JSON | jira-as search export "JQL" -o report.csv |
jira-as search validate | Check JQL syntax | jira-as search validate "your query" |
jira-as search build | Build JQL from clauses | jira-as search build --clause "project = PROJ" --clause "status = Open" |
jira-as search bulk-update | Bulk update issues from search | jira-as search bulk-update "JQL" --add-labels bug --dry-run |
jira-as search suggest | Get field value suggestions | jira-as search suggest --field status --no-cache |
jira-as search fields | List available JQL fields | jira-as search fields --custom-only |
jira-as search functions | List available JQL functions | jira-as search functions --with-examples |
jira-as search filter list | List saved filters | jira-as search filter list --favourites |
jira-as search filter create | Save a reusable filter | jira-as search filter create --name "Name" --jql "JQL" |
jira-as search filter update | Update an existing filter | jira-as search filter update 10042 --name "New Name" |
jira-as search filter run | Run a saved filter | jira-as search filter run --id 10042 |
jira-as search filter favourite | Toggle favourite status | jira-as search filter favourite 10042 --add |
jira-as search filter share | Share filter with users/groups | jira-as search filter share 10042 --project PROJ |
jira-as search filter delete | Delete a saved filter | jira-as search filter delete 10042 --yes |
All commands support --help for full documentation.
| Option | Description |
|---|---|
--help, -h | Show help message and usage |
--output, -o | Output format: text (default), json |
--max-results, -m | Maximum results to return |
--fields | Comma-separated list of fields |
--show-links, -l | Show issue links in output |
--show-time, -t | Show time tracking info |
--show-agile, -a | Show agile fields (story points, sprint) |
--page-token, -p | Pagination token for large results |
# Basic search
jira-as search query "project = PROJ AND status = Open"
# With field selection
jira-as search query "project = PROJ" --fields key,summary,status,assignee
# With result limit
jira-as search query "project = PROJ" --max-results 50
# Validate syntax (--show-structure shows parse tree, --output for format)
jira-as search validate "project = PROJ AND status = Open"
jira-as search validate "project = PROJ" --show-structure
jira-as search validate "project = PROJ" --output json
# Build JQL from clauses (--operator selects AND or OR between clauses)
jira-as search build --clause "project = PROJ" --clause "status = Open" --validate
jira-as search build --clause "status = Open" --clause "status = Closed" --operator OR
jira-as search build --clause "assignee = currentUser()" --order-by created --desc
jira-as search build --template sprint-backlog # Use a predefined template
jira-as search build --list-templates # List available templates
# Get field suggestions
jira-as search suggest --field status
jira-as search suggest --field status --prefix "In"
jira-as search suggest --field assignee --prefix "john"
jira-as search suggest --field priority --no-cache # Skip cache
jira-as search suggest --field status --refresh # Refresh cached values
# List available fields and operators
jira-as search fields
jira-as search fields --custom-only # Only custom fields
jira-as search fields --system-only # Only system fields
jira-as search fields --filter priority # Filter by name
# List available JQL functions (-t is short for --type)
jira-as search functions
jira-as search functions -t list # Only list-returning functions
jira-as search functions --list-only # Only list-returning functions
jira-as search functions --with-examples # Include usage examples
# Create filter (use -n and -j options, or long forms --name and --jql)
jira-as search filter create -n "Sprint Issues" -j "sprint IN openSprints()" -f
jira-as search filter create -n "Team Filter" -j "project = PROJ" -d "Team issues" --share-project PROJ
# List filters
jira-as search filter list --favourites # Your favourite filters
jira-as search filter list --my # Your own filters
jira-as search filter list --search "Sprint" # Search by name
jira-as search filter list --owner "john@co.com" # By owner
jira-as search filter list --project PROJ # By project scope
jira-as search filter list --id 10042 # Get specific filter by ID
# Run filter (use --id or --name option)
jira-as search filter run --id 10042
jira-as search filter run --name "Sprint Issues"
jira-as search filter run --id 10042 --max-results 50 # Limit results
# Update filter
jira-as search filter update 10042 --name "New Name" --jql "updated JQL"
jira-as search filter update 10042 --description "New description"
# Toggle favourite status
jira-as search filter favourite 10042 --add
jira-as search filter favourite 10042 --remove
# Share filter
jira-as search filter share 10042 --project PROJ
jira-as search filter share 10042 --project PROJ --role Developers
jira-as search filter share 10042 --group jira-users
jira-as search filter share 10042 --global
jira-as search filter share 10042 --list # View current permissions
jira-as search filter share 10042 --unshare 10100 # Remove permission by ID (use --list first)
# Delete filter (use --yes to skip confirmation, --dry-run to preview)
jira-as search filter delete 10042 --dry-run # Preview deletion
jira-as search filter delete 10042 --yes # Skip confirmation
# Add labels to all matching issues (dry-run first!)
jira-as search bulk-update "project = PROJ AND status = Open" --add-labels needs-review --dry-run
jira-as search bulk-update "project = PROJ AND status = Open" --add-labels needs-review --yes
# Remove labels
jira-as search bulk-update "type = Bug AND labels = stale" --remove-labels stale --dry-run
# Change priority
jira-as search bulk-update "project = PROJ AND priority = Low" --priority Medium --dry-run
# Limit number of issues updated
jira-as search bulk-update "project = PROJ" --add-labels batch1 --max-issues 50 --dry-run
# CSV export
jira-as search export "project = PROJ" -o report.csv
# JSON export
jira-as search export "project = PROJ" -o data.json --format json
# Export specific fields
jira-as search export "project = PROJ" -o report.csv --fields key,summary,status,assignee
# Limit results
jira-as search export "project = PROJ" -o report.csv --max-results 500
# Run a query using a saved filter ID
jira-as search query --filter 10042
# Combine filter with additional criteria
jira-as search query --filter 10042 --max-results 100
# Save search results as a new filter
jira-as search query "project = PROJ" --save-as "My New Filter"
For large exports, optimize your query and field selection:
| Result Size | Recommendation |
|---|---|
| < 1000 | jira-as search export "JQL" -o file.csv |
| 1000-5000 | jira-as search export "JQL" -o file.csv --fields key,summary,status |
| > 5000 | Split by date ranges using created/updated filters |
# Large export with minimal fields for speed
jira-as search export "project = PROJ" -o report.csv --fields key,summary,status,assignee
# Split by time periods for very large datasets
jira-as search export "project = PROJ AND created >= -30d" -o recent.csv
jira-as search export "project = PROJ AND created >= -60d AND created < -30d" -o older.csv
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General error (API, validation) |
| 2 | Invalid arguments |
| 130 | User interrupted (Ctrl+C) |
Quick diagnostics:
jira-as search validate "your query" # Check syntax
jira-as search fields # List available fields
jira-as search suggest --field status # Get valid values for a field
jira-as search functions # List available JQL functions
For detailed troubleshooting, see references/TROUBLESHOOTING.md.
Requires JIRA credentials via environment variables (JIRA_SITE_URL, JIRA_EMAIL, JIRA_API_TOKEN).
| Document | Purpose |
|---|---|
| docs/QUICK_START.md | Get started in 5 minutes |
| references/jql_reference.md | JQL syntax reference |
| references/BEST_PRACTICES.md | Expert guide |
| references/TROUBLESHOOTING.md | Error solutions |
| assets/QUICK_REFERENCE.txt | Printable cheat sheet |
Pre-configured JQL templates:
assets/templates/jql_templates.json - Common search patternsassets/ERROR_SOLUTIONS.json - Error catalogJIRA automation hub routing to 13 specialized skills for any JIRA task: issues, workflows, agile, search, time tracking, service management, and more.
Epic creation and sprint management - create epics, manage sprints, view backlog, estimate with story points. TRIGGERS: 'create an epic', 'create epic', 'new epic', 'show the backlog', 'view backlog', 'add to sprint', 'move to sprint', 'set story points', 'sprint planning', 'epic for', 'link to epic', 'sprint list', 'active sprint', 'velocity', 'create subtask'. NOT FOR: bugs/tasks/stories without epic context (use jira-issue), field ID discovery (use jira-fields), searching issues by JQL (use jira-search), transitioning issues through workflow (use jira-lifecycle).
Bulk operations for multiple issues at scale. TRIGGERS: 'bulk update', 'bulk close', 'bulk transition', 'bulk assign', 'transition N issues' (N >= 10), 'update all bugs', 'close 50 issues', 'mass transition', 'update multiple issues', quantities like '50 issues', '100 bugs', '20+ tickets'. Use for operations on 10+ issues. NOT FOR: single issue transitions (use jira-lifecycle), searching only without modifications (use jira-search), single issue field updates (use jira-issue).
Git and developer workflow integration. TRIGGERS: 'generate branch name', 'create branch name', 'branch name for', 'write PR description', 'PR description for', 'link PR', 'link pull request', 'parse commit', 'extract issue from commit', 'smart commit', 'development panel'. Use for Git, GitHub, GitLab, Bitbucket integration with JIRA. NOT FOR: issue field updates (use jira-issue), searching issues (use jira-search), status transitions (use jira-lifecycle).
Custom field discovery and configuration. TRIGGERS: 'field ID for', 'what's the field ID', 'what is the field ID', 'list custom fields', 'what fields are available', 'what custom fields', 'show custom fields', 'customfield_', 'find field', 'agile fields', 'configure agile fields', 'story points field'. Use for JIRA field metadata and discovery. NOT FOR: setting field values on issues (use jira-issue), setting story points (use jira-agile), searching by field values (use jira-search).
Core JIRA issue CRUD - create bugs/tasks/stories, get issue details, update fields, delete issues. TRIGGERS: 'show me [KEY]', 'get issue [KEY]', 'view issue', 'create a bug/task/story', 'update [KEY]', 'delete [KEY]', 'details of [KEY]', 'look up [KEY]', 'what's in [KEY]'. NOT FOR: epics (use jira-agile), transitions/status changes (use jira-lifecycle), comments/attachments (use jira-collaborate), time tracking (use jira-time), bulk operations on 10+ issues (use jira-bulk), dependencies/blockers (use jira-relationships), branch names/PR descriptions (use jira-dev).