Linear

You are operating ` via its API on behalf of the user. Team key: . Team UUID: . Read $APIKEY from the env (set it in your shell rc, e.g. ~/.zshrc`); NEVER hardcode the token in any file or commit.

This template uses a Linear-style GraphQL API as the worked example. It is the most-replaceable skill here: adapt to Jira, GitHub Issues, Notion, or any tracker by swapping the API-call layer (the _gql helper) and the field names — the subcommand contract stays the same.

Subcommands

Parse $ARGUMENTS as . Supported:

| Subcommand | Args | Effect | |---|---|---| | create-epic | ` [--description "..."] [--label "..."] | Create a top-level issue. | | create-story | --epic -NNN [--description "..."] [--label "..."] | Create a child issue under an Epic. | | create-task | --parent -NNN [--description "..."] [--label "..."] | Create a child issue under any parent. | | show | -NNN | Print id, title, state, parent, children, URL. | | update | -NNN status: OR title:"..." OR description:"..." OR parent:-NNN | Update one or more fields. | | list | [--status ] [--mine] [--limit N] [--label "..."]` | List issues from the team. |

Workflow state UUIDs (Linear-style — replace with your tracker's equivalents):

| Name | UUID placeholder | |---|---| | Todo | ` | | In Progress | | | In Review | | | Done | ` |

If no --status given on create, default to Todo.

Common: send a request

_gql() {
  local query="$1"
  curl -sS -X POST  \
    -H "Authorization: $_API_KEY" \
    -H "Content-Type: application/json" \
    -d "$(jq -nc --arg q "$query" '{query:$q}')"
}

Always check the response for .errors and abort with the message if present.

Resolve -NNN → UUID

When a subcommand references a sibling ticket (--parent, --epic, or update ), resolve the human identifier to the API UUID first:

query { issue(id: "-NNN") { id identifier title state { name id } } }

If the ticket doesn't exist, abort with Error: ticket not found.

create-epic / create-story / create-task

All three use the same issueCreate mutation; parentId is the only difference.

mutation {
  issueCreate(input: {
    teamId: ""
    title: ""
    description: ""
    stateId: ""
    parentId: ""
    labelIds: []
  }) {
    success
    issue { id identifier title url }
  }
}

To resolve a label name → UUID, query the team's labels once per session and cache in memory. After creation, print:

✅ Created  "" — 
   Parent:   •  State:   •  Labels: 

update

Map status: to the workflow state UUID via the table above (case-insensitive match). For parent:-NNN, resolve to UUID first.

mutation {
  issueUpdate(id: "", input: {
    stateId: ""
    title: ""
    description: ""
    parentId: ""
  }) {
    success
    issue { id identifier title state { name } url }
  }
}

Build the input dynamically — only include fields the user passed. Print ✅ Updated : .

show

query {
  issue(id: "-NNN") {
    id identifier title url
    description
    state { name }
    parent { identifier title }
    children { nodes { identifier title state { name } } }
    labels { nodes { name } }
    assignee { displayName }
    createdAt updatedAt
    comments(first: 5) { nodes { user { displayName } body createdAt } }
  }
}

Print as a tidy block. Truncate description to ~500 chars; truncate comment bodies to ~200 chars each.

list

query {
  issues(
    filter: {
      team: { key: { eq: "" } }
      
      
      
    }
    first: 
    orderBy: updatedAt
  ) {
    nodes {
      identifier title url
      state { name }
      assignee { displayName }
      updatedAt
    }
  }
}

Print as a one-line-per-issue table.

Logging

After every mutation (create / update only — not show / list), write a per-invocation audit shard, not an append to one shared file. A single RUN_LOG.md serializes parallel sessions and produces merge conflicts the moment two / invocations run at once; one file per invocation at a unique path never conflicts.

# CUSTOMIZE: point this at your own shard helper. It should write a uniquely
# named file under docs/agent-evolution/runs// — one per call.
./scripts/runlog.sh append " " "" \
  ""

Keep shard bodies PII-free (repo-relative paths only, no committer email, no home-dir absolutes) — they are committed to git history.

Error handling

• Missing _API_KEY → abort with Error: _API_KEY not set in environment.
• Tracker API error → abort with the verbatim error message from the response.
• Unknown subcommand → print the subcommand table above as usage, exit non-zero.
• create-* without a title → abort with usage.

Output style

• One ✅ / ❌ line per top-level result.
• For multi-step operations (resolve → mutate), emit a brief progress line per step.
• Don't print raw API responses unless --verbose is in $ARGUMENTS.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: amurthygithub
• Source: amurthygithub/Sharevalueclaude_skills
• License: MIT

Install and usage instructions live in the source repository linked above.