holocron/plugins/gitea/.apm/skills/gitea-issues/SKILL.md at 6cfc3577e2b6e888e9938fa71fb777966e945bc5

Files

Defame1297 6cfc3577e2 docs: trim repeated boilerplate in git, gitea, and bin skills

Finding 13: five blocks of near-identical wording were repeated across
skills within a plugin — the gitea "resolve owner and repo" step (5
skills), the 404-masks-403 note (6 files), the manual pagination
explanation (8 files), the git plugin's main/master force-push refusal
(7 files, some with multiple internal restatements), and the bin
skills' domain-glossary/ADR paragraph (5 skills). Tightened each
instance in place — same meaning, fewer words — rather than extracting
to a shared file, which ADR-0014's one-file-per-skill install
constraint rules out. Left the three git skills' structured-result
JSON shapes alone (coupled to the separate, out-of-scope git-orchestrate
merge candidate, finding 19).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD

2026-09-12 19:48:31 +00:00

4.5 KiB

Raw Blame History

name, description, compatibility, metadata, allowed-tools

name

description

compatibility

metadata

allowed-tools

gitea-issues

Use when reading or writing Gitea issues — "create an issue", "what issues are open", "close issue #N", "comment on issue #N", "label issue #N", "search issues for X" — even when the user does not say "Gitea". Not pull requests -> `gitea-prs`. Not label or milestone definitions -> `gitea-labels-milestones`.

Requires Gitea MCP server configured with write:issue and write:repository token scopes. Requires git remote "origin" pointing to the Gitea instance for owner/repo resolution when invoked directly by a human; an orchestrating caller (e.g. gitea-workflow) may pass owner/repo already resolved.

Gotchas

list_issues mixes in PRs unless you filter. Issues and PRs share one number space; pass type: "issues" to exclude PRs (or "pulls"). is_pull is returned only by issue_read method: "get" — on a list item the only tell is html_url's path segment (/issues/ vs /pulls/).
Label IDs and names are not interchangeable. issue_write takes numeric IDs only; list_issues and search_issues filter by name; issue_read "get" returns names but "get_labels" returns full objects with IDs. Resolve via gitea-labels-milestones unless the caller named exact labels.
A merge does not itself close the issue. Gitea has no close-on-merge event, but a Fixes #N in the merged commits can, depending on merge style (gitea-prs). Re-read its state after a merge before closing it manually.
404 may mean 403. Gitea hides permission errors as not-found — check write:issue scope before concluding the issue doesn't exist.

Step 1 — Resolve owner and repo

Skip if an orchestrating caller already passed owner/repo in, or the action is search (cross-repository, needs only a query). Otherwise, before any tool call:

rtk git remote get-url origin

No origin, or not a Gitea URL: stop and report "No Gitea remote found — set origin to your Gitea instance URL."

Step 2 — Dispatch

One invocation takes one row. Read only the reference(s) that row names — the call signatures were verified against the live MCP schema and differ from the published API docs in ways the body does not restate.

Invocation	Flow	Read
`/gitea-issues` or `/gitea-issues list`	List issues with `type: "issues"` so PRs are excluded, optionally filtered by state	`references/issues.md`
`/gitea-issues <N>`	Get one issue, routing to `gitea-prs` when the number turns out to be a PR	`references/issues.md`
`/gitea-issues <N> comments`	Get an issue's comments	`references/issues.md`
`/gitea-issues <N> labels`	Get an issue's labels as full objects, IDs included	`references/issues.md`
`/gitea-issues close <N>`	Close an issue by updating its state	`references/issues.md`
`/gitea-issues comment <N>`	Add a comment drawn from conversation context, never one invented to fill the gap — a comment on a live issue is not cheap to undo	`references/issues.md`
`/gitea-issues label <N>`	Apply, replace or remove labels using IDs resolved by `gitea-labels-milestones`	`references/issues.md`
`/gitea-issues create`	Create an issue — Step 3 first	`references/enrichments.md`, then `references/issues.md`
`/gitea-issues search <query>`	Cross-repo search, narrowed by owner, state, type or labels	`references/search.md`

Step 3 — Create

Only the create flow reaches this step.

Take title and body from conversation context — the most recent task, bug report, or explicit statement. An empty body is an acceptable fallback, an invented one is not.
Run the enrichments in references/enrichments.md, then create with the resolved IDs per references/issues.md. Omitting a parameter always beats guessing its value — a wrong milestone or assignee is harder to notice than a missing one.
Fire immediately, with no confirmation step. A create is cheap to undo by closing, so a gate here only costs a round trip.

Step 4 — Report

Reads: a compact table or numbered list — number, title, state, labels, milestone.

Writes: what was created or updated, with the issue number and the URL when one is returned.

Errors: the HTTP code and message as returned, without paraphrasing either.

4.5 KiB Raw Blame History