integration-jira
Connects Jira to AI agents for seamless issue tracking management.
Install
mkdir -p .claude/skills/integration-jira && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/16251" && unzip -o skill.zip -d .claude/skills/integration-jira && rm skill.zipInstalls to .claude/skills/integration-jira
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Connect Jira (Atlassian Cloud) to a self-hosted Hermes Agent over SSH so the agent can search, create, and update issues. Wires Atlassian's official remote MCP server (Rovo) with a static API token. Idempotent and rollback-safe. Works from Claude Code, Codex, Cursor, Hermes itself, and Gemini CLI.Key capabilities
- →Connect Jira (Atlassian Cloud) to a self-hosted Hermes Agent over SSH
- →Register the Hermes Agent with Atlassian's remote MCP server (Rovo)
- →Store Atlassian API tokens securely on the VPS
- →Reload the Hermes gateway for configuration changes
- →Verify Jira integration through logs and smoke tests
How it works
The skill connects Jira to a Hermes agent on a VPS via SSH by securely storing the API token, registering the agent with Atlassian's MCP server, and reloading the gateway. It includes idempotency checks and dry runs.
Inputs & outputs
When to use integration-jira
- →Creating Jira tickets
- →Searching issue backlogs
- →Updating ticket statuses
About this skill
/integration-jira — connect jira to Hermes over SSH
Compatibility: source-verified for Hermes 0.23.2, commit
ae2a81ccc00e9b7c06301523e5bb09608397149c. Host-installed default profile only. Vendor live validation is pending; source and sandbox tests do not prove a live connection.
Before you start — gather (ask once, in one batch)
| Variable | What | Where to get it |
|---|---|---|
$VPS_IP | IP/hostname of the VPS running Hermes | User's hosting dashboard |
$VPS_USER | SSH user (typically root) | User's hosting dashboard |
$ATLASSIAN_EMAIL | Email of the Atlassian account the agent acts as | The user's Atlassian account |
$JIRA_TOKEN | Atlassian API token (opaque string) | https://id.atlassian.com/manage-profile/security/api-tokens → Create API token |
The MCP server runs within that user's Jira permissions — pick the right account.
Also provide $JIRA_SITE=https://your-team.atlassian.net; this validates your Jira identity before configuring the native Atlassian OAuth MCP.
Use one shell session. DRY_RUN=1 runs the read-only gates and prints the plan, then exits before snapshot or configuration writes. FORCE=1 permits replacing existing MCP configuration after snapshot; existing native skill directories are always preserved.
Step 0 — shared remote, lifecycle and recovery helpers
# Run every block of this skill in ONE shell session: later steps call these functions.
# If your harness starts a fresh shell per command, re-run this block first.
SKILL_NAME=integration-jira
# Non-login ssh shells miss ~/.local/bin, where the Hermes installer puts `hermes`.
remote() { ssh -o BatchMode=yes "$VPS_USER@$VPS_IP" "export PATH=\"\$HOME/.local/bin:\$PATH\"; $*"; }
# gw_ready [SECONDS]: native readiness. Succeeds only when `gateway ensure --json` exits 0 and reports "state":"ready"
# (the transient pending/draining codes 5 and 6 are retried twice). It never greps `gateway status` text, because the stopped
# gateway prints "✗ Gateway is not running", which contains "running".
gw_ready() {
remote "T=${1:-60} bash -s" <<'REMOTE'
n=0
while :; do
out=$(hermes -p default gateway ensure --json --timeout "$T") && rc=0 || rc=$?
[ "$rc" = 0 ] && break
n=$((n + 1))
{ [ "$rc" = 5 ] || [ "$rc" = 6 ]; } && [ "$n" -lt 3 ] || { printf '%s\n' "$out" >&2; exit 1; }
sleep 3
done
case $out in *'"state":"ready"'*) printf '%s\n' "$out" ;; *) printf '%s\n' "$out" >&2; exit 1 ;; esac
REMOTE
}
# gw_reload: restart the default-profile gateway natively and require a ready gateway with a NEW instance_id.
# `--detach` keeps `restart` from running the gateway inside the ssh shell when no service is installed. With live
# sessions and no terminal, restart refuses; GW_INTERRUPT=1 adds -y and interrupts them deliberately (never set by default).
# Side effect: the pre-restart `ensure` read that captures the old instance_id STARTS a gateway when none is running (ensure never
# installs a service, but it does start one). A reload implies the gateway should run, so that is accepted; read-only skills never call gw_reload.
gw_reload() {
local old new out interrupt
interrupt=""
if [ "${GW_INTERRUPT:-0}" = 1 ]; then interrupt=1; fi
# Keep an endpoint identity even when ensure exits 6 (draining/restart_wait).
out=$(remote 'hermes -p default gateway ensure --json --timeout 10 2>/dev/null') || :
old=$(printf '%s\n' "$out" | sed -n 's/.*"instance_id":"\([^"]*\)".*/\1/p')
remote "hermes -p default gateway restart --detach${interrupt:+ -y}" \
|| { echo "gw_reload: gateway restart failed or was refused (live sessions? re-run with GW_INTERRUPT=1 only if interrupting them is acceptable)." >&2; return 1; }
out=$(gw_ready) || return 1
new=$(printf '%s' "$out" | sed -n 's/.*"instance_id":"\([^"]*\)".*/\1/p')
if [ -n "$old" ] && [ "$new" = "$old" ]; then echo "gw_reload: the gateway instance did not change, so it was not restarted." >&2; return 1; fi
printf '%s\n' "$out"
}
# snapshot: copy ~/.hermes/.env and config.yaml aside BEFORE the first write.
# The snapshot dir doubles as the "run in progress" marker that rollback looks for.
snapshot() {
remote "SKILL_NAME='$SKILL_NAME' bash -s" <<'REMOTE'
set -e
p="$HOME/.hermes/.hstack-backup"
d="$p/$SKILL_NAME"
# The active recovery point is published only after every artifact has been verified.
if [ -e "$d" ] || [ -L "$d" ]; then
echo "snapshot: $d exists — a previous $SKILL_NAME run did not finish. Run rollback first (restores the state before that run), then re-run." >&2
exit 1
fi
mkdir -p "$p" && chmod 700 "$p"
lock="$d.creating"
mkdir "$lock" 2>/dev/null || { echo "snapshot: another $SKILL_NAME snapshot is being created; retry after it finishes." >&2; exit 1; }
t=""
trap '[ -z "$t" ] || rm -rf "$t"; rmdir "$lock" 2>/dev/null || true' EXIT
[ ! -e "$d" ] && [ ! -L "$d" ] || { echo "snapshot: a recovery point appeared; nothing was written." >&2; exit 1; }
t=$(mktemp -d "$p/.snapshot-$SKILL_NAME.XXXXXX")
for f in .env config.yaml; do
if [ -f "$HOME/.hermes/$f" ]; then
cp -p "$HOME/.hermes/$f" "$t/$f"
cmp -s "$HOME/.hermes/$f" "$t/$f"
chmod 600 "$t/$f"
elif [ -e "$HOME/.hermes/$f" ] || [ -L "$HOME/.hermes/$f" ]; then
echo "snapshot: $f is not a readable regular file; nothing was written." >&2; exit 1
else
: > "$t/$f.absent"
chmod 600 "$t/$f.absent"
fi
done
for f in .env config.yaml; do
for entry in "$f" "$f.absent"; do
if [ -f "$t/$entry" ]; then cksum < "$t/$entry" > "$t/$entry.cksum"; chmod 600 "$t/$entry.cksum"; fi
done
done
printf 'hstack-snapshot-v1\n' > "$t/.complete"
chmod 600 "$t/.complete"
mv "$t" "$d"
[ -f "$d/.complete" ] && [ ! -d "$t" ] || { echo "snapshot: recovery-point publication failed; nothing was written." >&2; exit 1; }
t=""
REMOTE
}
# rollback: restore the exact pre-skill .env + config.yaml (so a FORCE=1 re-run that
# fails puts the previous working value back), reload the gateway with gw_reload, then retire the snapshot.
rollback() {
local rc=0
remote "SKILL_NAME='$SKILL_NAME' bash -s" <<'REMOTE' || rc=$?
set -e
trap 'echo "rollback: restoration failed; active snapshot retained for recovery." >&2' ERR
d="$HOME/.hermes/.hstack-backup/$SKILL_NAME"
[ ! -d "$d.creating" ] || { echo "rollback: snapshot creation is still in progress; retry later." >&2; exit 1; }
[ -d "$d" ] || { echo "rollback: no snapshot for $SKILL_NAME; nothing was written."; exit 10; }
# Incomplete legacy snapshots cannot prove that their final copy succeeded. Keep them for manual recovery.
[ -f "$d/.complete" ] && [ "$(cat "$d/.complete")" = hstack-snapshot-v1 ] \
|| { echo "rollback: snapshot is incomplete or legacy; active snapshot retained for manual recovery." >&2; exit 1; }
for f in .env config.yaml; do
count=0
for entry in "$f" "$f.absent"; do
if [ -f "$d/$entry" ]; then
count=$((count + 1))
[ -f "$d/$entry.cksum" ] || { echo "rollback: missing checksum for $f; active snapshot retained for recovery." >&2; exit 1; }
checksum=$(cksum < "$d/$entry")
expected_checksum=$(cat "$d/$entry.cksum")
[ "$checksum" = "$expected_checksum" ] \
|| { echo "rollback: corrupt backup for $f; active snapshot retained for recovery." >&2; exit 1; }
fi
done
[ "$count" = 1 ] || { echo "rollback: missing or ambiguous backup for $f; active snapshot retained for recovery." >&2; exit 1; }
done
for f in .env config.yaml; do
if [ -f "$d/$f" ]; then
cp -p "$d/$f" "$HOME/.hermes/$f"
cmp -s "$d/$f" "$HOME/.hermes/$f"
elif [ -f "$d/$f.absent" ]; then
rm -f "$HOME/.hermes/$f"
[ ! -e "$HOME/.hermes/$f" ] && [ ! -L "$HOME/.hermes/$f" ] || { echo "rollback: file removal failed; active snapshot retained." >&2; exit 1; }
else
echo "rollback: missing backup for $f; active snapshot retained for recovery." >&2
exit 1
fi
done
[ -f "$HOME/.hermes/.env" ] && chmod 600 "$HOME/.hermes/.env"
exit 0
REMOTE
[ "$rc" = 10 ] && return 0
[ "$rc" = 0 ] || return "$rc"
gw_reload >/dev/null \
|| { echo "rollback: files restored, but the gateway did NOT come back ready — active snapshot retained; inspect the gateway and retry rollback after resolving the fault" >&2; return 1; }
finish || return 1
echo "rollback: restored ~/.hermes/.env and config.yaml to their pre-$SKILL_NAME state."
}
# finish: mark the run successful; keep the snapshot as .prev for a manual undo.
finish() {
remote "SKILL_NAME='$SKILL_NAME' bash -s" <<'REMOTE'
set -e
trap 'echo "finish: could not retire the active snapshot; inspect the recovery point before continuing." >&2' ERR
d="$HOME/.hermes/.hstack-backup/$SKILL_NAME"
[ -d "$d" ] || exit 0
rm -rf "$d.prev"
[ ! -e "$d.prev" ] && [ ! -L "$d.prev" ] || { echo "snapshot retirement: previous destination remains; active snapshot retained." >&2; exit 1; }
mv "$d" "$d.prev"
[ ! -e "$d" ] && [ ! -L "$d" ] && [ -f "$d.prev/.complete" ] || { echo "snapshot retirement: move could not be verified; inspect the recovery point." >&2; exit 1; }
REMOTE
}
# Reject line breaks, quote/backslash characters and controls: values also become curl config lines.
secret_line_ok() {
[ -n "$1" ] && printf '%s' "$1" | LC_ALL=C grep -Eq '^[!-~]+$' || return 1
case "$1" in *'"'*|*"'"*|*'\'*) return 1 ;; esac
}
# No response body or credential is logged. JSON errors on HTTP 200 are failures too.
api_check() {
local reply
reply=$(remote 'curl -q -fsS --connect-timeout 10 --max-time 25 --config -' 2>/dev/null) || return 1
printf '%s' "$reply" | python3 -c 'import json,sys; d=json.load(sys.stdin); assert not (isinstance(d,dict) and (d.get("errors") or d.get("error") or d.get("success") is False))' 2>/dev/null
}
# Extra native-skill artifacts are owned separately; canonical rollback still restores env/config bytes.
restore_native_skill() {
remote "SKILL_NAME='$SKILL_NAME' bash -s" <<'REMOTE'
set -e
d="$HOME/.hermes/.hstack-backup/$SKILL_NAME"
p="$HOME/.hermes/skills/$SKILL_NAME-runtime"
[ -f "$d/native-created" ] || exit 0
---
*Content truncated.*
When not to use it
- →When connecting Jira Data Center/Server (not Atlassian Cloud)
- →When the user does not have SSH access to their VPS
- →When the user needs to connect a system other than Jira
Limitations
- →The skill connects Jira (Atlassian Cloud).
- →The skill connects to a self-hosted Hermes Agent over SSH.
- →The skill uses Atlassian's official remote MCP server (Rovo).
How it compares
This skill automates the secure and idempotent integration of Jira Cloud with a self-hosted Hermes agent via SSH, handling token storage and MCP registration, unlike a manual setup that could be error-prone.
Compared to similar skills
integration-jira side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| integration-jira (this skill) | 0 | 4mo | Caution | Advanced |
| tapd | 0 | 4mo | Review | Advanced |
| fc-assistant | 0 | 5mo | No flags | Advanced |
| linear | 0 | 6mo | No flags | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
You might also like
tapd
dd-xiaozhi
TAPD 统一入口 skill。工单拉取、共识管理、子任务回填、事件驱动同步。触发关键词:tapd、初始化、ticket sync、共识、Wiki 评审、子任务、工时回填、QA 通过、QA 打回、TAPD 事件、契约推送、同步工单、拉工单。
fc-assistant
wam-leadclic
Main orchestrator for the Salesforce functional consultant engagement lifecycle. Detects the current project phase, guides the consultant through the full engagement (from pre-workshop preparation to training materials), and invokes the appropriate skill at each stage. Entry point for all functional
linear
sushaantu
|
linear
tonkeeper
Retrieve Linear task context via Linear MCP for implementation work. Use when the developer needs requirements, scope, or acceptance criteria from a ticket.
linear
lobehub
Linear issue management guide. Use when working with Linear issues, creating issues, updating status, or adding comments. Triggers on Linear issue references (LOBE-xxx), issue tracking, or project management tasks. Requires Linear MCP tools to be available.
github-manage
matteocervelli
Manage operations concerning GitHub on behalf of user