grandcamel/jira-assistant-skills

JIRA Assistant Skills

Natural language JIRA automation for Claude Code One thin skill points Claude at jira-as help — zero JQL memorization, zero skill sprawl.

Get Started • Skills • Use Cases • Architecture

---

The Difference

Time Saved

Typical developer: Save 30+ minutes per week. Team of 8: Reclaim 31 work days per year.

---

Quick Start

1. Clone the Repository

git clone https://github.com/grandcamel/jira-assistant-skills.git
cd jira-assistant-skills

2. Install Dependencies

pip install "jira-as>=2,<3"  # jira-as CLI from public PyPI

3. Get API Token

1. Visit Atlassian API Tokens
2. Create token → Copy it

4. Configure

export JIRA_API_TOKEN="your-token"
export JIRA_EMAIL="[email protected]"
export JIRA_SITE_URL="https://company.atlassian.net"

5. Start Using

# Just ask Claude
claude "Show me my open issues"
claude "Create a bug: Login button not working"
claude "What's blocking the release?"

# Or use the CLI directly -- run this first, it's the source of truth
jira-as help

jira-as issue get PROJ-123
jira-as search query "project = PROJ AND status = Open"
jira-as time log PROJ-123 --time 2h

That’s it. The plugin ships one skill (jira) that is deliberately thin: it just points Claude at jira-as help and jira-as api search/api describe to find and learn operations, so the skill never drifts out of sync with what the CLI actually supports. You can also use the jira-as CLI directly from your terminal.

Full Setup Guide →

---

Setup (Assistant Skills)

If you’re using the Assistant Skills plugin system, run the setup wizard:

/assistant-skills-setup

This configures:

• Shared Python venv at ~/.assistant-skills-venv/
• Required dependencies from requirements.txt
• Environment variables (prompts you to configure Jira credentials)
• claude-as shell function for running Claude with dependencies

After setup, use claude-as instead of claude:

claude-as  # Runs Claude with Assistant Skills venv activated

Environment Variables

Getting Your API Token

1. Go to Atlassian API Tokens
2. Click “Create API token”
3. Give it a descriptive label (e.g., “Claude Code Jira”)
4. Copy the token and add it to your shell config:

   export JIRA_API_TOKEN="your-token-here"
   export JIRA_EMAIL="[email protected]"
   export JIRA_SITE_URL="https://company.atlassian.net"
   

---

What You Can Do

flowchart LR
    subgraph Input["💬 You Say"]
        Q1["Show my highpriority bugs"]
        Q2["Create a storyfor login redesign"]
        Q3["What's blockingthe release?"]
    end

    subgraph Processing["🤖 Claude Understands"]
        P1["JQL: assignee=currentUser()AND type=BugAND priority>=High"]
        P2["create_issue.py--type Story--summary '...'"]
        P3["Search linked blockersTraverse dependency tree"]
    end

    subgraph Output["✅ You Get"]
        R1["📋 List of 7 bugswith details"]
        R2["🎫 PROJ-456 createdready to refine"]
        R3["🔍 3 blockers foundwith recommendations"]
    end

    Q1 --> P1 --> R1
    Q2 --> P2 --> R2
    Q3 --> P3 --> R3

---

The Jira Skill

There is one skill: jira (skills/jira/SKILL.md). It carries the Entry-Point Hint – a thin pointer, not a command reference – and nothing else:

1. Start every task with jira-as help: the surface map, groups, topics, auth and sandbox modes.
2. Find an operation with jira-as api search WORDS, read it with jira-as api describe OPERATION, run it with jira-as api call OPERATION.
3. For a known group, jira-as help GROUP; for a gotcha (ADF, paging, search, scope, risk, auth, migration, …), jira-as help TOPIC.
4. Discovery needs no credentials; calls need JIRA_SITE_URL, JIRA_EMAIL and JIRA_API_TOKEN. Risk-tagged calls preview by default; --confirm sends.

Every JIRA capability – issues, agile, search, time tracking, service management, bulk operations, and more – lives in the jira-as CLI itself, not in a table here. That is deliberate: a command table in this README would drift out of sync with the CLI exactly the way the old thirteen-skill hub did. Run jira-as help to see what is actually there.

Full CLI Reference →

---

Who Is This For?

---

Architecture

flowchart TD
    U["👤 User Request"] --> CC["🤖 Claude Code"]
    CC --> JS["📋 jira skillEntry-Point Hint"]
    JS -->|"jira-as help / api search / api describe"| CLI["🔧 jira-as CLI (2.x)"]
    CLI --> API["🔌 JIRA REST API"]
    API --> JIRA[("☁️ JIRA Cloud")]

One thin skill points at the CLI; the CLI carries the actual JIRA capability, its own error handling, config layering, ADF support, and retry behavior. See the jira-as repository for those internals – they are no longer duplicated here.

---

Quality & Security

Test Coverage

This repository is documentation-first: the CLI’s own unit tests (950+) live in the jira-as library repository. What lives here is:

See Testing for what runs in CI versus what is host-triggered and why.

Security

• No hardcoded secrets — API tokens stored in environment variables or gitignored files
• HTTPS-only connections — All JIRA API requests enforced over secure transport
• Input validation — All user data validated before API calls
• Credential isolation — settings.local.json gitignored by default
• No credential logging — Sensitive data excluded from logs and error output

---

Try It

One-click cloud environment with all dependencies pre-installed.

---

Documentation

Need Help?

• 💬 GitHub Discussions
• 🐛 Report Issues

---

E2E Testing: The Help-Only Sufficiency Arm

The end-to-end harness asks a narrower question now that there is one skill: is the Entry-Point Hint alone (skills/jira/SKILL.md) enough for a model to complete representative jira-as tasks? The model gets only the shipped plugin, the Bash tool, and jira-as in simulation transport with no credentials.

# Requires ANTHROPIC_API_KEY or `claude auth login`; host-run, not CI
pytest tests/e2e/ -v

See tests/e2e/README.md for the seven tasks, the isolation guarantees, and the pass thresholds.

Sandboxed Profile Testing

skills/jira/tests/test_sandbox_validation.py verifies that sandboxed tool-restriction profiles correctly limit what Claude can do. Set SANDBOX_PROFILE and CLAUDE_ALLOWED_TOOLS and run it directly:

SANDBOX_PROFILE=read-only \
CLAUDE_ALLOWED_TOOLS="Read Glob Grep WebFetch WebSearch Bash(jira-as issue get:*) Bash(jira-as search:*)" \
  pytest skills/jira/tests/test_sandbox_validation.py -v -k "readonly"

---

Contributing

Contributions are welcome! See our Contributing Guide.

# Clone the repository
git clone https://github.com/grandcamel/jira-assistant-skills.git
cd jira-assistant-skills

# Install dependencies and CLI
pip install "jira-as>=2,<3" pytest pytest-asyncio
pip install -e .  # Install the plugin package in editable mode

# Run tests (uses root pytest.ini configuration)
pytest skills/*/tests/*.py -v

# Verify CLI is working
jira-as --version
jira-as --help

---

Roadmap

• [x] Core JIRA operations (v1.0)
• [x] Agile workflow support (v1.1)
• [x] Service Management (v1.2)
• [x] Bulk operations (v1.3)
• [ ] GitHub integration enhancements
• [ ] Slack notifications
• [ ] Custom workflow templates

---

License

This project is licensed under the MIT License — see the LICENSE file for details.

---

Stop clicking through JIRA. Start talking to it.

Built for Claude Code by developers who were tired of memorizing JQL.