@amonstack/gitea-mcp 0.1.3 → 0.2.0

package/README.md

@@ -18,15 +18,17 @@ The server communicates over stdio and wraps the [Gitea REST API
 
 ## Installation
 
-### From GitHub Packages
+### From npm
 
 ```bash
-npm set @amonstack:registry https://npm.pkg.github.com
-npm set //npm.pkg.github.com/:_authToken YOUR_GITHUB_PAT
 npm install -g @amonstack/gitea-mcp
 ```
 
-Your GitHub PAT needs the `read:packages` scope.
+Or run directly without global install:
+
+```bash
+npx @amonstack/gitea-mcp
+```
 
 ### Build from source
 
@@ -95,6 +97,18 @@ Add to your opencode MCP configuration:
 
 If you built from source, use `node /path/to/gitea-mcp/dist/cli.js` instead.
 
+opencode also loads native **skills** — one per action (find, create, update,
+label, summarize, plan milestones, resolve repo) — that teach the assistant the
+safest workflow for that action, including pre-use checks and pitfalls. Install
+them once:
+
+```bash
+gitea-mcp skills install            # global (~/.config/opencode/skills/)
+gitea-mcp skills install --project  # this project (./.opencode/skills/)
+```
+
+Then restart opencode. See [AI Guidance & Skills](#ai-guidance--skills) below.
+
 ### Other MCP Clients
 
 Any client that supports stdio-based MCP servers can use `gitea-mcp`. After
@@ -158,6 +172,42 @@ gitea-mcp
 | `list_my_repos` | List repositories accessible to the authenticated user |
 | `resolve_repo` | Auto-detect `owner` and `repo` from a local git remote URL |
 
+## AI Guidance & Skills
+
+The server ships guidance so assistants use the tools correctly and safely,
+through three channels:
+
+- **`instructions` (on connect)** — a concise strategy the server sends during the
+  MCP handshake; capable clients inject it into the system prompt automatically.
+- **Tool descriptions** — every tool's description flags its key risk (pagination,
+  label ID-vs-name, destructive scope) and a minimal usage example.
+- **Prompts & resources** — workflow templates (`triage_issues`,
+  `summarize_issue`, `audit_labels`, `milestone_report`) and on-demand reference
+  docs (field reference, label guide, tool cookbook) for clients that surface them.
+
+### opencode skills
+
+For opencode, the server ships a set of **action-scoped skills** — one per
+workflow, so the assistant loads only the guidance it needs (and never, say,
+delete instructions while creating). Install them with the
+`gitea-mcp skills install` command shown in the opencode section above.
+
+| Skill | Invoke when |
+|-------|-------------|
+| `gitea-find-issues` | discovering / reading / triaging issues |
+| `gitea-create-issue` | creating an issue (after a duplicate check) |
+| `gitea-update-issue` | editing fields, closing, clearing assignee/milestone |
+| `gitea-label-issue` | adding / replacing / removing / clearing labels on an issue |
+| `gitea-manage-labels` | creating or editing label definitions |
+| `gitea-summarize-issue` | reading and summarizing an issue's discussion |
+| `gitea-plan-milestones` | creating / editing / closing milestones |
+| `gitea-resolve-repo` | resolving owner/repo or listing repositories |
+
+Each skill is a short, AI-facing action flow (purpose, when to use, when not to,
+rules, and what to check first). Destructive single-tool actions (delete issue /
+comment / label / milestone) are intentionally left to the tool descriptions so
+they never contaminate a creative workflow.
+
 ## Development
 
 ```bash
@@ -175,15 +225,8 @@ npm ci
 | `make test-integration` | Run integration tests (needs live Gitea instance) |
 | `make dev` | Run directly with tsx |
 
-### Project layout
-
-```
-src/
-  cli.ts           # Entry point
-  server.ts        # MCP server setup and tool registration
-  tools.ts         # Zod input schemas for all tools
-  gitea-client.ts  # REST client wrapping Gitea /api/v1 endpoints
-```
+For the full architecture — module layout, dependency graph, core patterns, and
+the guide to adding a new tool — see [`docs/architecture.md`](docs/architecture.md).
 
 ## License
 

package/README.zh-CN.md

@@ -17,15 +17,17 @@ opencode、Cursor 等）后，AI 助手即可通过自然语言在 Gitea 实例
 
 ## 安装
 
-### 从 GitHub Packages 安装
+### 从 npm 安装
 
 ```bash
-npm set @amonstack:registry https://npm.pkg.github.com
-npm set //npm.pkg.github.com/:_authToken <你的 GitHub PAT>
 npm install -g @amonstack/gitea-mcp
 ```
 
-GitHub PAT 需要 `read:packages` 权限。
+或无需全局安装，直接运行：
+
+```bash
+npx @amonstack/gitea-mcp
+```
 
 ### 从源码构建
 
@@ -94,6 +96,17 @@ node dist/cli.js
 
 如果从源码构建，将 `command` 改为 `node /path/to/gitea-mcp/dist/cli.js`。
 
+opencode 还会加载原生**技能（skills）**——按动作拆分（查找、创建、更新、打
+标签、总结、规划里程碑、解析仓库等），教会助手针对该动作的最安全工作流，含
+使用前检查与各类陷阱。一次性安装：
+
+```bash
+gitea-mcp skills install            # 全局（~/.config/opencode/skills/）
+gitea-mcp skills install --project  # 仅当前项目（./.opencode/skills/）
+```
+
+然后重启 opencode。详见下方 [AI 引导与技能](#ai-引导与技能)。
+
 ### 其他 MCP 客户端
 
 任何支持 stdio 方式运行 MCP 服务端的客户端都可以使用。安装完成后设置环境
@@ -157,6 +170,39 @@ gitea-mcp
 | `list_my_repos` | 列出当前用户可访问的仓库 |
 | `resolve_repo` | 从本地 git 仓库的远程地址自动检测 `owner` 和 `repo` |
 
+## AI 引导与技能
+
+服务端内置了引导内容，让助手正确、安全地使用工具，分三个通道：
+
+- **`instructions`（连接时）** —— 服务端在 MCP 握手时下发一份精炼策略；支持的
+  客户端会自动注入系统提示。
+- **工具描述** —— 每个工具的描述都标出其关键风险（分页、标签 ID 与名称、破坏性
+  作用范围）和最小用法示例。
+- **Prompts 与 Resources** —— 工作流模板（`triage_issues`、`summarize_issue`、
+  `audit_labels`、`milestone_report`）与按需参考文档（字段参考、标签指南、工具
+  食谱），供支持的客户端使用。
+
+### opencode 技能
+
+对 opencode，服务端内置了一组**按动作划分的技能**——每个工作流一个，助手只
+加载所需指引（避免例如创建时把删除说明一并带入造成幻觉）。用上面 opencode
+小节展示的 `gitea-mcp skills install` 命令安装。
+
+| 技能 | 何时触发 |
+|------|----------|
+| `gitea-find-issues` | 发现 / 读取 / 分流 issues |
+| `gitea-create-issue` | 创建 issue（先做查重） |
+| `gitea-update-issue` | 编辑字段、关闭、清空负责人/里程碑 |
+| `gitea-label-issue` | 为 issue 增加 / 替换 / 移除 / 清空标签 |
+| `gitea-manage-labels` | 创建或编辑标签定义 |
+| `gitea-summarize-issue` | 读取并总结某 issue 的讨论 |
+| `gitea-plan-milestones` | 创建 / 编辑 / 关闭里程碑 |
+| `gitea-resolve-repo` | 解析 owner/repo 或列出仓库 |
+
+每个技能都是面向 AI 的简短动作流程（目的、何时用、何时不用、规则、先检查什么）。
+破坏性的单工具操作（删除 issue / 评论 / 标签 / 里程碑）有意仅保留在工具描述里，
+不会污染创建类工作流。
+
 ## 二次开发
 
 ```bash
@@ -174,15 +220,8 @@ npm ci
 | `make test-integration` | 运行集成测试（需要可用的 Gitea 实例） |
 | `make dev` | 通过 tsx 直接运行 |
 
-### 项目结构
-
-```
-src/
-  cli.ts           # 入口文件
-  server.ts        # MCP 服务端搭建与工具注册
-  tools.ts         # 所有工具的 Zod 输入模式定义
-  gitea-client.ts  # 封装 Gitea /api/v1 端点的 REST 客户端
-```
+完整的架构说明（模块布局、依赖关系、核心模式，以及新增工具的指引）请参阅
+[`docs/architecture.md`](docs/architecture.md)。
 
 ## 许可证
 

package/dist/assets/instructions.md

@@ -0,0 +1,63 @@
+# Gitea MCP — usage strategy
+
+You manage Gitea issues, comments, labels, and milestones through this MCP server.
+Every tool returns Gitea's JSON verbatim as text. Follow these rules to use them
+correctly.
+
+## Resolve owner/repo FIRST (most common failure)
+
+Most tools target one repository and need both `owner` and `repo`. They resolve in
+this order:
+
+1. The `owner` / `repo` arguments you pass to the call.
+2. `GITEA_DEFAULT_OWNER` / `GITEA_DEFAULT_REPO` env vars (set at server start).
+3. The `resolve_repo` tool (detects owner/repo from a local git remote).
+
+If neither argument nor env var is set, the call errors. Before a batch of work on a
+repo you have not used this session, call `resolve_repo` (or confirm the env defaults)
+once and reuse the result — do not guess.
+
+## Labels: IDs vs names (critical gotcha)
+
+Label endpoints are NOT consistent — mixing them up silently fails or hits the wrong label:
+
+- `add_issue_labels`, `replace_issue_labels` → take label **names** (`string[]`).
+- `remove_issue_label` → takes a label **ID** (`number`). You must `list_labels` first to get IDs.
+- `create_issue` / `update_issue` `labels` field → takes label **IDs** (`number[]`).
+
+Always `list_labels` before any label mutation so you use the right identifier, and
+prefer `replace_issue_labels` (name-based) when you want a known final set.
+
+## Comments use comment IDs, not issue numbers
+
+`update_comment` and `delete_comment` take the comment `id`, NOT the issue `index`.
+`list_comments` returns each comment's `id`. Never reuse an issue number where a
+comment id is required.
+
+## Pagination
+
+List endpoints are 1-based: `page` starts at 1, `limit` max 100. To fetch everything,
+page forward until a page returns fewer than `limit` items (or an empty page). Do not
+assume one page is complete.
+
+## Destructive operations — confirm before running
+
+These are irreversible on most Gitea instances (no trash/recycle):
+
+- `delete_issue`, `delete_label`, `delete_milestone`, `delete_comment`
+- `clear_issue_labels`, `replace_issue_labels` (replaces the ENTIRE label set)
+
+Confirm the target id/index and scope with the user before calling. For labels,
+`replace_issue_labels` overwrites — read current labels first if any must survive.
+
+## Search vs list
+
+- `list_issues` — one repo, paginated, filterable by state/labels.
+- `search_issues` — across ALL repos the token can see, by keyword/type/state. Use it
+  for "find issues about X" or duplicate detection, not for listing one repo.
+
+## Error format
+
+Failed calls throw `Gitea API error (<status>): <body>`. Read the status: 401/403 →
+token scope/expiry; 404 → wrong owner/repo or no permission; 409 → conflict;
+422 → validation. Do not retry blindly on 4xx.

package/dist/assets/resources/field-reference.md

@@ -0,0 +1,48 @@
+# Gitea object field reference
+
+The shapes of the JSON objects these tools return (verbatim from the Gitea API).
+Use this to read results correctly and pick the right identifier.
+
+## Issue
+- `id` (number) — internal id. NOT used by tools; tools use `number`.
+- `number` (number) — the issue index shown in the URL (#42). This is the `index`
+  passed to get_issue / update_issue / delete_issue / comments tools.
+- `title` (string), `body` (string?), `state` ("open" | "closed")
+- `html_url`, `url` (string)
+- `comments` (number) — comment COUNT, not the comments themselves
+- `labels` (Label[])
+- `assignee` (User?), `assignees` (User[]?)
+- `milestone` (Milestone?)
+- `repository` (Repository) — present on search_issues results
+- `created_at`, `updated_at` (string ISO); `closed_at` (string?, when closed)
+
+## Label
+- `id` (number) — used by remove_issue_label / update_label / delete_label
+- `name` (string) — used by add_issue_labels / replace_issue_labels
+- `color` (string) — 6-digit hex, with or without "#"
+- `description` (string?)
+
+## User
+- `id` (number), `login` (string), `full_name` (string?), `avatar_url` (string),
+  `email` (string?)
+
+## Milestone
+- `id` (number) — used by get/update/delete_milestone; also the `milestone` value on
+  create/update_issue
+- `title` (string), `description` (string?), `state` ("open" | "closed")
+- `open_issues` (number), `closed_issues` (number) — counts for progress
+- `due_on` (string?, ISO)
+
+## Comment
+- `id` (number) — used by update_comment / delete_comment. NOT the issue number.
+- `body` (string) — Markdown
+- `html_url` (string), `created_at`, `updated_at` (string ISO)
+- `user` (User) — comment author
+
+## Repository (embedded on issues)
+- `id` (number), `full_name` (string "owner/repo"), `name` (string),
+  `owner` ({ login: string })
+
+## Repo (from list_my_repos)
+- `id`, `full_name`, `name`, `owner` (User), `description?`, `html_url`,
+  `default_branch?`, `created_at`, `updated_at`

package/dist/assets/resources/label-guide.md

@@ -0,0 +1,47 @@
+# Label management guide
+
+Labels are the most error-prone area because endpoints mix **names** and **ids**.
+
+## The name-vs-id matrix (memorize)
+
+| Operation | Identifier | Type |
+|---|---|---|
+| `add_issue_labels` | name | `string[]` |
+| `replace_issue_labels` | name | `string[]` |
+| `remove_issue_label` | **id** | `number` |
+| `create_issue` / `update_issue` `.labels` | **id** | `number[]` |
+| `update_label` / `delete_label` | **id** | `number` |
+
+**Workflow rule:** call `list_labels` first and keep the `id`↔`name` map for the
+whole session. Translate before any call that needs the other form.
+
+## Conventions
+
+- **Color:** 6-digit hex, with or without `#`. Keep a consistent palette per repo.
+- **Names are unique** per repo. Rename with `update_label` (by id); never recreate
+  to rename.
+- **Scoped/exclusive labels** use `scope/name` (e.g. `priority/low`, `priority/high`).
+  Within a scope, labels are mutually exclusive — adding `priority/high` removes
+  `priority/low`. Use this intentionally for single-value dimensions (priority,
+  type, status); use plain labels for multi-value dimensions (topic, team).
+
+## Safe operations
+
+- **Add one label without disturbing others** → `add_issue_labels(["name"])`
+  (additive, by name).
+- **Remove one label** → `remove_issue_label(id)` (by id; get it from the issue's
+  `labels`).
+- **Set an exact known set** → `replace_issue_labels(["a","b"])` — but read the
+  current labels first and confirm, since it removes everything not listed.
+- **Bulk cleanup** → `delete_label(id)` removes the label from EVERY issue; only
+  after user confirmation.
+
+## Anti-patterns
+
+- Passing a label **name** to `remove_issue_label` (needs id) — hits the wrong id
+  or 404s.
+- Passing a label **id** to `add_issue_labels` (needs name) — 404s.
+- Using `update_issue({ labels })` to "add" a label — it REPLACES the whole set.
+  Use `add_issue_labels` instead.
+- Deleting a label to "remove it from one issue" — that removes it from all issues.
+  Use `remove_issue_label` for one issue.

package/dist/assets/resources/tool-cookbook.md

@@ -0,0 +1,51 @@
+# Tool cookbook — task → tool recipes
+
+Quick recipes for common goals. Always resolve owner/repo first (explicit args,
+`GITEA_DEFAULT_OWNER`/`REPO`, or `resolve_repo`).
+
+## Discover where to work
+- One local repo → `resolve_repo({})` once, reuse `{owner, repo}`.
+- Across all repos → `list_my_repos({ page: 1, limit: 20 })`, page as needed.
+
+## Read / report
+- One issue's full picture → `get_issue` then `list_comments` (mind: list_comments
+  is one default page; long threads may be truncated).
+- All open issues in a repo → `list_issues({ state: "open", page: 1, limit: 50 })`,
+  page until a page returns < 50.
+- Issues across repos by keyword / duplicate check → `search_issues({ query, type:
+  "issues" })`.
+- Milestone progress → `list_milestones({ state: "all" })` (default omits closed!).
+
+## Create
+- New issue with labels → `list_labels` (to get ids) → `create_issue({ title, body,
+  labels: [ids] })`. Or create then `add_issue_labels([names])`.
+
+## Edit (non-destructive)
+- Change title/body/assignee → `update_issue` (PATCH; only given fields change).
+- Add ONE label → `add_issue_labels(["name"])` (additive, by name).
+- Remove ONE label → `remove_issue_label(id)` (by id).
+
+## Destructive (confirm first)
+- Close an issue → `update_issue({ state: "closed" })` (preferred over delete).
+- Delete an issue → `delete_issue` (irreversible).
+- Replace all labels → `replace_issue_labels(["a","b"])` (overwrites whole set).
+- Clear all labels → `clear_issue_labels`.
+- Delete a label → `delete_label(id)` (removes from EVERY issue).
+- Delete a milestone → prefer `update_milestone({ state: "closed" })`; `delete_milestone`
+  detaches its issues (they keep existing, milestone becomes null).
+
+## Pagination pattern (all list tools)
+```
+page = 1
+loop:
+  res = list_X({ ..., page, limit })
+  process(res)
+  if res.length < limit: break
+  page += 1
+```
+
+## Error triage
+- 401/403 → token scope/expiry. Ask user; don't loop.
+- 404 → wrong owner/repo or no permission.
+- 409 → conflict (e.g. duplicate label name).
+- 422 → validation (bad color, malformed date).

package/dist/assets/skills/gitea-create-issue/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: gitea-create-issue
+description: Invoke to CREATE / FILE / OPEN a new Gitea issue. The flow checks for an existing duplicate first, then creates. Do NOT invoke to edit/close (gitea-update-issue), delete (no skill — destructive), read/find (gitea-find-issues), or attach labels (gitea-label-issue).
+---
+
+# gitea-create-issue
+
+Open one new issue after ruling out a duplicate. Tools: `search_issues`, `create_issue`.
+
+## Prerequisites
+- Resolve `owner`+`repo`: pass explicitly, else `GITEA_DEFAULT_OWNER`/`GITEA_DEFAULT_REPO`, else `resolve_repo` (gitea-resolve-repo). Never guess — wrong values create the issue in the wrong repo.
+
+## Flow
+1. DUPLICATE CHECK (always first): `search_issues({ query: "<title keywords>", type: "issues" })`. If a match exists, comment on it (gitea-summarize-issue, then `create_comment`) instead of creating a duplicate. Do NOT skip this — creation does not de-duplicate.
+2. CREATE: `create_issue({ title, body?, assignees? })`.
+
+## create_issue
+- RULES: `title` required; `body` is Markdown. Use `assignees` (array); do NOT also set the deprecated single `assignee`.
+- Do NOT pass `labels` or `milestone` here: `labels` expect IDs (error-prone) and milestone needs an id. Create WITHOUT them, then attach labels by name via `add_issue_labels` (gitea-label-issue) and set the milestone via `update_issue` (gitea-update-issue).
+- CHECK FIRST: confirm no duplicate (step 1) and that `owner`/`repo` are correct before writing.
+- CHECK AFTER: the returned object's `number` is the new issue index.

package/dist/assets/skills/gitea-find-issues/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: gitea-find-issues
+description: Invoke to DISCOVER or READ Gitea issues — listing one repo's issues, cross-repo keyword search, reading a single issue, or triage. Do NOT invoke to create/edit/close/delete (gitea-create-issue / gitea-update-issue), to manage labels (gitea-label-issue), or to read the comment discussion (gitea-summarize-issue).
+---
+
+# gitea-find-issues
+
+Read-only issue discovery. Tools: `list_issues`, `search_issues`, `get_issue`.
+
+## Prerequisites
+- Resolve `owner`+`repo` for `list_issues`/`get_issue`: pass explicitly, else `GITEA_DEFAULT_OWNER`/`GITEA_DEFAULT_REPO`, else `resolve_repo` (gitea-resolve-repo). Never guess — wrong values 404 or silently target the wrong repo.
+- Paginate 1-based, `limit` ≤ 100. A page is final ONLY when it returns fewer than `limit` items. Always set `limit` (default page size is server-controlled).
+
+## Choose the tool
+- ONE repo's issues, filtered by state/labels → `list_issues`.
+- ACROSS repos by keyword, or duplicate check → `search_issues` (global; no owner/repo).
+- ONE issue's full detail → `get_issue`.
+
+## list_issues
+- RULES: `labels` = comma-separated NAMES, AND-matched; a mistyped or non-existent name returns EMPTY with no error. Results include pull requests (no `type` filter here); identify a PR by a non-null `pull_request` field in the JSON.
+- CHECK FIRST: confirm label names via `list_labels` (gitea-manage-labels) before filtering.
+- CHECK AFTER: if `length === limit`, fetch the next page before treating the list as complete.
+
+## search_issues
+- RULES: GLOBAL — no owner/repo; each result carries its own `repository`. Returns issues AND PRs by default; set `type: "issues"` to exclude PRs (`type: "pulls"` for PRs only). `labels` = names. `query` matches title + body.
+- CHECK FIRST: set `type` deliberately.
+- CHECK AFTER: page fully if completeness matters.
+
+## get_issue
+- RULES: pass `index` = the issue `number` (URL #42 → 42), never the internal `id`.
+- NOTE: the `comments` field is a COUNT only — to read the discussion use `list_comments` (gitea-summarize-issue).

package/dist/assets/skills/gitea-label-issue/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: gitea-label-issue
+description: Invoke to ATTACH labels to ONE Gitea issue — add, replace, remove one, or clear all. Covers the label name-vs-id pitfall. Do NOT invoke to create/edit/delete the repo's label definitions (gitea-manage-labels) or to create/edit the issue (gitea-create-issue / gitea-update-issue).
+---
+
+# gitea-label-issue
+
+Manage the labels ON one issue. Tools: `list_labels`, `add_issue_labels`, `replace_issue_labels`, `remove_issue_label`, `clear_issue_labels`.
+
+## Prerequisites
+- Resolve `owner`+`repo`: pass explicitly, else `GITEA_DEFAULT_OWNER`/`GITEA_DEFAULT_REPO`, else `resolve_repo` (gitea-resolve-repo).
+
+## CRITICAL — name vs id (the endpoints are inconsistent)
+- BY NAME (string[]): `add_issue_labels`, `replace_issue_labels`.
+- BY ID (number): `remove_issue_label` (param `id`).
+Resolve names→ids via `list_labels` when you need an id.
+
+## Choose the tool
+- ADD labels (keep existing) → `add_issue_labels({ index, labels: [names] })`.
+- SET the exact label set (overwrites all) → `replace_issue_labels({ index, labels: [names] })`.
+- REMOVE ONE label → `remove_issue_label({ index, id })` (id, not name).
+- REMOVE ALL → `clear_issue_labels({ index })`.
+
+## Rules
+- `index` = issue `number` (URL #N → N).
+- Adding a non-existent NAME → 404. Confirm names via `list_labels` first.
+- Scoped/exclusive labels (`scope/name`) are mutually exclusive within a scope — adding one may replace another in the same scope.
+- CHECK FIRST: for `replace`, `get_issue` (gitea-find-issues) to see current labels so you don't drop one unintentionally; for `remove`, `list_labels` to resolve the id.

package/dist/assets/skills/gitea-manage-labels/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: gitea-manage-labels
+description: Invoke to CREATE or EDIT a Gitea label in the repo's taxonomy (the set of available label definitions). Do NOT invoke to attach labels to an issue (gitea-label-issue) or to delete a label (destructive — no skill).
+---
+
+# gitea-manage-labels
+
+Create or edit the repo's label definitions. Tools: `list_labels`, `create_label`, `update_label`.
+
+## Prerequisites
+- Resolve `owner`+`repo`: pass explicitly, else `GITEA_DEFAULT_OWNER`/`GITEA_DEFAULT_REPO`, else `resolve_repo` (gitea-resolve-repo).
+
+## list_labels
+- Enumerate available labels (name, id, color, description). Use to resolve names→ids and to check name uniqueness before create. Paginate 1-based, `limit` ≤ 100.
+
+## create_label
+- RULES: `name` required and UNIQUE per repo (duplicate → conflict). `color` = 6-digit hex, with or without leading `#` (e.g. `#ff0000` or `ff0000`). `description` optional.
+- CHECK FIRST: `list_labels` to avoid a name collision.
+
+## update_label
+- RULES: identifies the label by `id` (number). PATCH — only `name` / `color` / `description` you pass change; omit = unchanged. `color` stays 6-digit hex.
+- NOTE: renaming or recoloring a label updates it on EVERY issue that currently has it.

package/dist/assets/skills/gitea-plan-milestones/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: gitea-plan-milestones
+description: Invoke to CREATE, EDIT, or CLOSE a Gitea milestone, or to list/inspect milestones for planning. Do NOT invoke to delete a milestone (destructive — no skill) or to set an issue's milestone (that is gitea-update-issue).
+---
+
+# gitea-plan-milestones
+
+Create / edit / close milestones. Tools: `list_milestones`, `get_milestone`, `create_milestone`, `update_milestone`.
+
+## Prerequisites
+- Resolve `owner`+`repo`: pass explicitly, else `GITEA_DEFAULT_OWNER`/`GITEA_DEFAULT_REPO`, else `resolve_repo` (gitea-resolve-repo).
+
+## list_milestones — DEFAULT-OPEN TRAP
+- Default returns ONLY open milestones. Pass `state: "all"` or `state: "closed"` to see the rest, or you will silently miss closed/completed milestones. Paginate 1-based, `limit` ≤ 100.
+
+## create_milestone
+- RULES: `title` required; `description` optional; `due_on` = ISO 8601 (e.g. `2025-12-31T23:59:59Z`). Returns the new milestone including its `id`.
+
+## update_milestone
+- RULES: identifies by `id` (number). PATCH — only `title` / `description` / `due_on` / `state` you pass change; omit = unchanged. State is `open` | `closed`.
+- NOTE: CLOSING a milestone does NOT close its issues — they stay open. Close issues separately (gitea-update-issue) before or after.
+
+## get_milestone
+- Read one milestone by `id`: includes `open_issues` / `closed_issues` counts for progress (progress = closed / (open + closed)).

package/dist/assets/skills/gitea-resolve-repo/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: gitea-resolve-repo
+description: Invoke to RESOLVE which owner/repo the other gitea tools should target (auto-detect from a git remote) or to LIST repositories the token can access. Run FIRST when the target repository is unknown. Do NOT invoke for issue/comment/label/milestone work once owner/repo are known.
+---
+
+# gitea-resolve-repo
+
+Discover the target repository. Tools: `resolve_repo`, `list_my_repos`.
+
+## resolve_repo
+- Reads the `origin` remote of the git repo at `path` (default: current directory) and parses owner/repo from SSH (`git@gitea.example:owner/repo.git`) or HTTPS (`https://gitea.example/owner/repo.git`) URLs.
+- Throws if there is no `origin` remote or the URL is unparseable. Do NOT guess owner/repo from context — call this, or ask the user.
+
+## list_my_repos
+- Lists repositories the token can access. GLOBAL. Returns large objects — paginate (`limit` ≤ 100) and read only the fields you need (name, full_name, owner.login).
+
+## Resolution order (every repo-scoped tool)
+explicit `owner`/`repo` args → `GITEA_DEFAULT_OWNER`/`GITEA_DEFAULT_REPO` → `resolve_repo`. If none resolve, the tool throws `owner and repo are required`. Wrong values 404 or silently target the wrong repo — never guess.

package/dist/assets/skills/gitea-summarize-issue/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: gitea-summarize-issue
+description: Invoke to READ and SUMMARIZE an issue's discussion — the issue body plus its comment thread. Do NOT invoke to create/edit an issue (gitea-create-issue / gitea-update-issue), post or edit a comment (no skill — single tool), or manage labels/milestones.
+---
+
+# gitea-summarize-issue
+
+Read an issue and its discussion, then synthesize. Tools: `get_issue`, `list_comments`.
+
+## Prerequisites
+- Resolve `owner`+`repo`: pass explicitly, else `GITEA_DEFAULT_OWNER`/`GITEA_DEFAULT_REPO`, else `resolve_repo` (gitea-resolve-repo).
+
+## Flow
+1. `get_issue({ index })` — `index` = issue `number` (URL #N → N), never the internal `id`. The `comments` field is only a COUNT.
+2. `list_comments({ index })` — returns the comment thread, oldest-first.
+
+## list_comments — TRUNCATION TRAP
+- This tool passes NO page/limit and returns at most the server's default page size. For long threads the list is SILENTLY TRUNCATED. If the `comments` count (from `get_issue`) exceeds the number returned, warn that part of the thread is missing and do NOT claim a complete summary.
+
+## Synthesis
+- Report the issue state (open/closed), the body's ask, then the thread's consensus / decision / open questions. Attribute by author. Flag unresolved disagreement explicitly — do not paper over it.

package/dist/assets/skills/gitea-update-issue/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: gitea-update-issue
+description: Invoke to EDIT fields, CLOSE, REOPEN, or CLEAR assignee/milestone on ONE existing Gitea issue. Do NOT invoke to create (gitea-create-issue), delete (destructive — no skill), find/read (gitea-find-issues), or change a single label (gitea-label-issue).
+---
+
+# gitea-update-issue
+
+Edit one issue's fields or change its state. Tools: `get_issue`, `update_issue`.
+
+## Prerequisites
+- Resolve `owner`+`repo`: pass explicitly, else `GITEA_DEFAULT_OWNER`/`GITEA_DEFAULT_REPO`, else `resolve_repo` (gitea-resolve-repo).
+- There is NO optimistic locking — always read current state first.
+
+## Flow
+1. READ CURRENT: `get_issue({ index })` — `index` = issue `number` (URL #N → N), never the internal `id`.
+2. APPLY: `update_issue({ index, ...changedFields })`.
+
+## update_issue
+- RULES: PATCH — only fields you pass change; omit = unchanged. To CLEAR a field pass its EMPTY form, do NOT omit it: `milestone: 0` clears the milestone, `assignees: []` clears assignees. Use `assignees` (array), not the deprecated `assignee`. State values are `open` | `closed`.
+- NOT FOR single-label changes: `labels` here are IDs and REPLACE the entire set — to add/remove one label use `add_issue_labels` / `remove_issue_label` (gitea-label-issue).
+- CHECK FIRST: `get_issue` for current values if state may have changed since your last read; state the intended change to the user before writing.

package/dist/cli.js

@@ -1,15 +1,27 @@
 #!/usr/bin/env node
 import { runServer } from "./server.js";
-const baseUrl = process.env.GITEA_BASE_URL;
-const token = process.env.GITEA_TOKEN;
-const defaultOwner = process.env.GITEA_DEFAULT_OWNER;
-const defaultRepo = process.env.GITEA_DEFAULT_REPO;
-if (!baseUrl || !token) {
-    console.error("GITEA_BASE_URL and GITEA_TOKEN environment variables are required");
-    process.exit(1);
+const argv = process.argv.slice(2);
+if (argv[0] === "skills") {
+    // `gitea-mcp skills ...` manages the bundled opencode skill. It needs no Gitea
+    // credentials, so it is dispatched before the env-var guard below.
+    const { runSkillsCommand } = await import("./skills.js");
+    runSkillsCommand(argv.slice(1)).catch((err) => {
+        console.error("Fatal error:", err);
+        process.exit(1);
+    });
+}
+else {
+    const baseUrl = process.env.GITEA_BASE_URL;
+    const token = process.env.GITEA_TOKEN;
+    const defaultOwner = process.env.GITEA_DEFAULT_OWNER;
+    const defaultRepo = process.env.GITEA_DEFAULT_REPO;
+    if (!baseUrl || !token) {
+        console.error("GITEA_BASE_URL and GITEA_TOKEN environment variables are required");
+        process.exit(1);
+    }
+    runServer(baseUrl, token, defaultOwner, defaultRepo).catch((err) => {
+        console.error("Fatal error:", err);
+        process.exit(1);
+    });
 }
-runServer(baseUrl, token, defaultOwner, defaultRepo).catch((err) => {
-    console.error("Fatal error:", err);
-    process.exit(1);
-});
 //# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;AAC3C,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC;AACtC,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC;AACrD,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;AAEnD,IAAI,CAAC,OAAO,IAAI,CAAC,KAAK,EAAE,CAAC;IACvB,OAAO,CAAC,KAAK,CAAC,mEAAmE,CAAC,CAAC;IACnF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,SAAS,CAAC,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,WAAW,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACjE,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;IACnC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAEnC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,QAAQ,EAAE,CAAC;IACzB,+EAA+E;IAC/E,mEAAmE;IACnE,MAAM,EAAE,gBAAgB,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;IACzD,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;QAC5C,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;QACnC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC;KAAM,CAAC;IACN,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;IAC3C,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC;IACtC,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC;IACrD,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;IAEnD,IAAI,CAAC,OAAO,IAAI,CAAC,KAAK,EAAE,CAAC;QACvB,OAAO,CAAC,KAAK,CAAC,mEAAmE,CAAC,CAAC;QACnF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,SAAS,CAAC,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,WAAW,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;QACjE,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;QACnC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}