commit 90e507bb3e15b62e0a2530770ea0e112dd8dd645 Author: zero Date: Tue Apr 7 21:56:06 2026 +0200 Add tea skill for Claude Code Full operability skill for the tea Gitea CLI — covers issues, PRs, repos, releases, branches, actions, webhooks, notifications, orgs, time tracking, and raw API access. Co-Authored-By: Claude Sonnet 4.6 diff --git a/README.md b/README.md new file mode 100644 index 0000000..1b07b0f --- /dev/null +++ b/README.md @@ -0,0 +1,56 @@ +# tea skill for Claude Code + +A [Claude Code](https://claude.ai/code) skill that gives Claude full operability with [`tea`](https://gitea.com/gitea/tea) — the official CLI for [Gitea](https://gitea.com). + +## What it does + +When installed, Claude will know how to use `tea` to: + +- Manage **issues** and **pull requests** (create, edit, review, merge, close) +- Work with **repositories** (create, fork, migrate, search) +- Handle **releases** and **release assets** +- Manage **branches**, **labels**, and **milestones** +- Monitor **CI/CD actions** (runs, logs, secrets, variables) +- Configure **webhooks** +- Track **time** on issues +- Manage **organizations** +- Read and act on **notifications** +- Make raw **authenticated API calls** for anything else + +## Requirements + +- [`tea`](https://gitea.com/gitea/tea) installed and accessible in `$PATH` +- At least one login configured (`tea logins add`) + +## Installation + +### Option A — install the skill folder directly + +Copy or symlink the `tea/` directory into your Claude Code skills path: + +```bash +cp -r tea ~/.claude/skills/ +``` + +Or via a plugin that points at this repo. + +### Option B — clone and reference + +```bash +git clone https://github.com/yourname/tea-skill +``` + +Then point your Claude Code config at the `tea/` subdirectory. + +## Structure + +``` +tea/ +├── SKILL.md # Main skill instructions +└── references/ + └── commands.md # Full command & flag reference +``` + +## License + +MIT diff --git a/tea/SKILL.md b/tea/SKILL.md new file mode 100644 index 0000000..ff6d3b0 --- /dev/null +++ b/tea/SKILL.md @@ -0,0 +1,274 @@ +--- +name: tea +description: > + Full operability with the `tea` CLI — the official command-line tool for Gitea. + Use this skill whenever the user wants to interact with a Gitea instance: managing + issues, pull requests, repos, releases, branches, labels, milestones, notifications, + actions (CI/CD), webhooks, organizations, time tracking, or making raw API calls. + Trigger on any mention of tea CLI, Gitea operations, or self-hosted git workflows + even if the user doesn't explicitly say "tea" — e.g., "open a PR on my Gitea", + "list issues on my self-hosted git", "create a release", "check CI runs". +--- + +# tea — Gitea CLI + +`tea` is the official CLI for Gitea. It handles everything: issues, PRs, repos, +releases, CI actions, webhooks, and more. It can also make raw authenticated API +calls for anything not covered by a dedicated subcommand. + +**Quick reference of all commands:** see `references/commands.md` + +--- + +## How tea finds context + +When run inside a git repo directory, `tea` automatically detects: +- Which Gitea instance to talk to (from the git remote URL) +- Which repo to operate on (owner/name from the remote) + +This means most commands just work in-context. Flags to override when needed: +- `--repo owner/name` or `-r` — target a different repo +- `--login name` or `-l` — use a specific saved login +- `--remote name` or `-R` — pick which git remote to use for login discovery + +--- + +## Authentication + +Logins are stored in `~/.config/tea/config.yml`. + +```bash +tea logins list # show saved logins +tea logins add # add a new Gitea server (interactive) +tea logins add --url https://git.example.com --token TOKEN --name myserver +tea logins default --name myserver # set default login +tea logins edit --name myserver # update an existing login +tea logins delete --name myserver # remove a login +tea whoami # show current logged-in user +``` + +--- + +## Issues + +```bash +tea issues # list open issues (current repo) +tea issues list --state all # all states: open, closed, all +tea issues list --assignee me --label bug +tea issues 42 # show issue #42 with details +tea issues create # interactive create +tea issues create --title "Bug" --body "Description" --label bug --assignee alice +tea issues edit 42 --title "New title" --assignee bob +tea issues close 42 +tea issues reopen 42 +tea comment 42 "This is a comment" # add a comment +``` + +Fields printable with `--fields`: `index,title,state,author,milestone,labels,body,comments,created,updated` + +--- + +## Pull Requests + +```bash +tea pulls # list open PRs +tea pulls 7 # show PR #7 in detail +tea pulls create --title "feat: X" --head feature-branch --base main +tea pulls checkout 7 # check out PR #7 locally +tea pulls review 7 # interactive review +tea pulls approve 7 # approve +tea pulls reject 7 # request changes +tea pulls merge 7 # merge +tea pulls edit 7 --assignee alice --milestone v2 +tea pulls close 7 +tea pulls reopen 7 +tea pulls clean 7 # delete local + remote branch after close +``` + +--- + +## Repositories + +```bash +tea repos # list your repos +tea repos list --owner myorg # list org repos +tea repos list --starred # your starred repos +tea repos search "keyword" # search across the instance +tea repos create --name myrepo --private +tea repos fork owner/repo # fork a repo +tea repos migrate --url https://github.com/owner/repo --name localname +tea repos edit --private=false # make current repo public +tea repos delete owner/repo # delete (irreversible — confirm with user) +tea clone owner/repo # clone without needing local git +``` + +--- + +## Branches + +```bash +tea branches # list branches +tea branches main # show branch detail +tea branches protect main # protect a branch +tea branches unprotect main +``` + +--- + +## Labels + +```bash +tea labels # list labels +tea labels create --name "bug" --color "#ee0701" --description "Something broken" +tea labels update --name "bug" --color "#cc0000" +tea labels delete --name "bug" +tea labels --save # save label set to file (for reuse) +``` + +--- + +## Milestones + +```bash +tea milestones # list open milestones +tea milestones create --title "v2.0" --due "2025-12-31" +tea milestones close "v1.0" +tea milestones reopen "v1.0" +tea milestones delete "v1.0" +tea milestones issues "v2.0" # list issues/PRs in a milestone +``` + +--- + +## Releases + +```bash +tea releases # list releases +tea releases create --tag v1.0.0 --title "v1.0.0" --note "Release notes" +tea releases create --tag v1.0.0 --draft --prerelease +tea releases edit v1.0.0 --note "Updated notes" +tea releases delete v1.0.0 + +# Release assets +tea releases assets list --tag v1.0.0 +tea releases assets create --tag v1.0.0 --asset ./build/app.tar.gz +tea releases assets delete --tag v1.0.0 --asset app.tar.gz +``` + +--- + +## Actions (CI/CD) + +```bash +# Workflow runs +tea actions runs # list recent runs +tea actions runs view 123 # view run details +tea actions runs logs 123 # view run logs +tea actions runs cancel 123 # cancel a run + +# Secrets +tea actions secrets list +tea actions secrets set SECRET_NAME --value "secret-value" +tea actions secrets delete SECRET_NAME + +# Variables +tea actions variables list +tea actions variables set VAR_NAME --value "value" +tea actions variables delete VAR_NAME + +# Workflows +tea actions workflows list +``` + +--- + +## Notifications + +```bash +tea notifications # unread + pinned notifications (current repo) +tea notifications --mine # all repos +tea notifications read # mark all as read +tea notifications read 42 # mark specific notification as read +tea notifications pin 42 +tea notifications unpin 42 +``` + +--- + +## Organizations + +```bash +tea orgs # list your orgs +tea orgs create --name myorg +tea orgs delete myorg +``` + +--- + +## Webhooks + +```bash +tea webhooks list +tea webhooks list --org myorg # org webhooks +tea webhooks create --url https://hook.example.com --events push,pull_request +tea webhooks update --active=false +tea webhooks delete +``` + +--- + +## Time Tracking + +```bash +tea times # list times on current repo +tea times --mine # all your tracked time across repos +tea times add 42 "1h30m" # track time on issue #42 +tea times delete +tea times reset 42 # reset all tracked time on issue #42 +tea times list --total # show total at end +``` + +--- + +## Raw API Access + +For anything not covered by a subcommand, `tea api` makes authenticated calls: + +```bash +tea api /repos/{owner}/{repo}/topics # GET (default) +tea api -X POST /repos/{owner}/{repo}/topics -f topic=golang # POST with field +tea api -X DELETE /repos/{owner}/{repo}/releases/123 +tea api -d '{"body":"hello"}' /repos/{owner}/{repo}/issues/1/comments +tea api '/repos/{owner}/{repo}/issues?state=open&type=pulls' # quote URLs with ? +tea api --include /user # include response headers +``` + +Placeholders `{owner}` and `{repo}` are filled from the current git context. + +--- + +## Helpers + +```bash +tea open # open current repo in browser +tea clone owner/repo ./dest # clone a repo (no local git needed) +``` + +--- + +## Output formats + +All list commands support `--output` / `-o`: +- `table` (default) — formatted table +- `simple` — minimal whitespace output +- `csv` / `tsv` — for scripts/pipes +- `json` / `yaml` — for programmatic use + +--- + +## Tips + +- Run `tea --help` at any time for full flag details +- Use `--debug` / `--vvv` on any command to see API calls being made +- `tea api` is your escape hatch — any Gitea API endpoint is reachable +- For multi-instance setups, set `--login` explicitly or configure a default with `tea logins default` diff --git a/tea/references/commands.md b/tea/references/commands.md new file mode 100644 index 0000000..3e4ce34 --- /dev/null +++ b/tea/references/commands.md @@ -0,0 +1,242 @@ +# tea Command Reference + +Quick-lookup table of all `tea` commands and their subcommands. + +## Table of Contents +- [Issues](#issues) +- [Pull Requests](#pull-requests) +- [Labels](#labels) +- [Milestones](#milestones) +- [Releases](#releases) +- [Times](#times) +- [Organizations](#organizations) +- [Repos](#repos) +- [Branches](#branches) +- [Actions](#actions) +- [Webhooks](#webhooks) +- [Notifications](#notifications) +- [Helpers](#helpers) +- [Setup](#setup) +- [Misc](#misc) + +--- + +## Issues +| Command | Aliases | Description | +|---------|---------|-------------| +| `tea issues` | `issue`, `i` | List or view issues | +| `tea issues list` | `ls` | List issues | +| `tea issues create` | `c` | Create an issue | +| `tea issues edit` | `e` | Edit one or more issues | +| `tea issues close` | | Close issues | +| `tea issues reopen` | `open` | Reopen issues | +| `tea comment ` | `c` | Add comment to issue/PR | + +**Filters:** `--state`, `--kind issues|pulls|all`, `--keyword`, `--labels`, `--milestones`, `--author`, `--assignee`, `--mentions`, `--from`, `--until` + +--- + +## Pull Requests +| Command | Aliases | Description | +|---------|---------|-------------| +| `tea pulls` | `pull`, `pr` | List or view PRs | +| `tea pulls list` | `ls` | List PRs | +| `tea pulls create` | `c` | Create a PR | +| `tea pulls checkout` | `co` | Check out PR branch locally | +| `tea pulls review` | | Interactive review | +| `tea pulls approve` | `lgtm`, `a` | Approve a PR | +| `tea pulls reject` | | Request changes | +| `tea pulls merge` | `m` | Merge a PR | +| `tea pulls edit` | `e` | Edit PR metadata | +| `tea pulls close` | | Close a PR | +| `tea pulls reopen` | `open` | Reopen a PR | +| `tea pulls clean` | | Delete merged feature branch | + +--- + +## Labels +| Command | Aliases | Description | +|---------|---------|-------------| +| `tea labels` | `label` | List/manage labels | +| `tea labels list` | `ls` | List labels | +| `tea labels create` | `c` | Create a label | +| `tea labels update` | | Update a label | +| `tea labels delete` | `rm` | Delete a label | + +--- + +## Milestones +| Command | Aliases | Description | +|---------|---------|-------------| +| `tea milestones` | `milestone`, `ms` | List/manage milestones | +| `tea milestones list` | `ls` | List milestones | +| `tea milestones create` | `c` | Create a milestone | +| `tea milestones close` | | Close milestones | +| `tea milestones reopen` | `open` | Reopen milestones | +| `tea milestones delete` | `rm` | Delete a milestone | +| `tea milestones issues` | `i` | List issues in milestone | + +--- + +## Releases +| Command | Aliases | Description | +|---------|---------|-------------| +| `tea releases` | `release`, `r` | List/manage releases | +| `tea releases list` | `ls` | List releases | +| `tea releases create` | `c` | Create a release | +| `tea releases edit` | `e` | Edit a release | +| `tea releases delete` | `rm` | Delete a release | +| `tea releases assets` | `asset`, `a` | Manage release assets | +| `tea releases assets list` | `ls` | List assets | +| `tea releases assets create` | `c` | Upload asset | +| `tea releases assets delete` | `rm` | Delete asset | + +--- + +## Times +| Command | Aliases | Description | +|---------|---------|-------------| +| `tea times` | `time`, `t` | List/manage time tracking | +| `tea times list` | `ls` | List tracked times | +| `tea times add` | `a` | Add tracked time to issue | +| `tea times delete` | `rm` | Delete a tracked time entry | +| `tea times reset` | | Reset all tracked time on issue | + +--- + +## Organizations +| Command | Aliases | Description | +|---------|---------|-------------| +| `tea organizations` | `organization`, `org` | List/manage orgs | +| `tea orgs list` | `ls` | List organizations | +| `tea orgs create` | `c` | Create an organization | +| `tea orgs delete` | `rm` | Delete an organization | + +--- + +## Repos +| Command | Aliases | Description | +|---------|---------|-------------| +| `tea repos` | `repo` | List/manage repos | +| `tea repos list` | `ls` | List accessible repos | +| `tea repos search` | `s` | Search repos on instance | +| `tea repos create` | `c` | Create a repo | +| `tea repos create-from-template` | `ct` | Create from template | +| `tea repos fork` | `f` | Fork a repo | +| `tea repos migrate` | `m` | Migrate repo from external source | +| `tea repos delete` | `rm` | Delete a repo | +| `tea repos edit` | `e` | Edit repo properties | + +--- + +## Branches +| Command | Aliases | Description | +|---------|---------|-------------| +| `tea branches` | `branch`, `b` | List/manage branches | +| `tea branches list` | `ls` | List branches | +| `tea branches protect` | `P` | Protect a branch | +| `tea branches unprotect` | `U` | Remove branch protection | + +--- + +## Actions +| Command | Aliases | Description | +|---------|---------|-------------| +| `tea actions` | `action` | Manage CI/CD | +| `tea actions runs` | `run` | Manage workflow runs | +| `tea actions runs list` | `ls` | List runs | +| `tea actions runs view` | `show`, `get` | View run details | +| `tea actions runs logs` | `log` | View run logs | +| `tea actions runs cancel` | `delete`, `rm` | Cancel/delete a run | +| `tea actions secrets` | `secret` | Manage secrets | +| `tea actions secrets list` | `ls` | List secrets | +| `tea actions secrets create` | `add`, `set` | Create/update secret | +| `tea actions secrets delete` | `rm` | Delete secret | +| `tea actions variables` | `variable`, `vars`, `var` | Manage variables | +| `tea actions variables list` | `ls` | List variables | +| `tea actions variables create` | `add`, `set` | Create/update variable | +| `tea actions variables delete` | `rm` | Delete variable | +| `tea actions workflows` | `workflow` | List workflows | + +--- + +## Webhooks +| Command | Aliases | Description | +|---------|---------|-------------| +| `tea webhooks` | `webhook`, `hooks`, `hook` | Manage webhooks | +| `tea webhooks list` | `ls` | List webhooks | +| `tea webhooks create` | `c` | Create a webhook | +| `tea webhooks update` | `edit`, `u` | Update a webhook | +| `tea webhooks delete` | `rm` | Delete a webhook | + +Scopes: `--repo`, `--org`, or `--global` + +--- + +## Notifications +| Command | Aliases | Description | +|---------|---------|-------------| +| `tea notifications` | `notification`, `n` | Manage notifications | +| `tea notifications list` | `ls` | List notifications | +| `tea notifications read` | `r` | Mark as read | +| `tea notifications unread` | `u` | Mark as unread | +| `tea notifications pin` | `p` | Pin notification | +| `tea notifications unpin` | | Unpin notification | + +**Filters:** `--types issue|pull|repository|commit`, `--states pinned|unread|read`, `--mine` + +--- + +## Helpers +| Command | Aliases | Description | +|---------|---------|-------------| +| `tea open` | `o` | Open repo in browser | +| `tea notifications` | `n` | Show notifications | +| `tea clone` | `C` | Clone a repo | +| `tea api` | | Raw authenticated API call | + +### tea api flags +| Flag | Description | +|------|-------------| +| `-X method` | HTTP method (GET/POST/PUT/PATCH/DELETE) | +| `-f key=value` | String field in request body | +| `-F key=value` | Typed field (number/bool/null/JSON) | +| `-H key:value` | Custom header | +| `-d '{"json"...}'` | Raw JSON body | +| `-i` / `--include` | Include HTTP response headers | +| `-o file` | Write response to file | + +--- + +## Setup +| Command | Aliases | Description | +|---------|---------|-------------| +| `tea logins` | `login` | Manage Gitea logins | +| `tea logins list` | `ls` | List saved logins | +| `tea logins add` | | Add a login | +| `tea logins edit` | `e` | Edit a login | +| `tea logins delete` | `rm` | Remove a login | +| `tea logins default` | | Get or set default login | +| `tea logins oauth-refresh` | | Refresh OAuth token | +| `tea logout` | | Log out | + +--- + +## Misc +| Command | Description | +|---------|-------------| +| `tea whoami` | Show current logged-in user | +| `tea admin users` | Manage users (requires admin) | + +--- + +## Global flags (all commands) +| Flag | Description | +|------|-------------| +| `--repo`, `-r` | Override repo (path or owner/name slug) | +| `--remote`, `-R` | Use specific git remote for login discovery | +| `--login`, `-l` | Use a specific saved login | +| `--output`, `-o` | Output format: `table`, `simple`, `csv`, `tsv`, `json`, `yaml` | +| `--page`, `-p` | Page number for paginated results | +| `--limit`, `--lm` | Items per page | +| `--debug`, `--vvv` | Enable debug mode (shows API calls) |