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:

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

Use Specific Search Terms: Precise keywords yield better results
Leverage JQL/CQL: Use query languages for advanced filtering
Start with Text Format: Use --format=text for readability, --format=json for processing
Use --full-content Wisely: Only use for detailed content review to avoid overwhelming output
Combine Commands: Search broadly first, then drill down into specific items
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

"ATLASSIAN_URL environment variable not set"
- Set the environment variable: export ATLASSIAN_URL=https://your-domain.atlassian.net
"Authentication failed"
- Verify your API token is valid
- Check that username (email) is correct
- Ensure token has not expired
"Permission denied"
- You don't have access to the requested resource
- Check project/space permissions with admin
- Ensure your account has appropriate licenses
"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
"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

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

Confluence

Know Your Space: Search within specific spaces for faster results
Use Text Search: text-search is easier than writing CQL
Request Full Content: Use --full-content when you need complete information
Check Page Hierarchy: Use children command to explore page structure
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:

Go to https://id.atlassian.com/manage-profile/security/api-tokens
Click "Create API token"
Give it a descriptive name (e.g., "Claude CLI")
Copy the token immediately (you won't see it again)
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.

atlassian-search

Atlassian Search Skill

Prerequisites

Available Commands

Jira Commands

1. Get Issue Details

2. Search Issues with JQL

3. List All Projects

4. Get Project Issues

5. List Agile Boards

6. List Sprints

7. Get Sprint Issues

8. Get Current User

Confluence Commands

1. Get Page Details

2. Search with CQL

3. Simple Text Search

4. List Spaces

5. Get Space Details

6. Get Child Pages

7. Get Page Comments

8. Get Page Labels

Output Formats

Text Format (Default)

JSON Format

Usage Guidelines

When to Use This Skill

Best Practices

Common Use Cases

Error Handling

Common Errors and Solutions

Limitations

Tips for Effective Searching

Jira

Confluence

Integration with Workflows

API Token Setup