From f5d3fe58ecd1bf188dcf8f185c76a2991ab95c07 Mon Sep 17 00:00:00 2001
From: Sulthan Zaki <sultankiki05@gmail.com>
Date: Mon, 17 Aug 2026 17:52:16 +0700
Subject: [PATCH] Add a gitea skill; point AGENTS.md at it (#126)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Forge usage lived in three places (`AGENTS.md`, `docs/agents/issue-tracker.md`, and habit). This moves the how-to-run-`tea` half into a model-invoked skill that fires on any issue/PR task, and reduces `AGENTS.md` to identity plus pointers.

- **new** `.claude/skills/gitea/SKILL.md` — command table plus the traps `tea <cmd> --help` will not tell you.
- `AGENTS.md` — Forge section is now one line: Gitea not GitHub, `gh` and the `issue://`/`pr://` URIs fail, then pointers to the skill, `docs/agents/issue-tracker.md`, and `docs/agents/triage-labels.md`.
- `.claude/skills/implement-tickets/SKILL.md` — pointer split: tracker conventions to the doc, `tea` usage to the skill.

Both `docs/agents/` files are untouched; the skill cites them instead of restating them.

Facts in the skill are measured against `tea` 0.14.2 on 2026-08-17, not remembered:

- `gh` is not installed, so `read issue://71` errors — there is no fallback to add.
- **A bare read is a truncated read.** Without `--comments`, `tea issue <n>` drops every comment silently, with no prompt under a non-TTY: issue #123 prints 40 lines bare, 132 with the flag. The skill makes `--comments` mandatory for any read meant to understand a ticket, with `tea issue list --fields index,comments` as the checkable count.
- Issues and PRs share one index space; output is rendered boxes so parsing needs `-o json`; `close` takes no `--comment`; labels never auto-create; multi-line bodies need a heredoc; `tea` exposes neither sub-issues nor dependencies.

Unmeasured and marked as such: whether `--comments` covers a PR's review-comment stream — no PR in this repo has comments, so `tea pr review-comments <n>` is named without a claim about overlap.

Reviewed-on: https://gitea.violetcrown.my.id/sulthan/mangaBookmark/pulls/126
Co-authored-by: Sulthan Zaki <sultankiki05@gmail.com>
Co-committed-by: Sulthan Zaki <sultankiki05@gmail.com>
---
 .claude/skills/gitea/SKILL.md             | 75 +++++++++++++++++++++++
 .claude/skills/implement-tickets/SKILL.md |  2 +-
 AGENTS.md                                 |  9 +--
 3 files changed, 77 insertions(+), 9 deletions(-)
 create mode 100644 .claude/skills/gitea/SKILL.md

diff --git a/.claude/skills/gitea/SKILL.md b/.claude/skills/gitea/SKILL.md
new file mode 100644
index 0000000..6b69f25
--- /dev/null
+++ b/.claude/skills/gitea/SKILL.md
@@ -0,0 +1,75 @@
+---
+name: gitea
+description: Use for every forge operation in this repo — read, create, comment on, label, close, or search an issue; create, review, merge, or check out a PR; and whenever `gh`, `issue://`, or `pr://` fails or a ticket number is ambiguous. This repo's forge is self-hosted Gitea driven by `tea`, not GitHub.
+---
+
+# Gitea, not GitHub
+
+`origin` is the self-hosted Gitea instance `gitea.violetcrown.my.id`, repo
+`sulthan/mangaBookmark`. Everything past plain git goes through
+[`tea`](https://gitea.com/gitea/tea) (0.14.2 on this machine).
+
+**`gh` is not installed**, so the harness's `issue://<n>` and `pr://<n>` URIs
+error out (`GitHub CLI (gh) is not installed`, measured 2026-08-17). There is no
+fallback to add — read tickets with `tea`.
+
+`tea` infers the repo from `origin`; auth lives in `tea login`, never a
+`GH_TOKEN`. Your Gitea username comes from `tea login list` — `tea` has no `@me`.
+
+Flags are the environment's job: run `tea <command> --help` rather than trusting
+a remembered flag. This file carries only what `--help` will not tell you.
+
+## Commands
+
+| Job | Command |
+|---|---|
+| Read | `tea issue <n> --comments` / `tea pr <n> --comments` — `--comments` is not optional |
+| List | `tea issue list --state open\|closed\|all -o json --fields index,title,body,labels,state,author` |
+| Search | `tea issue list -k "<keyword>" -L "<label>" -A "<author>"` (`-K all` also searches PRs) |
+| Create | `tea issue create -t "..." -d "..."` (`-L`, `-a` optional) |
+| Comment | `tea comment <n> "..."` |
+| Label | `tea issue edit <n> --add-labels "..."` / `--remove-labels "..."` |
+| Close | `tea issue close <n>` / `tea pr close <n>` |
+| PR | `tea pr create --head <branch> --base main -t "..." -d "..."`, `tea pr checkout <n>`, `tea pr review <n>`, `tea pr merge <n>` |
+
+## Traps
+
+- **A bare read is a truncated read.** Without `--comments`, `tea issue <n>` and
+  `tea pr <n>` print the opening body and drop every comment silently — no
+  prompt, no marker, no hint that more exists (measured 2026-08-17: issue #123
+  prints 40 lines bare, 132 with `--comments`). The comments are where the
+  decisions live and the body is usually the stalest part of the ticket, so
+  **every read that exists to understand an issue or PR passes `--comments`**,
+  and understanding means body plus all comments plus whatever ticket they point
+  at. Comment count is `tea issue list --fields index,comments`, so a read that
+  shows fewer than that is incomplete. A PR's review comments are a second
+  stream: `tea pr review-comments <n>`.
+- **One index space for issues and PRs.** A bare `#42` may be either: try
+  `tea pr 42`, fall back to `tea issue 42`. Say which one you found.
+- **Output is rendered boxes**, not plain text. Anything you parse needs
+  `-o json`, plus `--fields` to keep the payload small. `tea pr create` prints
+  the PR URL on its last line.
+- **`close` takes no `--comment`.** Comment with `tea comment <n>`, then close.
+- **Gitea will not auto-create a label.** `tea labels list` first; missing one
+  gets `tea labels create --name "..." --color "#rrggbb"` before the `edit`.
+- **Multi-line bodies go through a heredoc**, never inline escapes:
+  ```bash
+  tea issue create -t "Title" -d "$(cat <<'EOF'
+  body line one
+
+  - acceptance criterion
+  EOF
+  )"
+  ```
+- **No sub-issue and no dependency command.** Gitea's API has issue
+  dependencies, `tea` does not expose them, so parentage and blocking live as
+  body lines — the shapes are in `docs/agents/issue-tracker.md`.
+
+## Conventions this repo layers on top
+
+Ticket bodies, wayfinding issues, and the PR-as-request-surface flag:
+`docs/agents/issue-tracker.md`. Triage label strings: `docs/agents/triage-labels.md`.
+A label named there still has to exist in the tracker before `--add-labels`.
+
+Finish a forge action by stating the number you touched and its state after —
+"commented and closed #71" — so the write is checkable without a second query.
diff --git a/.claude/skills/implement-tickets/SKILL.md b/.claude/skills/implement-tickets/SKILL.md
index 1de63aa..9f3b088 100644
--- a/.claude/skills/implement-tickets/SKILL.md
+++ b/.claude/skills/implement-tickets/SKILL.md
@@ -11,7 +11,7 @@ to the tracker. You do not write the implementation — every line of ticket cod
 is written by a `ticket-implementer` subagent in its own git worktree. Reach for
 the editor yourself only for a merge conflict resolution.
 
-Ticket source and `tea` usage: `docs/agents/issue-tracker.md`.
+Ticket source and tracker conventions: `docs/agents/issue-tracker.md`. `tea` usage: skill `gitea`.
 
 ## 1. Collect the tickets
 
diff --git a/AGENTS.md b/AGENTS.md
index 9402151..11b7750 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -67,14 +67,7 @@ Smoke test: `curl` endpoints with `Authorization: Bearer <token>`; confirm `OPTI
 
 ## Forge: Gitea, not GitHub
 
-`origin` is self-hosted Gitea instance (`gitea.violetcrown.my.id`, repo `sulthan/mangaBookmark`), so **`gh` don't work here — use `tea` (Gitea CLI) for anything past plain git.** `tea` infers the repo from `origin`; auth lives in `tea login`, not a `GH_TOKEN` env var. It prints rendered boxes rather than plain text, so pass `-o json` when parsing; a PR URL lands on the last line.
-
-- PRs: `tea pr create --head <branch> --base main --title "..." --description "..."`, `tea pr list`, `tea pr <n>`, `tea pr checkout <n>`.
-- Issues: `tea issue create --title "..." --description "..."` (`--labels`, `--assignees` optional), `tea issue <n> --comments`, `tea issue list --state open|closed|all -o json`, `tea issue close <n>`.
-- Comments: `tea comment <n> "..."` — `tea issue close` takes no `--comment` flag.
-- Labels: `tea issue edit <n> --add-labels "..."` / `--remove-labels "..."`. Gitea will **not** auto-create a label, so `tea labels create --name "..." --color "#rrggbb"` first.
-- Triage vocabulary is `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`.
-- Gitea shares one index space across issues and PRs, so a bare `#42` may be either — try `tea pr 42`, fall back to `tea issue 42`.
+`origin` is self-hosted Gitea (`gitea.violetcrown.my.id`, repo `sulthan/mangaBookmark`), so **`gh` don't work here and the `issue://`/`pr://` URIs error out — drive the forge with `tea`.** How to run it — commands, traps, JSON output: skill `gitea`. Tracker conventions (ticket bodies, wayfinding, PR-as-request-surface flag): `docs/agents/issue-tracker.md`. Triage label strings: `docs/agents/triage-labels.md`.
 
 ## Design system