Pull a Jira issue into a local folder

One job: an issue key goes in, a folder of readable files comes out. One issue, one folder, everything in it — fields, comments, subtasks, worklogs, attachments, and any Confluence page the issue links to.

<skill-path> below is this skill's directory.

The seven rules

1. Pull only. This skill never creates, edits, transitions, comments on, assigns, or deletes anything in Jira. Every request reads: every REST call is a GET, and the one POST is a GraphQL query — the only way to read the deployment list, which no REST endpoint serves. Nothing here mutates anything. If the user wants a write, say so plainly and route to atlassian-rest — do not improvise it here.

2. Config first, and the config records the user's ticks. No .jira.config.json means run workflows/setup.md before anything else. Setup's five decisions — project, issue types, fields per type, board, output — are the user's, and each is settled by a box in a file that setup-choices.mjs generates from the API's own answer. The agent fetches the options and records what the user did — never narrowing a list, summarising it, or marking one option as recommended before they have seen all of it.

Only the starting state differs. Project, issue types, board and output arrive unticked, so a tick is the answer. A per-type fields file arrives fully ticked, because its options are the fields that issue type's screen shows — Jira's own answer to what the type holds — so keeping it all is the honest default and the user's job is to untick what they do not want. Either way their edit is the decision, and a fresh file is not one.

Setup also records one thing that is not a tick file: which of this site's custom fields fills each metadata row (project.metaFields). Propose that mapping from the field list already on screen, then let the user confirm it. An unmapped row is written —, never guessed.

3. One part per call. fetch-issue.mjs writes one document per run. Never reach for a single call that fetches everything: the parts are separate so each can be checked while it is still small enough to check.

4. Complete or failed, never partial. Every comment and every worklog entry is written. Any list read from the API is paged to the server's own total, and the count is asserted before the file is written. A file holding one page of a longer list is a failed pull, not a pull with a caveat. Never read a list out of fields=*all — that response is capped, silently.

The same rule decides when a pull is done: the folder is the evidence, not the report. An agent that says it finished, or that reports itself idle, has stated a hypothesis. Check the counts against Jira before believing it — and when many issues are in flight, stop the agent before reading its folder, because idle is reported while a write is still in flight.

5. Every document is versioned, and every JSON file is validated. Markdown declares schema: in its frontmatter; JSON declares $schema as its first key. In json or both mode, check-json.mjs must exit clean on every JSON file before the pull is reported done. A file that fails validation, or carries no $schema, is a failed pull. A pulled Confluence page is markdown in every mode, so check-markdown.mjs covers it and check-json.mjs never runs on it.

6. The format pass changes formatting, never words. Layout, headings, table syntax, list markers, unfilled boilerplate: all fair game. Wording, terminology, spelling, code, ids, dates, names, URLs: never. A ticket written in mixed languages, or with a typo in an acceptance criterion, stays exactly as written — that is what the ticket says. The one exception is image alt text, written from what the image shows. Detail in references/refactor-guide.md.

Within that boundary the target is a document a person can read, not a document the checker accepts. check-markdown.mjs covers what someone thought to automate, so a clean exit is the floor: the agent still reads the file as the reader will and fixes what renders wrong or breaks the reading, whether or not a rule names it. A clean gate on a visibly badly formatted file is a failed part.

7. Write for someone who has never seen the issue or the code. The reader cannot open Jira, has not read the repository, and does not know the project's shorthand. An unexplained ticket key, field name, or file path costs them a lookup they cannot make. Name what a thing is, once, in a short clause.

Pick the workflow

Setup runs once per project. Pull runs every time after that.

The scripts

All are Node 18+, zero dependencies, run from anywhere inside the workspace.

Run any of them with --help for the full flag list.

Three more files in scripts/ are libraries with no command line, imported by the scripts above: adf.mjs converts Atlassian Document Format to markdown, confluence-format.mjs does the same for a wiki page, and dev-status.mjs reads the development panel.

What the config holds

.jira.config.json sits at the workspace root. It runs to thousands of lines, almost all of it issueTypes, so read it with config.mjs types, config.mjs type <TYPE>, config.mjs meta and config.mjs where rather than config.mjs show.

What a pulled issue looks like

<output.dir>/PROJ-123/
  content.md      the issue: metadata, description, the ticked fields, checklist,
                  attachments, subtask list, links, development summary,
                  Linked Documents
  comments.md     every comment, oldest first
  tasks.md        every subtask in full (absent when the issue has none)
  worklogs.md     every worklog entry, on the issue and on every subtask
  development.md  pull requests, commits, builds and deployments, grouped by
                  repository (absent when the issue has no development activity)
  assets/         attachments, shared by the files above
  confluence/     linked pages, each with its own assets/ (only when linked)

In json mode the same folder holds content.json, comments.json, tasks.json, worklogs.json, development.json. In both mode it holds both sets.

Credentials

The token never goes in the config. Two environment variables, best set in a shell profile so every node call sees them:

export ATLASSIAN_EMAIL="you@example.com"
export ATLASSIAN_API_TOKEN="your-api-token"   # id.atlassian.com/manage-profile/security/api-tokens

The site itself is jira.domain in the config. Check all three at once with node <skill-path>/scripts/jira-api.mjs whoami.

Nothing here is configured for your Jira yet

Every example in these documents uses PROJ-123 and your-site.atlassian.net, and every field id reads customfield_NNNNN. Those are placeholders, not defaults. Four things differ on every Jira site, and the skill hard-codes none of them:

• Project key and issue type names. A project commonly has dozens of types, most of them names the team invented. The config is keyed by the type's own name, so any of them works.
• Custom field ids. Jira gives the same field a different customfield_NNNNN id on every site, so an id copied from someone else's config points at the wrong field — or at nothing.
• Which field fills which metadata row. Team, Sprint, Story Points, Due Date and the development panel all live in custom fields. project.metaFields maps them; a row left unmapped is written — rather than guessed.
• Which fields the checklist app writes into. project.checklistFields maps the three, and content.md rebuilds them as one list of checkboxes. All three are mapped together or none is. None of them carries the live per-item state — the YAML field is written once, at issue creation — so the real count comes from the issue's checklist property and is written as one line above the list, with every box left unticked.

workflows/setup.md asks Jira for all of it and records what the user ticks. Run it once before the first pull.

Reference documentation

Load these when the moment calls for them, not upfront. The subagent's set is pointed at from templates/subagent-instruction.md, so it reads a file when a step names it rather than being handed all of them.

Errors