gitea-cli-skill 0.1.8 → 0.2.0

package/assets/REFERENCE.md

@@ -0,0 +1,273 @@
+# gitea-cli Reference
+
+Full command reference and workflow details. This file is loaded on demand — the core rules and binary location are in SKILL.md.
+
+## Workflow: Issue 处理
+
+```bash
+# 1. 查看 open issues
+gitea-cli issue list --state open --output json
+
+# 2. 查看 issue 详情
+gitea-cli issue get <number> --output json
+
+# 3. 查找 label/milestone ID
+gitea-cli label list --output json
+gitea-cli milestone list --output json
+
+# 4. 更新 issue
+gitea-cli issue update <number> --label <id> --milestone <id>
+
+# 5. 添加评论
+gitea-cli issue comment create <number> -b "分析原因：..."
+
+# 6. 上传附件（图片自动嵌入为 markdown）
+gitea-cli issue attachment upload <number> ./screenshot.png
+
+# 7. 关闭 issue
+gitea-cli issue close <number>
+```
+
+## Workflow: PR 工作流
+
+```bash
+# 1. 创建 feature 分支
+gitea-cli branch create feature/xyz --from main
+
+# 2. 创建 PR
+gitea-cli pr create --title "feat: xxx" --head feature/xyz --base main --body "## Summary\n- Changes"
+
+# 3. 查看 PR 状态
+gitea-cli pr get <index> --output json
+
+# 4. 检查 CI
+gitea-cli actions run list --output json
+gitea-cli actions run jobs <run-id> --output json
+
+# 5. 合并 PR
+gitea-cli pr merge <index> --strategy squash --delete-branch
+```
+
+## Workflow: Release 发布
+
+```bash
+# 1. 查看最近提交
+gitea-cli commit list --branch main --limit 20 --output json
+
+# 2. 查看 tags/releases
+gitea-cli tag list --output json
+gitea-cli release list --output json
+
+# 3. 创建 tag + release
+gitea-cli tag create v1.0.0 --target main -m "Release v1.0.0"
+gitea-cli release create --tag v1.0.0 --name "v1.0.0" --body "## Changes\n- ..." --target main
+
+# 4. 上传 assets
+gitea-cli release asset upload v1.0.0 ./dist/binary --name binary-linux-amd64
+
+# 5. 确认
+gitea-cli release get v1.0.0 --output json
+gitea-cli release asset list v1.0.0 --output json
+```
+
+## Workflow: CI/CD 排障
+
+```bash
+gitea-cli actions run list --limit 10 --output json
+gitea-cli actions run jobs <run-id> --output json
+gitea-cli actions job logs <job-id> -o ./logs/
+gitea-cli actions job get <job-id> --output json
+gitea-cli actions workflow dispatch <workflow-id> --ref main
+gitea-cli actions artifact list --output json
+gitea-cli actions artifact download <artifact-id> -o ./dist/
+```
+
+## Workflow: 仓库文件修改
+
+```bash
+# 读取
+gitea-cli content get src/config.yaml --output json
+
+# 创建新文件
+gitea-cli content create src/config.yaml --content "new: value" -m "add config"
+
+# 更新（SHA 自动获取）
+gitea-cli content update src/config.yaml --content "updated: value" -m "update config"
+
+# 从本地文件上传
+gitea-cli content update src/config.yaml --file ./local-config.yaml -m "update from local"
+```
+
+## Workflow: 配置管理
+
+```bash
+gitea-cli config list --output json
+gitea-cli config set --name work --host <url> --token <tok> --default-owner myorg
+gitea-cli config get work
+# 临时使用其他 context
+gitea-cli issue list --context personal --output json
+```
+
+## Command Reference
+
+### Config
+
+```bash
+gitea-cli config list                                        # List all contexts
+gitea-cli config get <name>                                  # Get context details
+gitea-cli config set --name <ctx> --host <url> --token <tok> # Create/update context
+# Additional flags: --default-owner, --default-repo
+```
+
+### Repository
+
+```bash
+gitea-cli repo list --owner <org> --output json
+gitea-cli repo get --owner <org> --repo <repo> --output json
+```
+
+### Branch
+
+```bash
+gitea-cli branch list --output json
+gitea-cli branch get <name> --output json
+gitea-cli branch create <name> --from <base>
+gitea-cli branch delete <name> --force
+gitea-cli branch protect list --output json
+gitea-cli branch protect create <name> --enable-push --required-approvals 2
+gitea-cli branch protect delete <name> --force
+```
+
+### File Content
+
+```bash
+gitea-cli content list [--path] --ref <branch> --output json
+gitea-cli content get <path> --ref <branch> --output json       # --raw for decoded content
+gitea-cli content create <path> --content "text" -m "msg"       # or --file <local>
+gitea-cli content update <path> --content "text" -m "msg"       # --sha auto-fetched
+gitea-cli content delete <path> -m "msg" --force
+```
+
+### Commit
+
+```bash
+gitea-cli commit list --branch <ref> --limit 10 --output json
+gitea-cli commit get <sha> --output json
+```
+
+### Issue
+
+```bash
+gitea-cli issue list --state open --output json
+gitea-cli issue get <number> --output json
+gitea-cli issue create -t "Title" -b "Body" --label <id> --milestone <id>
+gitea-cli issue create -t "Title" --attach ./image.png --attach ./log.txt
+gitea-cli issue update <number> -t "New Title" --state closed
+gitea-cli issue close <number>
+
+# Comments
+gitea-cli issue comment list <number> --output json
+gitea-cli issue comment create <number> -b "Comment text"
+gitea-cli issue comment update <comment-id> -b "Updated text"
+gitea-cli issue comment delete <comment-id> --force
+
+# Attachments
+gitea-cli issue attachment list <number> --output json
+gitea-cli issue attachment upload <number> <file> --name <filename>
+gitea-cli issue attachment download <number> <attach-id> -o ./save/
+gitea-cli issue attachment delete <number> <attach-id> --force
+```
+
+### Pull Request
+
+```bash
+gitea-cli pr list --state open --output json
+gitea-cli pr get <index> --output json
+gitea-cli pr create --title "Title" --head <src> --base <target> --body "Desc"
+gitea-cli pr close <index>
+gitea-cli pr reopen <index>
+gitea-cli pr merge <index> --strategy merge --delete-branch
+# Strategies: merge, rebase, squash, fast-forward-only
+```
+
+### Label
+
+```bash
+gitea-cli label list --output json
+gitea-cli label get <id> --output json
+gitea-cli label create --name "bug" --color "#ff0000" --description "Bug report"
+gitea-cli label delete <id> --force
+```
+
+### Milestone
+
+```bash
+gitea-cli milestone list --state open --output json
+gitea-cli milestone get <id> --output json
+gitea-cli milestone create --title "v1.0" --description "First release" --due-on 2025-12-31T00:00:00Z
+gitea-cli milestone close <id>
+gitea-cli milestone delete <id> --force
+```
+
+### Tag
+
+```bash
+gitea-cli tag list --output json
+gitea-cli tag get <name> --output json
+gitea-cli tag create <name> --target <ref> -m "Annotated tag message"
+gitea-cli tag delete <name> --force
+```
+
+### Actions (CI/CD)
+
+```bash
+# Workflows
+gitea-cli actions workflow list --output json
+gitea-cli actions workflow get <id-or-filename> --output json
+gitea-cli actions workflow enable <id-or-filename>
+gitea-cli actions workflow disable <id-or-filename>
+gitea-cli actions workflow dispatch <id-or-filename> --ref main --input key=value
+
+# Runs
+gitea-cli actions run list --status completed --output json
+gitea-cli actions run get <run-id> --output json
+gitea-cli actions run jobs <run-id> --output json
+gitea-cli actions run artifacts <run-id> --output json
+gitea-cli actions run delete <run-id> --force
+
+# Jobs
+gitea-cli actions job get <job-id> --output json
+gitea-cli actions job logs <job-id> -o ./logs/
+
+# Artifacts
+gitea-cli actions artifact list --output json
+gitea-cli actions artifact download <id> -o ./dist/
+gitea-cli actions artifact delete <id> --force
+```
+
+### Webhook
+
+```bash
+gitea-cli webhook list --output json
+gitea-cli webhook get <id> --output json
+gitea-cli webhook create --url <endpoint> --secret <secret> --event push --event issues --active
+gitea-cli webhook update <id> --url <new-url> --active false
+gitea-cli webhook delete <id> --force
+gitea-cli webhook test <id>
+```
+
+### Release
+
+```bash
+gitea-cli release list --output json
+gitea-cli release get <tag> --output json
+gitea-cli release create --tag <tag> --name "Title" --body "Notes" --target <ref> --draft --prerelease
+gitea-cli release create --tag <tag> --body-file changelog.md            # avoids encoding issues
+gitea-cli release delete <tag> --force
+
+# Assets
+gitea-cli release asset list <tag> --output json
+gitea-cli release asset upload <tag> <file> --name <asset-name>
+gitea-cli release asset download <tag> <asset-id> -o ./downloads/
+gitea-cli release asset delete <tag> <asset-id> --force
+```

package/assets/SKILL.md

@@ -5,404 +5,86 @@ description: Use when needing to interact with Gitea repositories, branches, iss
 
 # gitea-cli
 
-## Binary Location
-
-Binaries for all platforms are bundled under the `scripts/` directory relative to this skill:
+Stateless CLI for Gitea HTTP API. Every call is an independent request, safe for concurrent use.
 
-| Platform | Relative Path |
-|----------|------|
-| Linux amd64 | `scripts/linux-amd64/gitea-cli` |
-| Linux arm64 | `scripts/linux-arm64/gitea-cli` |
-| macOS amd64 | `scripts/darwin-amd64/gitea-cli` |
-| macOS arm64 | `scripts/darwin-arm64/gitea-cli` |
-| Windows amd64 | `scripts/windows-amd64/gitea-cli.exe` |
-| Windows arm64 | `scripts/windows-arm64/gitea-cli.exe` |
+## Binary Location
 
-**Skill directory is `~/.claude/skills/gitea-cli/`.** Before executing commands, resolve `gitea-cli` to the platform-appropriate binary. Auto-detect with:
+Resolve `gitea-cli` to the platform binary in skill directory `~/.claude/skills/gitea-cli/`:
 
 ```bash
-SKILL_DIR="$HOME/.claude/skills/gitea-cli"
-
 # Linux / macOS
+SKILL_DIR="$HOME/.claude/skills/gitea-cli"
 OS="$(uname -s | tr '[:upper:]' '[:lower:]')"
-ARCH="$(uname -m)"
-[[ "$ARCH" == "x86_64" ]] && ARCH="amd64"
-[[ "$ARCH" == "aarch64" || "$ARCH" == "arm64" ]] && ARCH="arm64"
+ARCH="$(uname -m)" && [[ "$ARCH" == "x86_64" ]] && ARCH="amd64" && [[ "$ARCH" == "aarch64" || "$ARCH" == "arm64" ]] && ARCH="arm64"
 GITEA_CLI="$SKILL_DIR/scripts/${OS}-${ARCH}/gitea-cli"
-
-# Windows (PowerShell)
-# $GITEA_CLI = "$env:USERPROFILE\.claude\skills\gitea-cli\scripts\windows-amd64\gitea-cli.exe"
+# Windows: %USERPROFILE%\.claude\skills\gitea-cli\scripts\windows-amd64\gitea-cli.exe
 ```
 
-If the tool is also available in PATH (e.g. installed globally), `gitea-cli` can be used directly.
-
-## Overview
-
-`gitea-cli` is a stateless CLI tool that manages Gitea repositories through the HTTP API. Each call is an independent API request, making it safe for concurrent use. It supports both human-friendly table output and machine-friendly JSON output (`--output json`).
+If available in PATH, `gitea-cli` can be used directly.
 
 ## Agent Rules
 
-### 1. Always use JSON output
-
-```bash
-gitea-cli <command> --output json --owner <owner> --repo <repo>
-```
-
-### 2. Never switch context autonomously
-
-Use `--owner`/`--repo` flags to target different repos. Do NOT call `config use` without user supervision.
-
-### 3. Destructive operations require confirmation
-
-Always run a list/get command first to verify the target exists before deleting.
-
-### 4. Branch/ref auto-detection
-
-When inside a git repo, `--branch` and `--ref` default to the current branch. `--owner`/`--repo` auto-detect from git remote.
+1. **Always `--output json`** — All calls must include this flag
+2. **Never switch context** — Use `--owner`/`--repo` flags; do NOT call `config use` autonomously
+3. **Verify before delete** — Run `list`/`get` first, then `--force` for non-interactive
+4. **Auto-detection** — In a git repo, `--branch`/`--ref`/`--owner`/`--repo` auto-detect from `.git`
 
 ## Global Flags
 
 | Flag | Short | Description |
 |------|-------|-------------|
-| `--output` | `-o` | `json` or `table` (agents: always use `json`) |
-| `--owner` | | Repository owner |
-| `--repo` | `-r` | Repository name |
+| `--output` | `-o` | `json` (agents: always) or `table` |
+| `--owner` | | Repository owner (auto-detect from git) |
+| `--repo` | `-r` | Repository name (auto-detect from git) |
 | `--context` | `-c` | Context name (override, no save) |
-| `--config` | | Config file path |
 | `--host` | | Gitea host URL |
 | `--token` | | API token |
 
-**Env vars:** `GITEA_HOST`, `GITEA_TOKEN`, `GITEA_OWNER`, `GITEA_REPO`, `GITEA_OUTPUT`
-
-## Common Workflows
-
-### Workflow 1: Issue 处理
-
-处理用户反馈或 bug 报告的标准流程。
-
-```bash
-# 1. 查看当前 open 的 issues
-gitea-cli issue list --state open --output json
-
-# 2. 查看具体 issue 详情
-gitea-cli issue get <number> --output json
-
-# 3. 如果需要 label/milestone，先查找 ID
-gitea-cli label list --output json
-gitea-cli milestone list --output json
-
-# 4. 更新 issue（添加 label、milestone 等）
-gitea-cli issue update <number> --label <id> --milestone <id>
-
-# 5. 处理过程中添加评论记录进展
-gitea-cli issue comment create <number> -b "分析原因：..."
-
-# 6. 如果需要上传截图或日志
-gitea-cli issue attachment upload <number> ./screenshot.png
-
-# 7. 处理完成后关闭 issue
-gitea-cli issue close <number>
-```
-
-### Workflow 2: PR 工作流
-
-从创建分支到合并 PR 的完整流程。
-
-```bash
-# 1. 创建 feature 分支
-gitea-cli branch create feature/xyz --from main
-
-# 2. （本地开发完成后）查看当前分支列表确认
-gitea-cli branch list --output json
-
-# 3. 创建 PR
-gitea-cli pr create --title "feat: add new feature" --head feature/xyz --base main --body "## Summary\n- Changes made\n\n## Test plan\n- [ ] Unit tests pass"
-
-# 4. 查看 PR 状态
-gitea-cli pr get <index> --output json
-
-# 5. 检查 CI 状态（如果有 Actions 配置）
-gitea-cli actions run list --output json
-gitea-cli actions run jobs <run-id> --output json
-
-# 6. CI 通过后合并 PR
-gitea-cli pr merge <index> --strategy squash --delete-branch
-```
-
-### Workflow 3: Release 发布
-
-创建版本发布的完整流程。
-
-```bash
-# 1. 查看最近的提交，确定版本范围
-gitea-cli commit list --branch main --limit 20 --output json
-
-# 2. 查看现有 tags 和 releases
-gitea-cli tag list --output json
-gitea-cli release list --output json
-
-# 3. 创建 tag
-gitea-cli tag create v1.0.0 --target main -m "Release v1.0.0"
-
-# 4. 创建 release
-gitea-cli release create --tag v1.0.0 --name "v1.0.0" --body "## New Features\n- Feature A\n\n## Bug Fixes\n- Fix B" --target main
-
-# 5. 上传构建产物
-gitea-cli release asset upload v1.0.0 ./dist/binary-linux-amd64 --name binary-linux-amd64
-gitea-cli release asset upload v1.0.0 ./dist/binary-darwin-arm64 --name binary-darwin-arm64
-
-# 6. 确认 release 内容
-gitea-cli release get v1.0.0 --output json
-gitea-cli release asset list v1.0.0 --output json
-```
-
-### Workflow 4: CI/CD 监控与排障
-
-监控 pipeline 状态和排查失败的任务。
-
-```bash
-# 1. 查看最近的 runs
-gitea-cli actions run list --limit 10 --output json
-
-# 2. 查看失败 run 的 jobs
-gitea-cli actions run jobs <run-id> --output json
-
-# 3. 获取失败 job 的日志
-gitea-cli actions job logs <job-id> -o ./logs/
-
-# 4. 查看 job 详情（含步骤状态）
-gitea-cli actions job get <job-id> --output json
-
-# 5. 重新触发 workflow
-gitea-cli actions workflow dispatch <workflow-id> --ref main
-
-# 6. 查看构建产物
-gitea-cli actions artifact list --output json
-gitea-cli actions artifact download <artifact-id> -o ./dist/
-```
-
-### Workflow 5: 仓库文件修改
-
-通过 API 读取、修改、写回仓库文件。
-
-```bash
-# 1. 读取文件内容（获取当前版本）
-gitea-cli content get src/config.yaml --output json
-
-# 2. 在 feature 分支上创建新版本（--branch 省略时用当前分支）
-gitea-cli content create src/config.yaml --content "new: value" -m "add config"
+Env vars: `GITEA_HOST`, `GITEA_TOKEN`, `GITEA_OWNER`, `GITEA_REPO`
 
-# 3. 更新已有文件（SHA 自动获取）
-gitea-cli content update src/config.yaml --content "updated: value" -m "update config"
+## Command Summary
 
-# 4. 或从本地文件上传
-gitea-cli content update src/config.yaml --file ./local-config.yaml -m "update config from local"
-
-# 5. 确认修改
-gitea-cli content get src/config.yaml --output json
-```
-
-### Workflow 6: 配置与多环境管理
-
-管理多个 Gitea 实例的 context 配置。
-
-```bash
-# 1. 查看当前配置
-gitea-cli config list --output json
-
-# 2. 添加新的 context
-gitea-cli config set --name work --host https://git.company.com --token <token> --default-owner myorg
-
-# 3. 临时使用另一个 context（不保存）
-gitea-cli issue list --context personal --output json
-
-# 4. 查看特定 context 详情
-gitea-cli config get work
-```
-
-## Command Quick Reference
-
-### Config
-
-```bash
-gitea-cli config list                                        # List all contexts
-gitea-cli config get <name>                                  # Get context details
-gitea-cli config set --name <ctx> --host <url> --token <tok> # Create/update context
-```
-
-### Repository
-
-```bash
-gitea-cli repo list --owner <org> --output json
-gitea-cli repo get --owner <org> --repo <repo> --output json
-```
-
-### Branch
-
-```bash
-gitea-cli branch list --output json
-gitea-cli branch get <name> --output json
-gitea-cli branch create <name> --from <base>
-gitea-cli branch delete <name> --force
-gitea-cli branch protect list --output json
-gitea-cli branch protect create <name> --enable-push --required-approvals 2
-gitea-cli branch protect delete <name> --force
-```
-
-### File Content
-
-```bash
-gitea-cli content list [--path] --ref <branch> --output json
-gitea-cli content get <path> --ref <branch> --output json       # --raw for decoded content in json
-gitea-cli content create <path> --content "text" -m "msg"       # or --file <local>
-gitea-cli content update <path> --content "text" -m "msg"       # --sha auto-fetched
-gitea-cli content delete <path> -m "msg" --force
-```
-
-### Commit
-
-```bash
-gitea-cli commit list --branch <ref> --limit 10 --output json
-gitea-cli commit get <sha> --output json
-```
-
-### Issue
-
-```bash
-gitea-cli issue list --state open --output json
-gitea-cli issue get <number> --output json
-gitea-cli issue create -t "Title" -b "Body" --label <id> --milestone <id>
-gitea-cli issue create -t "Title" --attach ./image.png --attach ./log.txt   # embed attachments in body
-gitea-cli issue update <number> -t "New Title" --state closed
-gitea-cli issue close <number>
-
-# Comments
-gitea-cli issue comment list <number> --output json
-gitea-cli issue comment create <number> -b "Comment text"
-gitea-cli issue comment update <comment-id> -b "Updated text"
-gitea-cli issue comment delete <comment-id> --force
-
-# Attachments
-gitea-cli issue attachment list <number> --output json
-gitea-cli issue attachment upload <number> <file> --name <filename>
-gitea-cli issue attachment download <number> <attach-id> -o ./save/
-gitea-cli issue attachment delete <number> <attach-id> --force
 ```
-
-### Pull Request
-
-```bash
-gitea-cli pr list --state open --output json
-gitea-cli pr get <index> --output json
-gitea-cli pr create --title "Title" --head <src> --base <target> --body "Desc"
-gitea-cli pr close <index>
-gitea-cli pr reopen <index>
-gitea-cli pr merge <index> --strategy merge --delete-branch
+config set/list/get/use          — Context configuration
+issue list/get/create/update/close — Issues + comments + attachments
+pr list/get/create/close/reopen/merge — Pull requests
+branch list/get/create/delete     — Branches + protection rules
+content list/get/create/update/delete — Repo file CRUD
+commit list/get                   — Commit history
+label list/get/create/delete      — Labels
+milestone list/get/create/close/delete — Milestones
+tag list/get/create/delete        — Tags
+release list/get/create/delete    — Releases + assets
+actions workflow/run/job/artifact — CI/CD management
+webhook list/get/create/update/delete/test — Webhooks
 ```
 
-### Label
-
-```bash
-gitea-cli label list --output json
-gitea-cli label get <id> --output json
-gitea-cli label create --name "bug" --color "#ff0000" --description "Bug report"
-gitea-cli label delete <id> --force
-```
-
-### Milestone
-
-```bash
-gitea-cli milestone list --state open --output json
-gitea-cli milestone get <id> --output json
-gitea-cli milestone create --title "v1.0" --description "First release" --due-on 2025-12-31T00:00:00Z
-gitea-cli milestone close <id>
-gitea-cli milestone delete <id> --force
-```
-
-### Tag
+## Common Workflows
 
-```bash
-gitea-cli tag list --output json
-gitea-cli tag get <name> --output json
-gitea-cli tag create <name> --target <ref> -m "Annotated tag message"
-gitea-cli tag delete <name> --force
-```
+When performing a task, follow the matching workflow. Read `REFERENCE.md` in the same skill directory for full command details and flags.
 
-### Actions (CI/CD)
+**Issue** — `issue list` → `issue get <n>` → `comment create <n>` → `issue close <n>`
+**PR** — `branch create <name> --from <base>` → `pr create` → `actions run list` → `pr merge <idx>`
+**Release** — `tag create <v>` → `release create --tag <v>` → `release asset upload <v> <file>`
+**CI/CD** — `actions run list` → `actions run jobs <run>` → `actions job logs <job>`
+**File edit** — `content get <path>` → `content update <path> --content "..." -m "msg"`
+**Config** — `config set --name <ctx> --host <url> --token <tok>`
 
-```bash
-# Workflows
-gitea-cli actions workflow list --output json
-gitea-cli actions workflow get <id-or-filename> --output json
-gitea-cli actions workflow enable <id-or-filename>
-gitea-cli actions workflow disable <id-or-filename>
-gitea-cli actions workflow dispatch <id-or-filename> --ref main --input key=value
+## Error Handling
 
-# Runs
-gitea-cli actions run list --status completed --output json
-gitea-cli actions run get <run-id> --output json
-gitea-cli actions run jobs <run-id> --output json
-gitea-cli actions run artifacts <run-id> --output json
-gitea-cli actions run delete <run-id> --force
+| Error | Fix |
+|-------|-----|
+| `host is required` | Run `config set` |
+| `API 404` | Verify owner/repo/index |
+| `API 409` | Already exists, skip |
+| `API 401` | Check token |
 
-# Jobs
-gitea-cli actions job get <job-id> --output json
-gitea-cli actions job logs <job-id> -o ./logs/
+Destructive ops: always `list`/`get` first, then `--force`. Deleted resources cannot be recovered.
 
-# Artifacts
-gitea-cli actions artifact list --output json
-gitea-cli actions artifact download <id> -o ./dist/
-gitea-cli actions artifact delete <id> --force
-```
+## On-Demand Reference
 
-### Webhook
+For full command flags and detailed workflow steps, read the reference file:
 
-```bash
-gitea-cli webhook list --output json
-gitea-cli webhook get <id> --output json
-gitea-cli webhook create --url <endpoint> --secret <secret> --event push --event issues --active
-gitea-cli webhook update <id> --url <new-url> --active false
-gitea-cli webhook delete <id> --force
-gitea-cli webhook test <id>
 ```
-
-### Release
-
-```bash
-gitea-cli release list --output json
-gitea-cli release get <tag> --output json
-gitea-cli release create --tag <tag> --name "Title" --body "Notes" --target <ref> --draft --prerelease
-gitea-cli release create --tag <tag> --body-file changelog.md            # use file for release notes (avoids encoding issues)
-gitea-cli release delete <tag> --force
-
-# Assets
-gitea-cli release asset list <tag> --output json
-gitea-cli release asset upload <tag> <file> --name <asset-name>
-gitea-cli release asset download <tag> <asset-id> -o ./downloads/
-gitea-cli release asset delete <tag> <asset-id> --force
+~/.claude/skills/gitea-cli/REFERENCE.md
 ```
-
-## Error Handling
-
-| Exit Code | Meaning |
-|-----------|---------|
-| `0` | Success |
-| `1` | Error (see stderr) |
-
-JSON errors on stderr: `{"error": "API 404: repository not found"}`
-
-| Error | Cause | Fix |
-|-------|-------|-----|
-| `host is required` | No context configured | Run `config set` |
-| `API 404` | Resource not found | Verify owner/repo/index |
-| `API 409` | Resource already exists | Skip duplicate creation |
-| `API 401` | Invalid/expired token | Check context token |
-
-## Destructive Operations Checklist
-
-Before running any delete, always verify:
-
-1. Run the corresponding `list` or `get` command first
-2. Confirm the resource ID/name matches the intended target
-3. Use `--force` flag to skip interactive prompts (required for agent use)
-4. Consider irreversibility — deleted resources cannot be recovered

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitea-cli-skill",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "description": "Install gitea-cli as a Claude Code skill",
   "bin": {
     "gitea-cli-skill": "src/index.js"

package/src/index.js

@@ -170,13 +170,20 @@ async function install(args) {
 
   console.log(`Installing gitea-cli skill (${osArch.os}-${osArch.arch}) to ${skillDir}...`);
 
-  // 1. Copy SKILL.md
+  // 1. Copy SKILL.md and REFERENCE.md
   fs.mkdirSync(skillDir, { recursive: true });
   const srcSkill = path.resolve(__dirname, '..', 'assets', 'SKILL.md');
   const destSkill = path.join(skillDir, 'SKILL.md');
   fs.copyFileSync(srcSkill, destSkill);
   console.log(`  SKILL.md -> ${destSkill}`);
 
+  const srcRef = path.resolve(__dirname, '..', 'assets', 'REFERENCE.md');
+  const destRef = path.join(skillDir, 'REFERENCE.md');
+  if (fs.existsSync(srcRef)) {
+    fs.copyFileSync(srcRef, destRef);
+    console.log(`  REFERENCE.md -> ${destRef}`);
+  }
+
   // 2. Check existing binary
   const binaryName = osArch.os === 'windows' ? 'gitea-cli.exe' : 'gitea-cli';
   const destBinary = path.join(scriptsDir, binaryName);