plugins/gitea/skills/gitea-releases/README.md

@@ -0,0 +1,24 @@
+# gitea-releases
+
+Manage Gitea releases and tags — list, create, and delete releases (with draft/prerelease flags and notes) and their underlying tags.
+
+## What it does
+
+This skill handles release and tag operations for a Gitea repository. It creates releases from a tag/target commitish with title, notes, and draft/prerelease flags; lists and paginates releases and tags; retrieves the latest release; and deletes releases and tags as separate, independent destructive operations. It resolves the numeric release id required for deletion instead of assuming a tag name will work.
+
+## Usage
+
+```
+/gitea-releases
+```
+
+Describe your release/tag task: list releases, get the latest release, create a release (with a tag, target, and title), or delete a release or tag. The skill handles resolving the numeric release id where required and keeps release/tag deletion as distinct operations.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Skill instructions for agents |
+| `references/call-signatures.md` | Verified tool parameters and response shapes for all 9 release/tag tools |
+| `references/conventions.md` | Semver/draft/prerelease practitioner conventions and pagination behavior |
+| `references/sources.md` | Research sources backing the call signatures and conventions |

plugins/gitea/skills/gitea-releases/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: gitea-releases
+
+description: >
+  Use when managing Gitea releases and tags for a repository: listing, creating, or deleting
+  releases (with draft/prerelease flags and release notes), and listing, creating, or deleting the
+  underlying git tags. Use even if the user doesn't say "release" explicitly — "cut a v1.2.0",
+  "publish a prerelease", "tag this commit", or "what's the latest release" all apply. Do not use
+  for git branch or commit history operations (use gitea-branches) or for issue/PR management (use
+  gitea-issues / gitea-prs).
+
+metadata:
+  category: gitea
+  source_keys:
+    - gitea-mcp-repo
+    - gitea-mcp-slim-go
+    - context7-websites-gitea
+    - context7-gitea-tea-cli
+---
+
+## Gotchas
+
+- **`delete_release` takes a numeric `id`, never a tag name.** `delete_tag` is the mirror opposite — it takes the `tag_name` string, never a numeric id. These two tools are asymmetric on purpose; passing a tag name to `delete_release` or a numeric id to `delete_tag` fails. Always resolve the numeric release id via `list_releases` or `get_release` first if you only have a tag name in hand.
+- **Deleting a release does not delete its tag.** They are separate destructive operations against separate resources — a release is a wrapper (title, notes, draft/prerelease flags, assets) around a tag, not the tag itself. If the intent is to remove both, call `delete_release` and `delete_tag` separately.
+- **`list_releases`/`list_tags` default to `per_page: 20`**, unlike most other gitea-mcp tools which default to 30. There is no auto-pagination in the MCP layer — to get a complete result set, loop `page` upward until a page returns fewer than `per_page` results.
+- **`draft`/`is_pre_release` are explicit booleans the caller sets on `create_release` — never inferred from `tag_name`.** Practitioner convention (per the `tea` CLI) uses `-beta`/`-rc` suffixes for prereleases (e.g. `v2.0.0-beta.1`), but Gitea does not enforce or infer this from the tag string. If the user names a tag that looks like a prerelease, set `is_pre_release: true` explicitly rather than assuming the flag is redundant with the name.
+- **Tag names are conventionally semver, `v`-prefixed** (`v1.2.0`, `v2.0.0-beta.1`), but this is a practitioner convention, not a Gitea constraint — don't reject or rewrite a caller-supplied tag name that doesn't follow it.
+
+## Dispatch table
+
+| Action | Tool | Required params | Optional params |
+|---|---|---|---|
+| List releases | `list_releases` | `owner`, `repo` | `is_draft`, `is_pre_release`, `page` (default 1), `per_page` (default 20) |
+| Get one release | `get_release` | `owner`, `repo`, `id` (number) | — |
+| Get latest release | `get_latest_release` | `owner`, `repo` | — |
+| Create release | `create_release` | `owner`, `repo`, `tag_name`, `target`, `title` | `body`, `is_draft`, `is_pre_release` |
+| Delete release | `delete_release` | `owner`, `repo`, `id` (number) | — |
+| List tags | `list_tags` | `owner`, `repo` | `page` (default 1), `per_page` (default 20) |
+| Get one tag | `get_tag` | `owner`, `repo`, `tag_name` | — |
+| Create tag | `create_tag` | `owner`, `repo`, `tag_name` | `target`, `message` |
+| Delete tag | `delete_tag` | `owner`, `repo`, `tag_name` | — |
+
+`target` (on `create_release`/`create_tag`) is a commitish — a branch name, existing tag, or commit SHA — the point the new tag is cut from. See `references/call-signatures.md` for response shapes.
+
+## Workflow
+
+- [ ] **Creating a release:** Call `create_release` directly with `tag_name` + `target` + `title` — it creates the underlying tag automatically if `tag_name` doesn't already exist, so a separate `create_tag` call is only needed when you want to tag a commit without wrapping it in a release yet. Set `is_pre_release`/`is_draft` explicitly per the Gotchas above; don't leave them to default inference.
+- [ ] **Deleting a release safely:** Resolve the numeric id first — call `list_releases` (paginate if needed, see Gotchas) or `get_release` if the id is already known, find the entry matching the target `tag_name`, then call `delete_release` with that `id`. Never pass `tag_name` to `delete_release`.
+- [ ] **Deleting a tag along with its release:** Delete the release first (frees the id lookup), then call `delete_tag` with the `tag_name` separately — confirm both are intended before proceeding, since each is an independent irreversible operation.
+- [ ] **Listing completely:** If the caller needs all releases or tags (not just the first page), loop `page: 1, 2, 3...` until a response has fewer than `per_page` entries.
+
+If exact response field shapes or additional conventions are needed, read `references/call-signatures.md` and `references/conventions.md`.

plugins/gitea/skills/gitea-releases/references/call-signatures.md

@@ -0,0 +1,66 @@
+---
+topic: call-signatures
+source_keys:
+  - gitea-mcp-repo
+  - gitea-mcp-slim-go
+---
+
+# Release and tag call signatures
+
+Verified against the live MCP tool schemas at authoring time (not copied from upstream API docs,
+which can drift from the deployed gitea-mcp version). `owner` and `repo` are required strings on
+every tool below and are omitted from the per-tool lists for brevity.
+
+## Releases
+
+**`list_releases`**
+- Optional: `is_draft` (boolean), `is_pre_release` (boolean), `page` (number, default 1), `per_page` (number, default 20)
+- Returns an array of release objects (shape below), one page at a time.
+
+**`get_release`**
+- Required: `id` (number) — the release's numeric id, not its tag name.
+- Returns a single release object.
+
+**`get_latest_release`**
+- No parameters beyond `owner`/`repo`.
+- Returns a single release object for the most recently published (non-draft, non-prerelease by Gitea's own "latest" definition) release.
+
+**`create_release`**
+- Required: `tag_name` (string), `target` (string — branch, tag, or commit SHA to cut the tag from), `title` (string)
+- Optional: `body` (string — release notes), `is_draft` (boolean), `is_pre_release` (boolean)
+- If `tag_name` doesn't already exist as a tag, Gitea creates it against `target` as part of this call.
+
+**`delete_release`**
+- Required: `id` (number) — same numeric id as `get_release`. Does not accept `tag_name`.
+- Does not delete the underlying tag.
+
+**Release object shape** (returned by list/get/create/latest):
+```
+id, tag_name, target, title, body, draft, prerelease, html_url, author, created_at, published_at
+```
+`author` is the creator's login. `body` holds the release notes.
+
+## Tags
+
+**`list_tags`**
+- Optional: `page` (number, default 1), `per_page` (number, default 20)
+- Returns an array of `{ name, commit_sha }` — no `message` field on list responses.
+
+**`get_tag`**
+- Required: `tag_name` (string)
+- Returns `{ name, message, commit_sha }` — the only tag call that returns `message`.
+
+**`create_tag`**
+- Required: `tag_name` (string)
+- Optional: `target` (string — commitish to tag; if omitted, Gitea tags the default branch tip), `message` (string — annotated tag message)
+
+**`delete_tag`**
+- Required: `tag_name` (string). Does not accept a numeric id.
+- Does not delete any release wrapping the tag.
+
+## Pagination
+
+None of the list tools auto-paginate. To collect a full result set, call with `page: 1`, then
+`page: 2`, etc., stopping when a page returns fewer items than `per_page`. `list_releases` and
+`list_tags` default `per_page` to 20 — lower than the 30-default used by most other gitea-mcp list
+tools, so a caller assuming 30 will under-count pages needed for a fixed total.

plugins/gitea/skills/gitea-releases/references/conventions.md

@@ -0,0 +1,40 @@
+---
+topic: conventions
+source_keys:
+  - context7-websites-gitea
+  - context7-gitea-tea-cli
+---
+
+# Release and tag conventions
+
+Practitioner conventions that inform *how* to use the mechanics in `call-signatures.md` — not
+additional tool schemas.
+
+## Release wraps a tag, not the reverse
+
+A release is a title, body (notes), and draft/prerelease flags layered on top of an existing or
+newly-created tag. The tag is the git-level object (a name pointing at a commit); the release is a
+Gitea-level metadata wrapper around it. This is why `delete_release` and `delete_tag` are separate
+calls with separate identifiers (numeric id vs. tag name) — removing the wrapper never implies
+removing the underlying pointer, and vice versa.
+
+## Semver tag naming
+
+Per the `tea` CLI (the reference Gitea client), tag names conventionally follow semver with a `v`
+prefix: `v1.2.0`, `v2.0.0-beta.1`. This is a convention observed by tooling and humans, not a
+Gitea-enforced constraint — the API accepts any string as `tag_name`. Don't validate or rewrite a
+caller-supplied tag name against semver; just pass it through.
+
+## Draft and prerelease are explicit flags
+
+`draft` and `is_pre_release`/`prerelease` are booleans the caller sets directly on `create_release`
+— Gitea does not infer either from the tag name, even though the `-beta`/`-rc` suffix convention
+above is commonly used to signal a prerelease to humans. When a user asks to "cut a beta" or
+"publish a release candidate," set `is_pre_release: true` explicitly in the same call rather than
+relying on the tag string to carry that meaning.
+
+## Release notes sourcing
+
+Practitioner convention (per `tea`) is to source release notes (`body`) from a changelog file
+rather than typing them inline for each release — useful context when a caller asks to "generate"
+or "use the changelog for" release notes rather than write them from scratch.

plugins/gitea/skills/gitea-releases/references/sources.md

@@ -0,0 +1,48 @@
+# Sources
+
+## gitea-mcp-repo
+
+- **URL:** https://gitea.com/gitea/gitea-mcp
+- **Description:** Official gitea-mcp repository (v1.3.0); operation/*.go source files documenting all 55 MCP tools, their parameters, and CLI flags.
+- **Research doc:** plugins/gitea/docs/research/docs/gitea/api-reference.md (Releases and Tags section); plugins/gitea/docs/research/docs/gitea/troubleshooting.md (`delete_release` numeric-id gotcha, `per_page` defaults)
+
+**Contributing files:**
+- SKILL.md (Dispatch table, Gotchas)
+- references/call-signatures.md
+
+**Status:** `extracted`
+
+## gitea-mcp-slim-go
+
+- **URL:** https://gitea.com/gitea/gitea-mcp/raw/branch/main/operation/repo/slim.go
+- **Description:** Slim response shape structs from gitea-mcp source; defines exactly which fields the MCP server returns for tags and releases.
+- **Research doc:** plugins/gitea/docs/research/docs/gitea/api-reference.md (Releases and Tags response shapes)
+
+**Contributing files:**
+- references/call-signatures.md (release/tag object shapes)
+
+**Status:** `extracted`
+
+## context7-websites-gitea
+
+- **URL:** context7:/websites/gitea
+- **Description:** Official Gitea docs mirror on Context7 (docs.gitea.com content) — release and tag semantics, draft/prerelease behavior.
+- **Research doc:** plugins/gitea/docs/research/docs/gitea/workflow-conventions.md (Release and tag conventions section)
+
+**Contributing files:**
+- SKILL.md (Gotchas — draft/prerelease as explicit flags)
+- references/conventions.md
+
+**Status:** `extracted`
+
+## context7-gitea-tea-cli
+
+- **URL:** context7:/git_gitea_com/gitea_tea
+- **Description:** Official `tea` CLI (reference Gitea client) docs on Context7 — practitioner release/tag command patterns, semver tag conventions, draft/prerelease flags, release-notes-from-file conventions.
+- **Research doc:** plugins/gitea/docs/research/docs/gitea/workflow-conventions.md (Release and tag conventions section)
+
+**Contributing files:**
+- SKILL.md (Gotchas — semver tag naming)
+- references/conventions.md
+
+**Status:** `extracted`