| name | docs-workflow-create-jira |
| description | 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. |
| model | claude-haiku-4-5@20251001 |
| argument-hint | <ticket> --base-path <path> --project <PROJECT> |
| allowed-tools | Read, Write, Bash |
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".
