AgentSkillsCN

atlassian-search

使用 atlassian-cli 工具，在 Jira 和 Confluence 中搜索并检索信息。当用户需要查找问题、搜索文档、管理项目，或在 Atlassian 产品中跟踪冲刺进度时，可使用此技能。

SKILL.md
--- frontmatter
name: atlassian-search
description: Search and retrieve information from Jira and Confluence using the atlassian-cli tool. Use this skill to find issues, search documentation, manage projects, and track sprints in Atlassian products.

Atlassian Search Skill

This skill enables you to search and retrieve information from Jira and Confluence using the atlassian-cli command-line tool.

Prerequisites

Before using this skill, ensure:

  1. •Environment variables are set:
    • •ATLASSIAN_URL: Your Atlassian instance URL (e.g., https://your-domain.atlassian.net)
    • •ATLASSIAN_USERNAME: Your email address
    • •ATLASSIAN_API_TOKEN: Your API token
    • •ATLASSIAN_CLOUD: Set to true for Cloud, false for Server/DC (default: true)
    • •CONFLUENCE_BASE_PATH: Confluence API base path (default: /wiki)
  2. •The atlassian-cli binary is built and available in PATH

Available Commands

Jira Commands

1. Get Issue Details

Get detailed information about a specific Jira issue:

bash
atlassian-cli jira issue <issue-key>

Examples:

bash
# Get issue details in readable text format (default)
atlassian-cli jira issue PROJECT-123

# Get raw JSON output
atlassian-cli jira issue PROJECT-123 --format=json

2. Search Issues with JQL

Search for Jira issues using JQL (Jira Query Language):

bash
atlassian-cli jira search "<jql>" [--max=20] [--format=text|json]

Examples:

bash
# Find open issues in project
atlassian-cli jira search "project=DEV AND status=Open"

# Find issues assigned to current user
atlassian-cli jira search "assignee=currentUser() ORDER BY created DESC" --max=50

# Find recently created bugs
atlassian-cli jira search "issuetype=Bug AND created >= -7d"

# Get high priority issues
atlassian-cli jira search "priority=High AND status!=Done" --max=30

Common JQL Operators:

  • •project=<KEY>: Filter by project
  • •status=<Status>: Filter by status (Open, In Progress, Done, etc.)
  • •assignee=<user>: Filter by assignee (currentUser() for yourself)
  • •issuetype=<Type>: Filter by type (Bug, Task, Story, etc.)
  • •created >= -Nd: Issues created in last N days
  • •updated >= -Nd: Issues updated in last N days
  • •priority=<Priority>: Filter by priority (High, Medium, Low)
  • •labels=<label>: Filter by label
  • •ORDER BY <field> DESC/ASC: Sort results

3. List All Projects

Get a list of all accessible Jira projects:

bash
atlassian-cli jira projects [--format=text|json]

4. Get Project Issues

Get issues from a specific project:

bash
atlassian-cli jira project-issues <project-key> [--max=20] [--format=text|json]

Example:

bash
atlassian-cli jira project-issues DEV --max=50

5. List Agile Boards

Get a list of Scrum/Kanban boards:

bash
atlassian-cli jira boards [--type=scrum|kanban] [--max=50] [--format=text|json]

Examples:

bash
# List all boards
atlassian-cli jira boards

# List only Scrum boards
atlassian-cli jira boards --type=scrum

6. List Sprints

Get sprints from a specific board:

bash
atlassian-cli jira sprints <board-id> [--state=active|closed|future] [--format=text|json]

Examples:

bash
# List all sprints
atlassian-cli jira sprints 123

# List only active sprints
atlassian-cli jira sprints 123 --state=active

7. Get Sprint Issues

Get issues in a specific sprint:

bash
atlassian-cli jira sprint-issues <sprint-id> [--max=50] [--format=text|json]

8. Get Current User

Get information about the authenticated user:

bash
atlassian-cli jira user [--format=text|json]

Confluence Commands

1. Get Page Details

Get content of a specific Confluence page by ID:

bash
atlassian-cli confluence page <page-id> [--format=text|json]

Example:

bash
# Get page with ID 123456
atlassian-cli confluence page 123456

2. Search with CQL

Search Confluence using CQL (Confluence Query Language):

bash
atlassian-cli confluence search "<cql>" [--limit=10] [--format=text|json] [--full-content]

Examples:

bash
# Search pages in specific space
atlassian-cli confluence search "type=page AND space=DEV"

# Search with text query
atlassian-cli confluence search "siteSearch ~ \"important concept\""

# Search recent pages
atlassian-cli confluence search "created >= \"2024-01-01\" AND space=TEAM" --limit=20

# Search with full content
atlassian-cli confluence search "type=page AND space=DEV" --full-content

Common CQL Operators:

  • •type=page: Filter by content type
  • •space=<KEY>: Filter by space key
  • •siteSearch ~ "<text>": Full-text search
  • •text ~ "<text>": Title/content text search
  • •title ~ "<text>": Title search
  • •label=<label>: Filter by label
  • •created >= "<date>": Created after date (YYYY-MM-DD)
  • •lastModified >= "<date>": Modified after date
  • •creator=<user>: Filter by creator
  • •contributor=<user>: Filter by contributor

3. Simple Text Search

Easy-to-use text search (automatically converts to proper CQL):

bash
atlassian-cli confluence text-search "<query>" [--limit=10] [--format=text|json] [--full-content]

Examples:

bash
# Simple text search (shows preview by default)
atlassian-cli confluence text-search "情報セキュリティ" --limit=20

# Show full content
atlassian-cli confluence text-search "meeting notes" --full-content

# Get raw JSON
atlassian-cli confluence text-search "API documentation" --format=json

Note: Use --full-content to display complete page content (up to 2000 chars per page). Without this flag, only 200-character previews are shown.

4. List Spaces

Get a list of all accessible Confluence spaces:

bash
atlassian-cli confluence spaces [--limit=50] [--format=text|json]

5. Get Space Details

Get information about a specific space:

bash
atlassian-cli confluence space <space-key> [--format=text|json]

6. Get Child Pages

Get child pages of a specific page:

bash
atlassian-cli confluence children <page-id> [--limit=25] [--format=text|json] [--full-content]

7. Get Page Comments

Get comments on a specific page:

bash
atlassian-cli confluence comments <page-id> [--format=text|json]

8. Get Page Labels

Get labels/tags on a specific page:

bash
atlassian-cli confluence labels <page-id> [--format=text|json]

Output Formats

Text Format (Default)

Readable, formatted output with essential information:

Jira Issue:

code
Issue: PROJECT-123
Summary: Fix login bug
─────────────────────────────────────────

Status: In Progress
Type: Bug
Priority: High
Assignee: John Doe
Reporter: Jane Smith
Labels: backend, security
Created: 2024-11-15T10:30:00Z
Updated: 2024-11-20T14:45:00Z

Description:
─────────────────────────────────────────
Users are unable to login when...

Confluence Search Results:

code
Found 5 result(s):

[1] Information Security Rules

[2] Security Training Content
    ...

JSON Format

Raw API response for programmatic processing:

bash
atlassian-cli jira issue PROJECT-123 --format=json

Returns complete JSON with all fields from the API.

Usage Guidelines

When to Use This Skill

Use this skill when you need to:

  • •Find specific Jira issues or track their status
  • •Search for documentation in Confluence
  • •Review project progress and sprint planning
  • •Investigate problems mentioned in issues or pages
  • •Gather information for reports or summaries
  • •Track team activities and decisions

Best Practices

  1. •Use Specific Search Terms: Precise keywords yield better results
  2. •Leverage JQL/CQL: Use query languages for advanced filtering
  3. •Start with Text Format: Use --format=text for readability, --format=json for processing
  4. •Use --full-content Wisely: Only use for detailed content review to avoid overwhelming output
  5. •Combine Commands: Search broadly first, then drill down into specific items
  6. •Check Multiple Sources: Search both Jira and Confluence for comprehensive information

Common Use Cases

Finding Related Issues:

bash
# Search for bugs related to authentication
atlassian-cli jira search "issuetype=Bug AND text ~ \"authentication\""

Reviewing Sprint Progress:

bash
# List active sprints
atlassian-cli jira sprints 123 --state=active

# Get issues in sprint
atlassian-cli jira sprint-issues 456 --max=50

Finding Documentation:

bash
# Search Confluence for API docs
atlassian-cli confluence text-search "API documentation" --limit=10

# Get full page content
atlassian-cli confluence page 789012

Investigating Issues:

bash
# First, find the Jira issue
atlassian-cli jira search "text ~ \"database timeout\""

# Then, search related documentation
atlassian-cli confluence text-search "database configuration" --full-content

Tracking Team Work:

bash
# See what's assigned to you
atlassian-cli jira search "assignee=currentUser() AND status!=Done"

# Check recent updates
atlassian-cli jira search "updated >= -3d AND project=MYPROJECT" --max=30

Error Handling

Common Errors and Solutions

  1. •

    "ATLASSIAN_URL environment variable not set"

    • •Set the environment variable: export ATLASSIAN_URL=https://your-domain.atlassian.net
  2. •

    "Authentication failed"

    • •Verify your API token is valid
    • •Check that username (email) is correct
    • •Ensure token has not expired
  3. •

    "Permission denied"

    • •You don't have access to the requested resource
    • •Check project/space permissions with admin
    • •Ensure your account has appropriate licenses
  4. •

    "Resource not found"

    • •Verify issue key, page ID, or space key is correct
    • •Check spelling and format (e.g., "PROJECT-123" not "project123")
    • •Ensure resource exists and hasn't been deleted
  5. •

    "Connection error"

    • •Check network connectivity
    • •Verify ATLASSIAN_URL is correct (include https://)
    • •For Confluence, ensure CONFLUENCE_BASE_PATH is set correctly (default: /wiki)

Limitations

  • •Read-Only: This tool provides read-only access; cannot create or modify issues/pages
  • •Rate Limits: Atlassian APIs have rate limits; avoid rapid consecutive requests
  • •Permissions: Only retrieves resources your account has access to
  • •Content Length: Text format truncates very long content (use --format=json for complete data)
  • •Binary Formats: Cannot retrieve file attachments, only metadata

Tips for Effective Searching

Jira

  1. •Use Specific JQL: status=Open is better than searching all statuses
  2. •Order Results: Add ORDER BY created DESC to see newest first
  3. •Limit Scope: Filter by project or sprint to reduce noise
  4. •Use Labels: Search by labels for categorized issues
  5. •Date Ranges: Use relative dates like -7d for recent items

Confluence

  1. •Know Your Space: Search within specific spaces for faster results
  2. •Use Text Search: text-search is easier than writing CQL
  3. •Request Full Content: Use --full-content when you need complete information
  4. •Check Page Hierarchy: Use children command to explore page structure
  5. •Combine Searches: Search by keyword, then browse space or check labels

Integration with Workflows

This skill works well in combination with other tasks:

  • •Search Jira → Analyze status → Summarize progress → Create report
  • •Find Confluence docs → Extract information → Answer questions → Document findings
  • •Track sprint → Identify blockers → Suggest actions → Update stakeholders
  • •Search issues → Investigate patterns → Propose solutions → Generate recommendations
  • •Browse documentation → Compile knowledge → Create summaries → Share insights

API Token Setup

To use this skill, you need an Atlassian API token:

  1. •Go to https://id.atlassian.com/manage-profile/security/api-tokens
  2. •Click "Create API token"
  3. •Give it a descriptive name (e.g., "Claude CLI")
  4. •Copy the token immediately (you won't see it again)
  5. •Set environment variable: export ATLASSIAN_API_TOKEN=<your-token>

Security Note: Keep your API token secure. Do not commit it to version control or share it publicly.