Docs workflow create jira

Skill opendatahub-io/docs-skills/skills/docs-workflow-create-jira

Create a linked JIRA ticket for documentation work. No agent dispatch. Uses direct JIRA REST API calls via a shell script. Checks for existing links, handles public/private project visibility, converts markdown to JIRA wiki markup.From its SKILL.md

Install

npx -y skills add opendatahub-io/docs-skills --skill docs-workflow-create-jira

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

3 stars3 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

3.4 KB, as published. Nobody here has run it

Create JIRA Step

Step skill for the docs-orchestrator pipeline. Follows the step skill contract: parse args → do work → write output.

Unlike other step skills, this skill does not dispatch an agent. It runs scripts/create-jira-ticket.sh directly.

Output: null (produces a JIRA URL, not a file)

Arguments

$1 — Parent JIRA ticket ID (required)
--base-path <path> — Base output path (e.g., .agent_workspace/proj-123)
--project <PROJECT> — Target JIRA project key for the new ticket (required)

Input

<base-path>/planning/plan.md

Environment

Requires JIRA_API_TOKEN (or the backward-compatible alias JIRA_AUTH_TOKEN) and JIRA_EMAIL in the environment. create-jira-ticket.sh sources ~/.env then <project-root>/.env, where the project root is resolved from the PLAN_FILE location.

Execution

Run the create-jira-ticket script:

bash ${CLAUDE_SKILL_DIR}/scripts/create-jira-ticket.sh "$TICKET" "$PROJECT" "${BASE_PATH}/planning/plan.md"

The script handles all steps:

Check for existing link — if a "Document" link already exists on the parent ticket, exits early
Check project visibility — unauthenticated probe to determine public vs private
Extract description — pulls JTBD sections from the plan, appends dated footer
Convert to JIRA wiki markup — calls scripts/md2wiki.py for markdown → wiki conversion
Create JIRA ticket — POST to JIRA REST API with [ccs] Docs - prefix
Link to parent — creates a "Document" issue link (singular, not "Documents")
Attach plan — attaches the full plan file (private projects only)

The script prints the JIRA URL on success (e.g., https://redhat.atlassian.net/browse/DOCS-456), or a skip message if a linked ticket already exists.

Write step-result.json

After the script completes, write the sidecar to ${BASE_PATH}/create-jira/step-result.json:

mkdir -p "${BASE_PATH}/create-jira"

If the script created a new ticket (output contains a JIRA URL like https://...atlassian.net/browse/DOCS-456):

{
  "schema_version": 1,
  "step": "create-jira",
  "ticket": "<TICKET>",
  "completed_at": "<current ISO 8601 timestamp>",
  "jira_url": "https://redhat.atlassian.net/browse/DOCS-456",
  "jira_key": "DOCS-456",
  "action": "created",
  "skipped": false,
  "skip_reason": null
}

If the script found an existing linked ticket (output contains "already exists"):

{
  "schema_version": 1,
  "step": "create-jira",
  "ticket": "<TICKET>",
  "completed_at": "<current ISO 8601 timestamp>",
  "jira_url": "https://redhat.atlassian.net/browse/<linked-key from output>",
  "jira_key": "<linked-key from output>",
  "action": "found_existing",
  "skipped": false,
  "skip_reason": null
}

Extract jira_key and jira_url from the script's stdout. If the script fails (non-zero exit), write the sidecar with action: "skipped", skipped: true, and skip_reason: "create_failed".