Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

refactor(gitea): deep modules — split flat dispatch skill into 6 domain skills + orchestrator + agent (#67)

Browse Source
This commit was merged in pull request #67.
This commit is contained in:
Claude Code AI - Gitea MCP
2026-07-05 19:53:26 +00:00
parent 060771b481
commit bc7b3ecdbf
47 changed files with 2417 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
plugins/gitea/skills/gitea-releases/README.md Normal file
View File

@@ -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` | Tool parameters and response shapes derived from gitea-mcp source (see `references/sources.md`); input params for 3 of the 9 tools additionally live-cross-checked |
| `references/conventions.md` | Semver/draft/prerelease practitioner conventions and pagination behavior |
| `references/sources.md` | Research sources backing the call signatures and conventions |

52
plugins/gitea/skills/gitea-releases/SKILL.md Normal file
View File

@@ -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.
- **`is_draft`/`is_pre_release` are explicit booleans the caller sets on `create_release` — never inferred from `tag_name`.** Note the input param is `is_draft`, which maps to the `draft` field on the *response* object (see Dispatch table below and `references/call-signatures.md`) — `draft` is never a valid input key. 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` — Gitea is assumed to create the underlying tag automatically if `tag_name` doesn't already exist (this is plausible behavior inferred from the API shape, not directly confirmed in the research docs), so a separate `create_tag` call is only needed when you want to tag a commit without wrapping it in a release yet. Verify the tag exists afterward if this matters to the caller. 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`.

75
plugins/gitea/skills/gitea-releases/references/call-signatures.md Normal file
View File

@@ -0,0 +1,75 @@
---
topic: call-signatures
source_keys:
- gitea-mcp-repo
- gitea-mcp-slim-go
---
# Release and tag call signatures
Signatures and response shapes are derived from gitea-mcp source (`operation/*.go` and `slim.go`,
see `references/sources.md`) rather than copied from upstream API docs, which can drift from the
deployed gitea-mcp version — but this is a source-code extraction, not a live MCP tool call.
Input parameter schemas for 3 of the 9 tools here — `create_release`, `delete_tag`, and
`get_latest_release` — were additionally cross-checked live via `ToolSearch` against the deployed
`mcp__gitea__*` tools in session 2026-07-05, and confirmed to match exactly (required/optional
params and names). That check covered only input params for those 3 tools, not response shapes,
and not the other 6 tools — treat the rest of this document as source-derived, not live-verified.
`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 release. It is assumed (by analogy with typical "latest release" semantics) that this excludes drafts and prereleases, but that exclusion is not directly confirmed by any of the research docs — verify with `list_releases` if the caller depends on this.
**`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)
- Assumed (not confirmed by the research docs) that if `tag_name` doesn't already exist as a tag, Gitea creates it against `target` as part of this call. Verify with `get_tag`/`list_tags` afterward if the caller needs certainty.
**`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.
- Assumed by symmetry with `delete_release` (documented above as not deleting the underlying tag) to also not delete any release wrapping the tag — but this reverse direction is not independently confirmed by the research docs, and is the more dangerous direction to get wrong: an agent might skip an explicit `delete_release` call assuming the release survives. Verify with `list_releases`/`get_release` after calling `delete_tag` rather than assume.
## 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.

44
plugins/gitea/skills/gitea-releases/references/conventions.md Normal file
View File

@@ -0,0 +1,44 @@
---
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
`is_draft` and `is_pre_release` 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.
Note the input/output naming mismatch: the input param is `is_draft`, but the release object
returned by the API uses `draft` (and `prerelease`) as the field names. `draft` is never a valid
input key — passing `draft: true` to `create_release` is silently ignored rather than erroring.
## 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.

48
plugins/gitea/skills/gitea-releases/references/sources.md Normal file
View File

@@ -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`