Pin Skill | Agent Skills

When to Use This Skill

| Use this skill when... | Use the alternative when... | |---|---| | Transferring, pinning, locking, or bulk-editing GitHub issues | Use github-issue-writing to compose a single issue body well | | Creating a development branch from an issue (gh issue develop) | Use git-branch-pr-workflow for general branch + PR design | | Updating custom issue fields (priority, severity, custom selects) in bulk | Use github-labels for label-only operations on issues and PRs | | Performing bulk operations across many issue numbers in one command | Use git-triage to evaluate issues and PRs by completion evidence and CI state |

Context

Git remotes: !git remote -v

Open issues are fetched during execution (requires a configured git remote).

Parameters

Parse $ARGUMENTS[0] as the operation, remaining args as issue numbers and options.

| Operation | Syntax | Description | |-----------|--------|-------------| | transfer | transfer <N> <target-repo> | Transfer issue to another repository | | pin | pin <N...> | Pin issues to repository (max 3) | | unpin | unpin <N...> | Unpin issues | | lock | lock <N...> [--reason <reason>] | Lock issue discussions | | unlock | unlock <N...> | Unlock issue discussions | | develop | develop <N> [--branch <name>] [--checkout] | Create branch from issue | | bulk | bulk <sub-op> <N...> [options] | Bulk operations on multiple issues | | fields | fields <N> [--set <field>=<value>] [--list] | Manage custom issue fields |

Lock reasons: off-topic, too heated, resolved, spam

Bulk sub-operations: label, assign, close, reopen

When to Use

| Use this skill when... | Use X instead when... | |------------------------|----------------------| | Transferring issues between repos | Creating new issues (github-issue-writing) | | Pinning/unpinning important issues | Implementing issue fixes (git:issue) | | Locking resolved discussions | Managing sub-issues/deps (git:issue-hierarchy) | | Creating dev branches from issues | Searching for issues (github-issue-search) | | Bulk labeling/assigning/closing | Auto-detecting related issues (github-issue-autodetect) | | Setting custom field values | |

Execution

Execute the requested issue management operation.

Step 1: Parse Operation and Validate

Parse the operation from $ARGUMENTS[0]. Validate that specified issue numbers exist:

gh issue view $N --json number,title,state 2>/dev/null

If any issue is not found, report it and skip that issue.

Step 2: Execute Operation

Transfer

Transfer an issue to another repository within the same organization or owner.

gh issue transfer $N $TARGET_REPO

Prerequisites:

Target repo must exist and you must have write access
Both repos must be owned by the same user/org (or target accepts transfers)

Report the new issue URL after transfer.

Pin / Unpin

Pin important issues to the top of the issues list (maximum 3 pinned per repo).

# Pin
gh issue pin $N

# Unpin
gh issue unpin $N

If pinning would exceed the 3-pin limit, report which issues are currently pinned and ask which to unpin.

Lock / Unlock

Lock issue threads to prevent further comments.

# Lock with reason
gh issue lock $N --reason resolved

# Lock without reason
gh issue lock $N

# Unlock
gh issue unlock $N

| Reason | When to use | |--------|-------------| | resolved | Issue is fixed, no further discussion needed | | off-topic | Discussion has drifted from the issue | | too heated | Discussion has become unproductive | | spam | Issue thread contains spam |

Develop

Create a development branch linked to the issue.

# Create branch and switch to it locally
gh issue develop $N --checkout

# Create branch with custom name
gh issue develop $N --name $BRANCH_NAME --checkout

# Create branch without checkout
gh issue develop $N

The branch name defaults to {issue-number}-{issue-title-slug}. The branch is automatically linked to the issue on GitHub.

Bulk Operations

Apply the same operation to multiple issues at once.

Bulk label:

# Pre-check: create any missing labels before applying
for LABEL in $(echo "$LABELS" | tr ',' '\n'); do
  if ! gh label list --search "$LABEL" --json name | jq -e ".[] | select(.name==\"$LABEL\")" >/dev/null 2>&1; then
    echo "Label '$LABEL' not found — skipping (create it first with: gh label create \"$LABEL\")"
    LABELS=$(echo "$LABELS" | sed "s/,$LABEL//;s/$LABEL,//;s/^$LABEL$//")
  fi
done
for N in $ISSUE_NUMBERS; do
  [ -n "$LABELS" ] && gh issue edit $N --add-label "$LABELS"
done

Bulk assign:

for N in $ISSUE_NUMBERS; do
  gh issue edit $N --add-assignee "$USERS"
done

Bulk close:

for N in $ISSUE_NUMBERS; do
  gh issue close $N
done

Bulk reopen:

for N in $ISSUE_NUMBERS; do
  gh issue reopen $N
done

Report success/failure count after bulk operations.

Custom Fields

Manage custom issue fields (requires org-level issue field configuration).

List available fields:

# Get org name from repo
ORG=$(gh repo view --json owner --jq '.owner.login')

# List fields
gh api orgs/$ORG/issue-fields --jq '.[] | "\(.id): \(.name) (\(.type))"'

Get field values for an issue:

gh api repos/$OWNER/$REPO/issues/$N/issue-field-values \
  --jq '.[] | "\(.field.name): \(.value)"'

Set a field value:

FIELD_ID=$(gh api orgs/$ORG/issue-fields --jq '.[] | select(.name == "$FIELD_NAME") | .id')

gh api repos/$OWNER/$REPO/issues/$N/issue-field-values \
  -X POST -f field_id=$FIELD_ID -f value="$VALUE"

If the repo is not in an organization, report: "Custom issue fields require an organization-level repository."

Step 3: Report Results

| Operation | Report | |-----------|--------| | transfer | New issue URL in target repo | | pin/unpin | Confirmation, current pinned issues list | | lock/unlock | Confirmation with lock reason | | develop | Branch name and URL, checkout status | | bulk | Success/failure count per issue | | fields | Field values table or confirmation of update |

Error Handling

| Error | Cause | Action | |-------|-------|--------| | unknown command "develop" | Older gh CLI version | Report: "gh issue develop requires gh CLI 2.30+. Update with: gh upgrade" | | 403 on transfer | No write access to target | Report permission requirement | | 422 on pin | Already 3 pinned issues | List current pins, ask which to replace | | 404 on issue-fields | Org doesn't have custom fields | Report: "Custom fields not configured for this organization" |

Agentic Optimizations

| Context | Command | |---------|---------| | Transfer issue | gh issue transfer N target-repo | | Pin issue | gh issue pin N | | Lock issue | gh issue lock N --reason resolved | | Create dev branch | gh issue develop N --checkout | | Bulk close | Loop: gh issue close N for each N | | List custom fields | gh api orgs/{org}/issue-fields --jq '.[].name' | | Get field values | gh api repos/{o}/{r}/issues/N/issue-field-values |

Agent Skills: Pin

Install this agent skill to your local

Skill Files