From 22fae34b55273ff5486da8e9e30d934ad7248ce5 Mon Sep 17 00:00:00 2001
From: James Griffin <james@unsupervised.ca>
Date: Tue, 7 Apr 2026 10:27:51 -0300
Subject: [PATCH] Add skill for doing issue management in gitea

---
 .claude/skills/issues/SKILL.md | 501 +++++++++++++++++++++++++++++++++
 1 file changed, 501 insertions(+)
 create mode 100644 .claude/skills/issues/SKILL.md

diff --git a/.claude/skills/issues/SKILL.md b/.claude/skills/issues/SKILL.md
new file mode 100644
index 0000000..f148e29
--- /dev/null
+++ b/.claude/skills/issues/SKILL.md
@@ -0,0 +1,501 @@
+---
+name: issues
+description: Create and Manage issues in Gitea
+dependencies: tea
+---
+
+# Issue Management
+
+Comprehensive guide for managing Gitea issues using the tea CLI.
+
+## Table of Contents
+
+- [Viewing Issues](#viewing-issues)
+- [Creating Issues](#creating-issues)
+- [Updating Issues](#updating-issues)
+- [Closing and Reopening Issues](#closing-and-reopening-issues)
+- [Labels](#labels)
+- [Milestones](#milestones)
+- [Projects](#projects)
+- [Search and Filtering](#search-and-filtering)
+- [Common Workflows](#common-workflows)
+
+## Viewing Issues
+
+### ls issues
+
+```bash
+# ls open issues in current repository
+tea issue ls --repo thatguygriff/walkies
+
+# ls all issues (open and closed)
+tea issue ls --state all --repo thatguygriff/walkies
+
+# Limit number of results
+tea issue ls --limit 50 --repo thatguygriff/walkies
+
+# Filter by label
+tea issue ls --labels bug --repo thatguygriff/walkies
+tea issue ls --labels "help wanted,good first issue" --repo thatguygriff/walkies
+
+# Filter by assignee
+tea issue ls --assignee @me --repo thatguygriff/walkies
+tea issue ls --assignee username --repo thatguygriff/walkies
+
+# Filter by milestone
+tea issue ls --milestones "v1.0" --repo thatguygriff/walkies
+
+# Get JSON output (use --fields to select columns)
+tea issue ls --output json --fields number,title,state,labels,assignees --repo thatguygriff/walkies
+```
+
+### View specific issue
+
+```bash
+# View issue details
+tea issue view 123
+
+# View in browser
+tea issue view 123 --web
+
+# View issue comments
+tea issue view 123 --comments
+
+# Get JSON output
+tea issue view 123 --output json
+```
+
+## Creating Issues
+
+### Interactive creation
+
+```bash
+# Create issue with interactive prompts
+tea issue create --repo thatguygriff/walkies
+
+# Follow prompts for:
+# - Title
+# - Body
+# - Metadata (labels, assignees, milestones)
+```
+
+### Non-interactive creation
+
+```bash
+# Create issue with title only
+tea issue create --title "Fix login bug" --repo thatguygriff/walkies
+
+# Create issue with title and body
+tea issue create --title "Add dark mode" --description "Users have requested dark mode support" --repo thatguygriff/walkies
+
+# Create issue with metadata
+tea issue create \
+  --title "Performance optimization" \
+  --description "Optimize database queries" \
+  --labels bug,performance \
+  --assignees username \
+  --milestone "v2.0" \
+  --repo thatguygriff/walkies
+```
+
+## Updating Issues
+
+### Edit issue
+
+```bash
+# Edit issue interactively
+tea issue edit 123
+
+# Update title
+tea issue edit 123 --title "New title"
+
+# Update body
+tea issue edit 123 --description "Updated description"
+
+# Add labels (flag is plural: --add-labels)
+tea issue edit 123 --add-labels bug,priority-high
+
+# Remove labels (flag is plural: --remove-labels)
+tea issue edit 123 --remove-labels wontfix
+
+# Add assignees (flag is plural: --add-assignees)
+tea issue edit 123 --add-assignees user1,user2
+
+# Set milestone
+tea issue edit 123 --milestone "v1.5"
+
+# Remove milestone
+tea issue edit 123 --milestone ""
+```
+
+### Comment on issue
+
+```bash
+# Add comment — body is a positional argument, not a flag
+tea comment 123 "Working on this now" --repo thatguygriff/walkies
+
+# Edit comment (requires comment ID, via API)
+tea api repos/:owner/:repo/issues/comments/COMMENT_ID -X PATCH -f body="Updated comment"
+```
+
+## Closing and Reopening Issues
+
+```bash
+# Close issue (no --comment or --reason flags available)
+tea issue close 123 --repo thatguygriff/walkies
+
+# Close multiple issues
+for issue in 123 124 125; do
+  tea issue close $issue --repo thatguygriff/walkies
+done
+
+# Reopen issue
+tea issue reopen 123 --repo thatguygriff/walkies
+
+# To add a comment when closing, close first then comment separately
+tea issue close 123 --repo thatguygriff/walkies
+tea comment 123 "Fixed in PR #456" --repo thatguygriff/walkies
+```
+
+### Delete issues
+
+```bash
+# Delete issue (via API - CAREFUL)
+tea api repos/:owner/:repo/issues/123 -X DELETE
+```
+
+## Labels
+
+### ls labels
+
+```bash
+# ls labels in repository
+tea label ls --repo thatguygriff/walkies
+
+# Get JSON output
+tea label ls --output json --repo thatguygriff/walkies
+```
+
+### Create labels
+
+```bash
+# Create label — name is a named flag (--name), not positional
+tea label create --name bug --description "Something isn't working" --color d73a4a --repo thatguygriff/walkies
+
+# Create multiple labels
+tea label create --name enhancement --description "New feature or request" --color a2eeef --repo thatguygriff/walkies
+tea label create --name documentation --description "Improvements to documentation" --color 0075ca --repo thatguygriff/walkies
+tea label create --name "good first issue" --description "Good for newcomers" --color 7057ff --repo thatguygriff/walkies
+```
+
+### Update labels
+
+```bash
+# tea label edit does not exist — use tea label update with --id (get ID from tea label ls --output json)
+tea label update --id 42 --name "bug" --description "Bug report" --color ff0000 --repo thatguygriff/walkies
+
+# Rename label (change --name)
+tea label update --id 42 --name new-name --repo thatguygriff/walkies
+```
+
+### Delete labels
+
+```bash
+# Delete label by ID (get ID from tea label ls --output json)
+tea label delete --id 42 --repo thatguygriff/walkies
+```
+
+### Manage issue labels
+
+```bash
+# Add labels to issue
+tea issue edit 123 --add-labels bug,priority-high --repo thatguygriff/walkies
+
+# Remove labels from issue
+tea issue edit 123 --remove-labels wontfix --repo thatguygriff/walkies
+
+# Replace all labels (via API)
+tea api repos/:owner/:repo/issues/123 -X PATCH -f labels='["bug","confirmed"]'
+```
+
+## Milestones
+
+### ls milestones
+
+```bash
+# ls milestones (via API)
+tea api repos/:owner/:repo/milestones | jq '.[] | {number: .number, title: .title, due_on: .due_on}'
+```
+
+### Create milestone
+
+```bash
+# Create milestone
+tea api repos/:owner/:repo/milestones -X POST \
+  -f title="v1.0" \
+  -f description="First major release" \
+  -f due_on="2024-12-31T23:59:59Z"
+```
+
+### Update milestone
+
+```bash
+# Update milestone
+tea api repos/:owner/:repo/milestones/1 -X PATCH \
+  -f title="v1.0.0" \
+  -f state="closed"
+```
+
+### Delete milestone
+
+```bash
+# Delete milestone
+tea api repos/:owner/:repo/milestones/1 -X DELETE
+```
+
+## Projects
+
+Projects are managed via the API — `tea issue edit` does not support `--add-project` or `--remove-project`.
+
+```bash
+# ls projects (via API)
+tea api repos/:owner/:repo/projects | jq '.[] | {name: .name, number: .number}'
+
+# ls organization projects
+tea api orgs/:org/projects | jq '.[] | {name: .name, number: .number}'
+```
+
+## Search and Filtering
+
+Search uses `--keyword` / `-k`, not `--search`.
+
+```bash
+# Filter by keyword in title/body
+tea issue ls --keyword "authentication" --repo thatguygriff/walkies
+
+# Filter by label + keyword
+tea issue ls --labels bug --keyword "login" --repo thatguygriff/walkies
+
+# Filter by assignee + state
+tea issue ls --assignee @me --state open --repo thatguygriff/walkies
+
+# Filter by milestone
+tea issue ls --milestones "v2.0" --repo thatguygriff/walkies
+
+# Filter by date range
+tea issue ls --from "2024-01-01" --until "2024-12-31" --repo thatguygriff/walkies
+```
+
+### Filter with JSON output
+
+Pipe `--output json` to `jq` for advanced filtering — there is no `--jq` flag.
+
+```bash
+# Get open issues as JSON and filter with jq
+tea issue ls --output json --repo thatguygriff/walkies \
+  | jq '.[] | select(.labels[].name == "bug")'
+
+# Count issues by label
+tea issue ls --state all --output json --repo thatguygriff/walkies \
+  | jq '[.[] | .labels[].name] | group_by(.) | map({label: .[0], count: length})'
+
+# Find untriaged issues (no labels)
+tea issue ls --output json --repo thatguygriff/walkies \
+  | jq '.[] | select(.labels | length == 0) | {number: .number, title: .title}'
+```
+
+## Common Workflows
+
+### Workflow 1: Bug report workflow
+
+```bash
+# Create bug report
+tea issue create \
+  --title "Login fails with 2FA enabled" \
+  --description "$(cat <<EOF
+## Bug Description
+Users cannot log in when 2FA is enabled.
+
+## Steps to Reproduce
+1. Enable 2FA on account
+2. Attempt to log in
+3. Authentication fails
+
+## Expected Behavior
+Login should succeed with 2FA code
+
+## Actual Behavior
+Login fails with error message
+
+## Environment
+- Browser: Chrome 119
+- OS: macOS 14.0
+EOF
+)" \
+  --labels bug,priority-high \
+  --assignees security-team \
+  --repo thatguygriff/walkies
+
+# Get issue number from JSON output
+ISSUE=$(tea issue ls --labels bug --limit 1 --output json --repo thatguygriff/walkies | jq -r '.[0].number')
+
+# Add follow-up comment
+tea comment $ISSUE "Investigating root cause" --repo thatguygriff/walkies
+
+# Link to PR when fixed
+tea comment $ISSUE "Fixed in PR #789" --repo thatguygriff/walkies
+
+# Close issue, then add closing comment separately
+tea issue close $ISSUE --repo thatguygriff/walkies
+tea comment $ISSUE "Resolved in v2.1.0" --repo thatguygriff/walkies
+```
+
+### Workflow 2: Feature request workflow
+
+```bash
+# Create feature request
+tea issue create \
+  --title "Add export to PDF feature" \
+  --description "Users want to export reports as PDF" \
+  --labels enhancement,feature-request \
+  --repo thatguygriff/walkies
+
+# Team discusses and assigns
+tea issue edit 123 --add-assignees developer1 --milestone "v2.0" --repo thatguygriff/walkies
+
+# Track progress with comments
+tea comment 123 "Starting implementation" --repo thatguygriff/walkies
+tea comment 123 "UI mockups ready for review" --repo thatguygriff/walkies
+tea comment 123 "Backend API complete" --repo thatguygriff/walkies
+
+# Link to PR
+tea comment 123 "Implementation complete, see PR #456" --repo thatguygriff/walkies
+
+# Close when merged
+tea issue close 123 --repo thatguygriff/walkies
+tea comment 123 "Feature released in v2.0" --repo thatguygriff/walkies
+```
+
+### Workflow 3: Issue triage workflow
+
+```bash
+# ls untriaged issues (no labels)
+tea issue ls --output json --repo thatguygriff/walkies \
+  | jq '.[] | select(.labels | length == 0) | {number: .number, title: .title}'
+
+# Triage each issue (--add-labels is plural)
+tea issue edit 123 --add-labels bug --repo thatguygriff/walkies
+tea issue edit 124 --add-labels enhancement --repo thatguygriff/walkies
+tea issue edit 125 --add-labels question,help-wanted --repo thatguygriff/walkies
+
+# Assign priority labels
+tea issue edit 123 --add-labels priority-high --repo thatguygriff/walkies
+tea issue edit 124 --add-labels priority-medium --repo thatguygriff/walkies
+
+# Assign to milestones
+tea issue edit 123 --milestone "v1.5" --repo thatguygriff/walkies
+tea issue edit 124 --milestone "v2.0" --repo thatguygriff/walkies
+
+# Assign to team members
+tea issue edit 123 --add-assignees developer1 --repo thatguygriff/walkies
+```
+
+### Workflow 4: Sprint planning workflow
+
+```bash
+# ls issues in milestone
+tea issue ls --milestones "Sprint 5" --output json --repo thatguygriff/walkies
+
+# Assign issues to team members
+tea issue edit 101 --add-assignees alice --repo thatguygriff/walkies
+tea issue edit 102 --add-assignees bob --repo thatguygriff/walkies
+tea issue edit 103 --add-assignees charlie --repo thatguygriff/walkies
+
+# Add sprint label
+for issue in 101 102 103; do
+  tea issue edit $issue --add-labels "sprint-5" --repo thatguygriff/walkies
+done
+
+# Monitor progress during sprint
+tea issue ls --milestones "Sprint 5" --state all --output json --repo thatguygriff/walkies
+
+# Close completed issues
+tea issue ls --milestones "Sprint 5" --labels done --output json --repo thatguygriff/walkies \
+  | jq -r '.[].number' \
+  | xargs -I {} tea issue close {} --repo thatguygriff/walkies
+```
+
+### Workflow 5: Bulk issue operations
+
+```bash
+# Create multiple issues from file (title|body|labels per line)
+while IFS='|' read -r title body labels; do
+  tea issue create --title "$title" --description "$body" --labels "$labels" --repo thatguygriff/walkies
+done < issues.txt
+
+# Bulk close stale issues
+tea issue ls --until "2023-01-01" --output json --repo thatguygriff/walkies \
+  | jq -r '.[].number' \
+  | xargs -I {} tea issue close {} --repo thatguygriff/walkies
+
+# Bulk label update
+tea issue ls --labels old-label --output json --repo thatguygriff/walkies \
+  | jq -r '.[].number' \
+  | xargs -I {} tea issue edit {} --remove-labels old-label --add-labels new-label --repo thatguygriff/walkies
+
+# Export issues to CSV
+tea issue ls --state all --output json --limit 1000 --repo thatguygriff/walkies \
+  | jq -r '.[] | [.number, .title, .state, (.labels | map(.name) | join(";")), (.assignees | map(.login) | join(";")), .created] | @csv' \
+  > issues.csv
+```
+
+## Tips and Best Practices
+
+1. **Label systematically**: Develop a consistent labeling scheme
+2. **Triage regularly**: Review and label new issues promptly
+3. **Link PRs**: Always reference issues in PR descriptions
+4. **Use milestones**: Group related issues for release planning
+5. **Assign clearly**: Assign issues to specific people
+6. **Comment updates**: Keep stakeholders informed with comments
+7. **Use --output json + jq**: Combine for powerful filtering and reporting
+8. **Get label IDs first**: `tea label update` and `tea label delete` require `--id`, not name — run `tea label ls --output json` to find IDs
+
+## Quick Reference
+
+```bash
+# List
+tea issue ls                                           # ls open issues
+tea issue ls --state all                               # ls all issues
+tea issue ls --labels bug                              # Filter by label (plural flag)
+tea issue ls --assignee @me                            # Your issues
+tea issue ls --keyword "auth"                          # Search by keyword
+
+# View
+tea issue view 123                                     # View issue details
+tea issue view 123 --web                               # Open in browser
+tea issue view 123 --comments                          # Include comments
+
+# Create
+tea issue create                                       # Interactive creation
+tea issue create --title "text" --description "text"   # Non-interactive
+tea issue create --labels bug --assignees user         # With metadata (both plural)
+
+# Update
+tea issue edit 123 --title "new title"                 # Change title
+tea issue edit 123 --add-labels bug                    # Add label (plural flag)
+tea issue edit 123 --remove-labels wontfix             # Remove label (plural flag)
+tea issue edit 123 --add-assignees user                # Add assignee (plural flag)
+
+# Comment (tea comment, not tea issue comment)
+tea comment 123 "comment text" --repo thatguygriff/walkies
+
+# Close/Reopen (no --comment or --reason flags; add comment separately)
+tea issue close 123                                    # Close issue
+tea issue reopen 123                                   # Reopen issue
+
+# Labels
+tea label ls                                           # ls labels
+tea label create --name "bug" --color d73a4a           # Create (--name flag required)
+tea label update --id 42 --name new-name               # Update (--id required, not name)
+tea label delete --id 42                               # Delete (--id required, not name)
+```