atlassian-usage

name	atlassian-usage
description	This skill should be used when the user asks to "search jira", "find tickets", "look up an issue", "search confluence", "find pages", "read a document", "create a ticket", "update an issue", "add a comment", mentions JQL, CQL, Atlassian, Jira issues, Confluence pages, or provides an Atlassian URL (*.atlassian.net). Provides guidance for using the atl CLI to interact with Atlassian products. Use when this capability is needed.
metadata	{"author":"dhughes"}

Atlassian CLI Usage

This skill provides guidance for using the atl CLI tool to interact with Jira and Confluence.

CRITICAL: Handling Atlassian URLs

NEVER attempt to fetch Atlassian URLs directly via web tools. Atlassian Cloud requires authentication that web fetch tools cannot provide. Instead, extract identifiers from URLs and use the atl CLI.

Jira URL Patterns

When a user provides a Jira URL, extract the relevant identifier and use atl:

URL Pattern	Extract	Command
https://*.atlassian.net/jira/software/projects/PROJ/boards/123	PROJ	atl jira search-jql "project = PROJ"
https://*.atlassian.net/jira/core/projects/PROJ/board	PROJ	atl jira search-jql "project = PROJ"

Examples:

• https://example.atlassian.net/jira/software/projects/PROJ/boards/5 → atl jira search-jql "project = PROJ"

Confluence URL Patterns

When a user provides a Confluence URL, extract the page ID and use atl:

URL Pattern	Extract	Command
https://*.atlassian.net/wiki/spaces/SPACE/pages/123456789/Page+Title	123456789	atl confluence get-page 123456789
https://*.atlassian.net/wiki/spaces/SPACE/overview	SPACE	atl confluence get-pages-in-space SPACE

Examples:

• https://example.atlassian.net/wiki/spaces/ENG/pages/987654321/Architecture → atl confluence get-page 987654321
• https://example.atlassian.net/wiki/spaces/TEAM/pages/123456789 → atl confluence get-page 123456789

URL Recognition Rules

1. Any URL containing .atlassian.net should trigger this skill
2. NEVER use WebFetch or similar tools on Atlassian URLs
3. Extract the identifier (issue key or page ID) from the URL
4. Use the appropriate atl command to retrieve the content

Overview

The atl CLI provides direct access to Jira and Confluence through their REST APIs. Use it for searching, reading, creating, and updating content in Atlassian products.

Discovering Commands

The atl CLI is actively developed and may have commands not covered in this skill. Always use --help to discover available commands and options:

atl --help
atl jira --help
atl confluence --help
atl jira <command> --help

Jira Operations

Searching Issues (JQL)

Search using Jira Query Language:

atl jira search-jql "project = PROJ AND status = 'In Progress'"
atl jira search-jql "assignee = currentUser() AND created >= -7d"
atl jira search-jql "text ~ 'keyword'" --max-results 20 --json

For detailed JQL syntax, see references/jql-reference.md.

Reading Issues

atl jira get-issue PROJ-123
atl jira get-issue PROJ-123 --json
atl jira get-issue PROJ-123 --fields summary,status,assignee

Creating Issues

atl jira create-issue --project PROJ --type Task --summary "Issue title"
atl jira create-issue --project PROJ --type Bug --summary "Bug title" \
  --description "**Details:** markdown supported"

The --description flag supports markdown formatting including headings, bold, italic, code blocks, and lists.

Updating Issues

atl jira edit-issue PROJ-123 --summary "New title"
atl jira edit-issue PROJ-123 --description "Updated description"
atl jira edit-issue PROJ-123 --assignee <account-id>

To find account IDs:

atl jira lookup-account-id "username or email"

Comments

atl jira add-comment PROJ-123 "Comment text with **markdown**"

Transitions

atl jira get-transitions PROJ-123
atl jira transition-issue PROJ-123 --transition "In Progress"

Issue Links

atl jira get-link-types
atl jira create-issue-link --inward PROJ-123 --outward PROJ-456 --type "Blocks"
atl jira get-issue-links PROJ-123

Project Information

atl jira get-projects
atl jira get-project-issue-types PROJ
atl jira get-create-meta --project PROJ --issue-type Task

Confluence Operations

Searching Pages (CQL)

Search using Confluence Query Language:

atl confluence search-cql "space = TEAM AND type = page"
atl confluence search-cql "title ~ 'Onboarding'"
atl confluence search-cql "text ~ 'documentation'" --limit 20 --json

For detailed CQL syntax, see references/cql-reference.md.

Reading Pages

Page IDs are numeric values found in page URLs or search results:

atl confluence get-page 123456789
atl confluence get-page 123456789 --json

Creating Pages

atl confluence create-page --space TEAM --title "Page Title" --body "Content"

Updating Pages

atl confluence update-page 123456789 --title "New Title"
atl confluence update-page 123456789 --body "Updated content"

Comments

atl confluence get-page-comments 123456789
atl confluence add-comment 123456789 "Comment text"
atl confluence create-inline-comment 123456789 --body "Inline comment"

Navigation

atl confluence get-spaces
atl confluence get-pages-in-space TEAM
atl confluence get-page-ancestors 123456789
atl confluence get-page-descendants 123456789

Output Formats

Most commands support --json for machine-readable output:

atl jira get-issue PROJ-123 --json | jq '.fields.status.name'
atl jira search-jql "project = PROJ" --json | jq '.[].key'

Common Workflows

Research a Topic

1. Search Jira for relevant tickets:

   atl jira search-jql "project = PROJ AND text ~ 'topic'"
   

2. Read promising tickets:

   atl jira get-issue PROJ-123
   

3. Search Confluence for documentation:

   atl confluence search-cql "text ~ 'topic'"
   

4. Read relevant pages:

   atl confluence get-page 123456789
   

Create and Track Work

1. Create the issue:

   atl jira create-issue --project PROJ --type Task --summary "Task name" \
     --description "Details here"
   

2. Transition to in progress:

   atl jira transition-issue PROJ-123 --transition "In Progress"
   

3. Add updates as comments:

   atl jira add-comment PROJ-123 "Progress update"
   

Authentication

Verify authentication status:

atl meta user-info

If not authenticated or authentication has expired:

atl auth

Additional Resources

Reference Files

For detailed query syntax, consult:

• references/jql-reference.md - Complete JQL syntax, fields, operators, and functions
• references/cql-reference.md - Complete CQL syntax for Confluence searches

Discovering New Features

The CLI is actively developed. To discover commands not covered here:

atl --help
atl jira --help
atl confluence --help
atl <product> <command> --help

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.