| name | jira-config |
| description | Read and validate the jira block in .claude/project.json for jira-pack: required keys, defaults, working-repo resolution. NOT for talking to Jira itself (that's jira-tasks / the Atlassian MCP tools) and NOT for Confluence. |
| version | 0.1.0 |
| owner | swarmery-core |
| docs | {"status":"reviewed","source_sha":"0b1d68abed0c","updated":"2026-08-06T00:00:00.000Z"} |
Purpose
jira-pack runs with autonomy: auto — nobody is watching to answer a clarifying question.
Anything the ticket text doesn't spell out has to come from .claude/project.json, and if it's
missing the run must fail loudly with a fix-it message, never guess. This skill is that gate:
it reads the jira block, validates it, resolves defaults, and resolves which repo the run
operates against — before any other jira-pack skill or agent touches a ticket.
Source of truth
Read ${CLAUDE_PROJECT_DIR}/.claude/project.json, key jira, straight from the file. Never
infer these values from a ticket, a prompt, or a prior run — the schema at
overlays/_schema/project.schema.json (jira property) is the contract; this skill enforces it
at runtime.
Validation
Required: jira.baseUrl, jira.projectKey, jira.qaStatus, jira.repro.test.
If any of these is missing (key absent, empty string, or repro present without test):
stop immediately. Do not call Jira, do not fall back to a guess, do not proceed with a
partial config. Report exactly which keys are missing and hand back a ready-to-paste JSON
fragment for the consumer to drop into .claude/project.json, e.g.:
jira-config: missing required keys — jira.projectKey, jira.qaStatus
Paste this into .claude/project.json (fill in the placeholders):
"jira": {
"baseUrl": "<jira-base-url>",
"projectKey": "<PROJECT-KEY>",
"qaStatus": "QA",
"repro": { "setup": "npm ci", "test": "npm test" },
"budget": { "maxFiles": 5, "maxAttempts": 3 }
}
Only list the keys that are actually missing — don't reprint the whole fragment as if nothing
were configured when the config is partially there.
Working-repo resolution
Default: ${CLAUDE_PROJECT_DIR}. If the caller passes --repo <path>, use that path instead,
provided it exists and is a git repository (git -C <path> rev-parse --is-inside-work-tree
or equivalent) — otherwise stop and report the bad path, don't silently fall back to the
default. The resolved root is printed in the skill's own report and is what gets threaded into
the board card's prompt field downstream, so the executor agent operates against the same
repo this skill validated.
Documented limitation, not a missed case: there is no "Jira component → repository" mapping
in this iteration. One jira block resolves to exactly one working repo (default-or---repo);
multi-repo routing by ticket component is out of scope until a later phase adds it.
Defaults
budget.maxFiles = 5, budget.maxAttempts = 3 when budget (or either field) is absent —
chosen to match plugins/core/agents/debugger.md's own stop conditions (~5 files, 3 failed
attempts), so the orchestrator's budget never conflicts with the executor's internal limits.repro.setup is optional. Absent means the setup step is skipped — that is expected
behavior, not a validation failure. repro.test has no default; its absence is a hard stop
(see Validation above).
Placeholders / neutrality
Any example this skill prints uses only <jira-base-url> and <PROJECT-KEY> as placeholders.
Never print a real site host, project key, or team name — plugins/** must stay at zero hits
under scripts/scan-flavor.sh (docs/NEUTRALITY.md).
Related
overlays/_schema/project.schema.json — the jira block's JSON Schema (source of the
required-keys list above).overlays/example/project.json — a fully-populated neutral example of the block.plugins/core/skills/jira-tasks/SKILL.md — read-only Jira queries once a run is underway;
this skill only resolves and validates config, it never calls the Atlassian MCP tools itself.plugins/core/agents/debugger.md — source of the budget defaults above.
How to use
What it does
This skill reads the jira block from your project's .claude/project.json, checks that everything a run needs is actually there, and works out which repository the run will operate against. Because jira-pack runs unattended, nothing can be guessed at runtime — so this gate either hands back a validated config or stops the run with a message telling you exactly which keys to add.
When to use it
- Before any other jira-pack skill or agent touches a ticket, so a run never starts on a half-configured project.
- When a ticket run failed with a config complaint and you want the precise list of missing keys plus a paste-ready fix.
- When you are setting up jira-pack in a new project and want to confirm the
jira block is complete.
- When you need to know which repository a run will work in, including a
--repo <path> override.
When not to use it
- To read or search tickets — use the
jira-tasks skill, which handles read-only tracker queries.
- To verify that tracker access and credentials actually work — that is the
jira-access-preflight skill.
- To classify a ticket as a defect or a change — that is the
jira-triage skill.
- For Confluence pages of any kind; this skill only touches the local config file.
How to invoke
Skill(skill: "jira-pack:jira-config")
Call it first in a jira-pack run. It reads the config file itself, so you do not pass the values in.
Inputs
--repo <path> — an alternative working repository root — optional; must exist and be a git repository, otherwise the run stops..claude/project.json — the config file it reads, with a jira block holding baseUrl, projectKey, qaStatus, and repro.test as required keys — required.
What you get back
A short report naming the resolved working-repo root and the effective settings, including defaults it filled in (budget.maxFiles = 5, budget.maxAttempts = 3 when absent; a missing repro.setup simply skips the setup step). If a required key is missing, you instead get a hard stop listing only the keys that are actually absent, plus a JSON fragment with neutral placeholders to paste into your config. The resolved repo root is what downstream jira-pack steps operate against.
Worked example
Skill(skill: "jira-pack:jira-config")
→ jira-config: missing required keys — jira.projectKey, jira.qaStatus
Paste this into .claude/project.json (fill in the placeholders):
"jira": {
"projectKey": "<PROJECT-KEY>",
"qaStatus": "QA"
}
You add the two keys, run it again, and it reports a valid config with the working repo resolved to your project root.
Related
jira-access-preflight — run it right after this one to confirm the tracker itself is reachable.jira-triage — prefer it once config is valid and you need the ticket classified.jira-tasks — prefer it for read-only ticket queries during a run.
