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:

atlassian-cli jira issue <issue-key>

Examples:

# 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):

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

Examples:

# 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:

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

4. Get Project Issues

Get issues from a specific project:

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

Example:

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

5. List Agile Boards

Get a list of Scrum/Kanban boards:

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

Examples:

# 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:

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

Examples:

# 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:

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

8. Get Current User

Get information about the authenticated user:

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

Confluence Commands

1. Get Page Details

Get content of a specific Confluence page by ID:

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

Example:

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

2. Search with CQL

Search Confluence using CQL (Confluence Query Language):

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

Examples:

# 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):

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

Examples:

# 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:

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

5. Get Space Details

Get information about a specific space:

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

6. Get Child Pages

Get child pages of a specific page:

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

7. Get Page Comments

Get comments on a specific page:

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

8. Get Page Labels

Get labels/tags on a specific page:

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

Output Formats

Text Format (Default)

Readable, formatted output with essential information:

Jira Issue:

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:

Found 5 result(s):

[1] Information Security Rules

[2] Security Training Content
    ...

JSON Format

Raw API response for programmatic processing:

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:

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

Reviewing Sprint Progress:

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

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

Finding Documentation:

# 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:

# 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:

# 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.