holocron/plugins/gitea/.apm/skills/gitea-issues/SKILL.md at 78015893d4fdfe7235a3ad8fc517900216d47f4a

Files

Defame1297 78015893d4 refactor(gitea-issues): retrofit to the ADR-0020 context contract

Description 827 -> 182 chars, body 902 -> 584 words, Gotchas 7 entries/43% of
body -> 4/23.1%. Clears both size FAILs, the dangling-target FAIL and the Vale
CompositionNote error.

The dangling 'gitea-labels' target is gone with the composition sentence that
carried it -- a YAML fold artifact, not a typo: the '>'-folded scalar joined
'gitea-labels-' and 'milestones' across a line break, leaving the name terminal
and danglable. Both boundary names now sit whole on one source line each, and
both resolve.

Cut the second trigger register, the seven-verb capability enumeration, the
issue_write implementation detail and a gitea-branches boundary that defended
nothing. Two Gotchas deleted as spec restatement carried in references/, one as
a paraphrase of the step below it.

Closes a capability hole rather than papering over it: gitea-labels-milestones
routes label application here and has no issue_write, but no dispatch row
existed for add/replace/remove/clear_labels or get_labels. Both rows added.
The label ID/name Gotcha is now stated per method -- issue_write takes IDs,
list_issues and search_issues filter by name, issue_read 'get' returns names
but 'get_labels' returns full objects with IDs.

Drops a stale quotation of gitea-labels-milestones' description from
references/enrichments.md; that string went with its composition note.

Refs #99

2026-08-30 12:28:54 +00:00

4.3 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 — 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 returns PRs too. It has no type filter and both share one repo number space. is_pull appears only on issue_read method: "get", never on a list item — check it there before treating a number as an issue.
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 merged PR leaves its issue open. Gitea does not auto-close on merge the way GitHub does. Re-read the issue's state after a merge before closing it manually.
A 404 may really be a 403. Gitea hides permission errors as not-found — check the token's write:issue scope before concluding the issue does not exist.

Step 1 — Resolve owner and repo

An orchestrating caller may pass owner and repo in already; if so, skip this. The search row is cross-repository and needs only a query, so it skips this too. Otherwise, before any tool call:

git remote get-url origin

If origin is unset or the URL is 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, 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; every other row goes straight to its reference.

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.3 KiB Raw Blame History