Skills
skills/sillsdev/fieldworks/atlassian-readonly-skills

atlassian-readonly-skills

SKILL.md

Atlassian Readonly Skills

Read-only Python utilities for Jira, Confluence, and Bitbucket integration, supporting both Cloud and Data Center deployments.

Note: This is a read-only variant that excludes all write operations (create, update, delete). For full functionality including write operations, use atlassian-skills.

FieldWorks / SIL JIRA Integration

LT-prefixed tickets (e.g., LT-22382, LT-19288) are JIRA issues from SIL's JIRA instance:

  • Base URL: https://jira.sil.org
  • Browse URL: https://jira.sil.org/browse/LT-XXXXX
  • Project key: LT (Language Technology)

Trigger patterns: Use this skill when you see:

  • LT-prefixed identifiers in user queries, code comments, commit messages, or git log output
  • References to jira.sil.org URLs
  • Requests to "look up" or "check" a JIRA ticket

⚠️ Critical: Always Use Python Scripts

NEVER attempt to:

  • Browse to jira.sil.org URLs directly (requires authentication)
  • Use fetch_webpage or similar tools on JIRA URLs
  • Use GitHub issue tools for LT-* tickets

ALWAYS use these Python modules. The scripts are Python modules (not CLI tools), so use them via inline Python or import:

# Get a single issue (inline Python one-liner)
python -c "import sys; sys.path.insert(0, '.github/skills/atlassian-readonly-skills/scripts'); from jira_issues import jira_get_issue; print(jira_get_issue('LT-22382'))"

# Search for issues (JQL query)
python -c "import sys; sys.path.insert(0, '.github/skills/atlassian-readonly-skills/scripts'); from jira_search import jira_search; print(jira_search('project = LT AND status = Open'))"

# Get issue workflow transitions
python -c "import sys; sys.path.insert(0, '.github/skills/atlassian-readonly-skills/scripts'); from jira_workflow import jira_get_transitions; print(jira_get_transitions('LT-22382'))"

Use the script modules in this skill directly.

Configuration

Two configuration modes are supported:

Mode 1: Environment Variables (Traditional)

Set environment variables based on your deployment type. This mode is used when credentials parameter is not provided to skill functions.

SIL JIRA (Data Center / PAT Token)

# SIL JIRA instance for LT-* tickets
JIRA_URL=https://jira.sil.org
# Personal Access Token - generate at: https://jira.sil.org/secure/ViewProfile.jspa → Personal Access Tokens
JIRA_PAT_TOKEN=your_jira_pat_token_here

Cloud (API Token)

# Jira Cloud
JIRA_URL=https://your-company.atlassian.net
JIRA_USERNAME=your.email@company.com
JIRA_API_TOKEN=your_api_token

# Confluence Cloud
CONFLUENCE_URL=https://your-company.atlassian.net/wiki
CONFLUENCE_USERNAME=your.email@company.com
CONFLUENCE_API_TOKEN=your_api_token

Generate API tokens at: https://id.atlassian.com/manage-profile/security/api-tokens

Data Center / Server (PAT Token)

# Jira Data Center
JIRA_URL=https://jira.your-company.com
JIRA_PAT_TOKEN=your_pat_token

# Confluence Data Center
CONFLUENCE_URL=https://confluence.your-company.com
CONFLUENCE_PAT_TOKEN=your_pat_token

# Bitbucket Server/Data Center
BITBUCKET_URL=https://bitbucket.your-company.com
BITBUCKET_PAT_TOKEN=your_pat_token

Note: PAT Token takes precedence if both are provided.

Mode 2: Parameter-Based (Agent Environments)

Alternatively, call the scripts in this skill directly.

Create credentials object

credentials = AtlassianCredentials( # Jira configuration jira_url="https://your-company.atlassian.net", jira_username="your.email@company.com", jira_api_token="your_api_token",

# Confluence configuration (optional)
confluence_url="https://your-company.atlassian.net/wiki",
confluence_username="your.email@company.com",
confluence_api_token="your_api_token",

# Bitbucket configuration (optional)
# bitbucket_url="https://bitbucket.your-company.com",
# bitbucket_pat_token="your_pat_token"

)

Check which services are available

availability = check_available_skills(credentials) print(availability["available_services"]) # ["jira", "confluence"] print(availability["unavailable_services"]) # {"bitbucket": "Missing bitbucket_url"}

Use skills with credentials parameter

result = jira_get_issue( issue_key="PROJ-123", credentials=credentials # Pass credentials here )


#### Partial Service Configuration

You can configure only the services you need. Services without complete credentials will be unavailable:

```python
# Only configure Jira
credentials = AtlassianCredentials(
    jira_url="https://your-company.atlassian.net",
    jira_username="your.email@company.com",
    jira_api_token="your_api_token"
)

# Jira skills will work
jira_get_issue("PROJ-123", credentials=credentials)  # ✓ Works

# Confluence/Bitbucket skills will fail with ConfigurationError
confluence_get_page("Page Title", "SPACE", credentials=credentials)  # ✗ Fails

For credentials object fields and authentication options, see the full documentation in atlassian-skills.

Core Workflow

Using Environment Variables

from scripts.jira_issues import jira_get_issue
from scripts.jira_search import jira_search
from scripts.confluence_pages import confluence_get_page
import json

# 1. Get a Jira issue
result = jira_get_issue(issue_key="PROJ-123")
issue = json.loads(result)
print(f"Issue: {issue['key']} - {issue['summary']}")

# 2. Search for issues
result = jira_search(
    jql="project = PROJ AND status = 'In Progress'",
    fields="summary,status,assignee",
    limit=50
)
issues = json.loads(result)

# 3. Get a Confluence page
result = confluence_get_page(title="Feature Documentation", space_key="DEV")
page = json.loads(result)
print(f"Page: {page['title']}")

Using Credentials Parameter (Agent Mode)

from scripts._common import AtlassianCredentials
from scripts.jira_issues import jira_get_issue
from scripts.jira_search import jira_search
from scripts.confluence_pages import confluence_get_page
import json

# Create credentials
credentials = AtlassianCredentials(
    jira_url="https://company.atlassian.net",
    jira_username="user@company.com",
    jira_api_token="token123",
    confluence_url="https://company.atlassian.net/wiki",
    confluence_username="user@company.com",
    confluence_api_token="token123"
)

# 1. Get a Jira issue with credentials
result = jira_get_issue(
    issue_key="PROJ-123",
    credentials=credentials
)
issue = json.loads(result)

# 2. Search for issues with credentials
result = jira_search(
    jql="project = PROJ AND status = 'In Progress'",
    fields="summary,status,assignee",
    limit=50,
    credentials=credentials
)

# 3. Get a Confluence page with credentials
result = confluence_get_page(
    title="Feature Documentation",
    space_key="DEV",
    credentials=credentials
)

Available Utilities

Jira Issue Management (scripts.jira_issues)

from scripts.jira_issues import jira_get_issue

# Get issue by key
jira_get_issue(
    issue_key="PROJ-123",
    credentials=credentials  # Optional
)

Jira Search (scripts.jira_search)

from scripts.jira_search import jira_search, jira_search_fields

# Search with JQL
jira_search(
    jql="project = PROJ AND status = 'In Progress'",
    fields="summary,status,assignee",
    limit=50
)

# Find field definitions
jira_search_fields(keyword="custom")

Jira Workflow (scripts.jira_workflow)

from scripts.jira_workflow import jira_get_transitions

# Get available transitions for an issue
jira_get_transitions(issue_key="PROJ-123")

Jira Agile (scripts.jira_agile)

from scripts.jira_agile import (
    jira_get_agile_boards,
    jira_get_board_issues,
    jira_get_sprints_from_board,
    jira_get_sprint_issues
)

# Get boards
jira_get_agile_boards(project_key="PROJ")

# Get issues on a board
jira_get_board_issues(board_id=1, jql="status = 'In Progress'")

# Get sprints from a board
jira_get_sprints_from_board(board_id=1, state="active")

# Get issues in a sprint
jira_get_sprint_issues(sprint_id=42)

Jira Links (scripts.jira_links)

from scripts.jira_links import jira_get_link_types

# Get available link types
jira_get_link_types()

Jira Worklog (scripts.jira_worklog)

from scripts.jira_worklog import jira_get_worklog

# Get worklog entries for an issue
jira_get_worklog(issue_key="PROJ-123")

Jira Projects (scripts.jira_projects)

from scripts.jira_projects import (
    jira_get_all_projects,
    jira_get_project_issues,
    jira_get_project_versions
)

# Get all projects
jira_get_all_projects()

# Get issues in a project
jira_get_project_issues(project_key="PROJ", limit=100)

# Get project versions
jira_get_project_versions(project_key="PROJ")

Jira Users (scripts.jira_users)

from scripts.jira_users import jira_get_user_profile

# Get user profile
jira_get_user_profile(user_identifier="user@company.com")

Confluence Pages (scripts.confluence_pages)

from scripts.confluence_pages import confluence_get_page

# Get page by title
confluence_get_page(title="Meeting Notes", space_key="TEAM")

# Get page by ID
confluence_get_page(page_id="12345")

Confluence Search (scripts.confluence_search)

from scripts.confluence_search import confluence_search

# Search with CQL
confluence_search(
    query="space = DEV AND type = page AND text ~ 'API'",
    limit=25
)

Confluence Comments (scripts.confluence_comments)

from scripts.confluence_comments import confluence_get_comments

# Get comments on a page
confluence_get_comments(page_id="12345")

Confluence Labels (scripts.confluence_labels)

from scripts.confluence_labels import confluence_get_labels

# Get labels on a page
confluence_get_labels(page_id="12345")

Bitbucket Projects (scripts.bitbucket_projects)

from scripts.bitbucket_projects import (
    bitbucket_list_projects,
    bitbucket_list_repositories
)

# List all projects
bitbucket_list_projects(limit=25)

# List repositories in a project
bitbucket_list_repositories(project_key="PROJ", limit=50)

Bitbucket Pull Requests (scripts.bitbucket_pull_requests)

from scripts.bitbucket_pull_requests import (
    bitbucket_get_pull_request,
    bitbucket_get_pr_diff
)

# Get PR details
bitbucket_get_pull_request(
    project_key="PROJ",
    repository_slug="my-repo",
    pr_id=123
)

# Get PR diff
bitbucket_get_pr_diff(
    project_key="PROJ",
    repository_slug="my-repo",
    pr_id=123
)

Bitbucket Files & Search (scripts.bitbucket_files)

from scripts.bitbucket_files import (
    bitbucket_get_file_content,
    bitbucket_search
)

# Get file content
bitbucket_get_file_content(
    project_key="PROJ",
    repository_slug="my-repo",
    file_path="src/main.py",
    branch="develop"
)

# Search code
bitbucket_search(
    query="def authenticate",
    project_key="PROJ",
    search_type="code",
    limit=25
)

Bitbucket Commits (scripts.bitbucket_commits)

from scripts.bitbucket_commits import (
    bitbucket_get_commits,
    bitbucket_get_commit
)

# Get recent commits from a branch
bitbucket_get_commits(
    project_key="PROJ",
    repository_slug="my-repo",
    branch="master",
    limit=10
)

# Get details of a specific commit
bitbucket_get_commit(
    project_key="PROJ",
    repository_slug="my-repo",
    commit_id="1da11eaec25aed8b251de24841885c91493b3173"
)

Response Data Structures

All functions return JSON strings with flattened data structures (not nested API responses).

Jira Issue Structure

{
  "key": "PROJ-123",
  "id": "10001",
  "summary": "Issue title",
  "description": "Issue description",
  "status": "In Progress",
  "issue_type": "Task",
  "priority": "High",
  "assignee": "user@company.com",
  "reporter": "reporter@company.com",
  "created": "2024-01-15T10:30:00.000+0000",
  "updated": "2024-01-16T14:20:00.000+0000",
  "labels": ["backend", "urgent"],
  "components": ["API", "Auth"],
  "custom_fields": {}
}

Confluence Page Structure

{
  "id": "12345",
  "title": "Page Title",
  "space_key": "DEV",
  "status": "current",
  "created": "2024-01-15T10:30:00.000Z",
  "updated": "2024-01-16T14:20:00.000Z",
  "author": "user@company.com",
  "version": 3,
  "url": "https://company.atlassian.net/wiki/spaces/DEV/pages/12345"
}

Note: These are simplified structures. The original Jira API returns nested data like {"key": "...", "fields": {"summary": "...", "status": {"name": "..."}}}, but this skill flattens it for easier use.

Error Handling

All functions return JSON strings. Check for errors:

import json

result = jira_get_issue(issue_key="PROJ-999")
data = json.loads(result)

if not data.get("success", True):
    print(f"Error: {data['error']}")
    print(f"Type: {data['error_type']}")
else:
    print(f"Issue: {data['key']}")

Error Types

  • ConfigurationError - Missing environment variables
  • AuthenticationError - Invalid credentials
  • ValidationError - Invalid input parameters
  • NotFoundError - Resource not found
  • APIError - Atlassian API error
  • NetworkError - Connection issues

Philosophy

This skill provides:

  • Read-Only Access: Query and retrieve data without modification
  • Token Efficiency: Reduced context size by excluding write operations
  • Safety: Prevents accidental data modifications
  • Flexibility: Support for both Cloud and Data Center deployments
  • Consistency: Unified error handling and response format

It does NOT provide:

  • Write operations (create, update, delete)
  • Direct API access (use the provided functions instead)
  • Webhook handling or event processing
  • Bulk import/export operations

Best practices:

  • Always check return values for errors
  • Use JQL/CQL for efficient searching
  • For write operations, use the full atlassian-skills package

Dependencies

pip install requests python-dotenv

Or use the requirements file:

pip install -r requirements.txt
Weekly Installs
15
Repository
sillsdev/fieldworks
GitHub Stars
103
First Seen
Mar 1, 2026
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykWarn
Installed on
opencode15
gemini-cli15
codebuddy15
github-copilot15
codex15
kimi-cli15