agentleFS
GavinGreenwoodGavinGreenwood/agentic-workflow-template/.agents/skills/assign-epic/SKILL.md

assign-epic

Skill5 starsChanged 44 days agoMITView on GitHub

Use this skill when a new Jira ticket has just been created (a ticket key was returned from a Jira API POST to /rest/api/3/issue). Automatically assigns the ticket to the most relevant open epic, or asks the user to choose when ambiguous. Also invoked when the user says "assign epic", "link to epic", or "which epic does this belong to".

  • Reads credentials

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 6 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Ticket input: use the value supplied with a direct invocation, or the ticket key from the just-created ticket.

    line 10
  2. Very specific:

    If the ticket input is a bare number (e.g.

    line 16
  3. Very specific:

    Check that JIRA_BASE_URL, JIRA_API_TOKEN, JIRA_EMAIL, and JIRA_PROJECT_KEY are set in .env.

    line 20
  4. Distinctive:

    Wait for confirmation before continuing.

    line 41
  5. Distinctive:

    If no open epics are found, tell the user and stop — there is nothing to assign.

    line 59
  6. Distinctive:

    Wait for the user's answer before continuing.

    line 90
  7. Distinctive:

    If the user says leave it unassigned, stop here and report that no change was made.

    line 99
  8. Distinctive:

    If the user asks to see the full list, print all open epics (from Step 3) and let them pick.

    line 100
  9. Very specific:

    If the response is 2xx (200 or 204), assignment succeeded — go to Step 6.

    line 114
  10. Very specific:

    If the response is 400 or 404, fall back to customfield_10014 (classic project epic link):

    line 116
  11. Very specific:

    If both fail, report the contents of /tmp/jira-resp.json (Jira's error JSON) and stop.

    line 126

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Assign a Jira ticket to the right epic

Given a ticket ID, fetch all open epics, reason about the best match, and assign the epic — or ask the user to choose when it's ambiguous.

Ticket input: use the value supplied with a direct invocation, or the ticket key from the just-created ticket.


Step 0 — Normalise the ticket ID

If the ticket input is a bare number (e.g. 42), prepend $JIRA_PROJECT_KEY- to get e.g. PROJ-42. Set this as TICKET_KEY and use it for all steps below.

Step 1 — Verify credentials

Check that JIRA_BASE_URL, JIRA_API_TOKEN, JIRA_EMAIL, and JIRA_PROJECT_KEY are set in .env. If any are missing, stop and ask the user to add them. Source .env before all Jira API calls.

Step 2 — Fetch the target ticket

source .env && curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  "$JIRA_BASE_URL/rest/api/3/issue/$TICKET_KEY?expand=renderedFields"

Extract:

  • fields.summary
  • fields.description (rendered text — this is the primary signal for matching)
  • fields.issuetype.name
  • fields.labels
  • fields.parent (key + summary, if present)
  • fields.customfield_10014 (classic epic link, if present)

If the ticket already has an epic assigned (non-null fields.parent and fields.parent.fields.issuetype.name == "Epic", or fields.customfield_10014 is set):

  • Report: "$TICKET_KEY is already linked to epic [KEY]: [summary]. Do you want to reassign it?"
  • Wait for confirmation before continuing. If the user says no, stop here.

Step 3 — Fetch all open epics

source .env && curl -s \
  -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  -X POST "$JIRA_BASE_URL/rest/api/3/search/jql" \
  -H "Content-Type: application/json" \
  -d "{\"jql\": \"project = $JIRA_PROJECT_KEY AND issuetype = Epic AND statusCategory != Done ORDER BY created DESC\", \"fields\": [\"summary\", \"description\", \"status\", \"labels\"], \"maxResults\": 200}"

Build a list of candidates:

[KEY] <summary> (<status>)

If no open epics are found, tell the user and stop — there is nothing to assign.

Step 4 — Reason about the best match

Using the ticket's summary, description, type, and labels alongside each epic's summary, reason about which epic this ticket most naturally belongs to.

Confidence rules:

  • High confidence — one epic is a clear fit and the others are clearly not. Proceed to Step 5 without asking.
  • Ambiguous — two or more epics are plausible, or the ticket could belong to none of them. Present the shortlist and ask the user to choose (see Step 4a).
  • No match — the ticket is clearly standalone (e.g. a chore, infra task, or bug with no thematic home). Confirm with the user that leaving it unassigned is intentional (see Step 4b).

Signals that suggest no epic is needed:

  • issuetype is Bug, Chore, or Spike with no clear feature area.
  • Summary contains words like "dependency update", "upgrade", "housekeeping", "docs", "config".

Step 4a — Ambiguous: ask the user to choose

Present a numbered list of the plausible epics:

I found a few possible epics for $TICKET_KEY ("<summary>"):

1. PROJ-YY — <epic summary>
2. PROJ-ZZ — <epic summary>
3. None of the above

Which epic should I assign? (1/2/3 or the key directly)

Wait for the user's answer before continuing.

Step 4b — No match: confirm unassigned is intentional

$TICKET_KEY ("<summary>") doesn't clearly belong to any open epic.
Shall I leave it unassigned, or would you like to pick one from the full list?

If the user says leave it unassigned, stop here and report that no change was made. If the user asks to see the full list, print all open epics (from Step 3) and let them pick.

Step 5 — Assign the epic

Try the parent field first (works for next-gen / team-managed projects):

source .env && curl -s -o /tmp/jira-resp.json -w "%{http_code}" \
  -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  -X PUT "$JIRA_BASE_URL/rest/api/3/issue/$TICKET_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"fields\": {\"parent\": {\"key\": \"<EPIC_KEY>\"}}}"

If the response is 2xx (200 or 204), assignment succeeded — go to Step 6.

If the response is 400 or 404, fall back to customfield_10014 (classic project epic link):

source .env && curl -s -o /tmp/jira-resp.json -w "%{http_code}" \
  -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  -X PUT "$JIRA_BASE_URL/rest/api/3/issue/$TICKET_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"fields\": {\"customfield_10014\": \"<EPIC_KEY>\"}}"

If both fail, report the contents of /tmp/jira-resp.json (Jira's error JSON) and stop. Do not retry silently.

Step 6 — Report back

Tell the user:

  • Ticket: $JIRA_BASE_URL/browse/$TICKET_KEY
  • Epic assigned: $JIRA_BASE_URL/browse/<EPIC_KEY> — <epic summary>
  • How the match was made (high-confidence auto-match or user selection)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.