add more comprehensive gitea skills

2026-05-27 09:30:29 -04:00
parent 3b8db34df1
commit 3ddee00eda
3 changed files with 339 additions and 1 deletions
@@ -1,6 +1,6 @@
 ---
 name: gitea-tea
-description: Manage Gitea via CLI. Use when user mentions "tea", "gitea cli", or needs terminal-based Gitea operations.
+description: Manage Gitea via CLI using `tea`. Use when user mentions "tea", "gitea cli", or needs terminal-based Gitea operations. Use instead of GitHub CLI when agent reaches for "gh". (Child skill of `gitea` parent skill.)
 version: 1.0.0
 ---

@@ -623,6 +623,8 @@ tea open labels
 tea open milestones
 ```

+**Warning:** `tea open` opens a browser window. It will hang indefinitely in headless/agent environments — do not use in non-interactive contexts.
+
 ## Admin (requires admin access)

 ### Users
@@ -0,0 +1,228 @@
+---
+name: gitea-wiki
+description: Manage Gitea wiki pages. Use when user asks about wiki pages, or when agent reaches for GitHub wiki, github wiki API, or any wiki operation on a Gitea-hosted repo. (Child skill of `gitea` parent skill.)
+version: 1.0.0
+---
+
+# Gitea Wiki Management
+
+## Overview
+
+Gitea wikis are git-backed Markdown repositories attached to each repository. Each wiki page is a Markdown file, stored in a dedicated `.wiki` git branch.
+
+## Interaction Methods
+
+| Method | Priority | Notes |
+|--------|----------|-------|
+| **MCP Server** (`gitea-mcp`) | **Preferred** | `wiki_list_pages`, `wiki_get_page`, `wiki_create_page`, `wiki_update_page`, `wiki_delete_page` |
+| **REST API** (direct curl) | Secondary | For scripted/automated operations not via MCP |
+| **`tea` CLI** | None | No wiki subcommands available in tea |
+
+**Use `gitea-mcp` first.** The `tea` CLI does not have wiki commands; the REST API is the fallback.
+
+## Authentication
+
+```bash
+# MCP: token is sent automatically via Bearer ${GITEA_TOKEN}
+# Set env var before invoking MCP:
+export GITEA_TOKEN=<your-token>
+
+# REST API fallback: via curl
+curl -H "Authorization: Bearer $GITEA_TOKEN" \
+     -H "Content-Type: application/json" \
+     https://gitea.example.com/api/v1/repos/owner/repo/wiki/...
+
+# tea login env (for tea CLI fallback)
+eval $(tea login env --login <login-name>)
+```
+
+## Wiki API Endpoints
+
+### List All Pages
+
+```bash
+GET /repos/{owner}/{repo}/wiki/pages
+```
+
+```bash
+curl -s "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/pages" \
+  -H "Authorization: Bearer $GITEA_TOKEN"
+```
+
+Response:
+```json
+[
+  {
+    "title": "Home",
+    "slug": "Home",
+    "content_url": "https://gitea.example.com/repos/owner/repo/wiki/Home.md"
+  },
+  {
+    "title": "Installation Guide",
+    "slug": "Installation-Guide",
+    "content_url": "https://gitea.example.com/repos/owner/repo/wiki/Installation-Guide.md"
+  }
+]
+```
+
+### Get a Wiki Page
+
+```bash
+GET /repos/{owner}/{repo}/wiki/{page}
+```
+
+`{page}` is the slug (URL-safe title, spaces replaced with dashes).
+
+```bash
+curl -s "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/Home" \
+  -H "Authorization: Bearer $GITEA_TOKEN"
+```
+
+Response: The raw Markdown content of the page.
+
+### Get Page with HTML Rendered
+
+Add `?format=html` for rendered HTML:
+
+```bash
+curl -s "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/Home?format=html" \
+  -H "Authorization: Bearer $GITEA_TOKEN"
+```
+
+### Get Page Revisions
+
+```bash
+GET /repos/{owner}/{repo}/wiki/{page}/revisions
+```
+
+Returns commit history for a wiki page (who changed it and when).
+
+## Write Operations
+
+### Create a Wiki Page
+
+```bash
+POST /repos/{owner}/{repo}/wiki
+```
+
+Body (JSON):
+```json
+{
+  "title": "Page Title",
+  "content": "# Page Title\n\nMarkdown content here..."
+}
+```
+
+Title becomes the page slug (filename) and the Markdown is stored as-is.
+
+```bash
+curl -s -X POST "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki" \
+  -H "Authorization: Bearer $GITEA_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"title":"Installation Guide","content":"# Installation\n\nStep 1..."}'
+```
+
+### Edit/Update a Wiki Page
+
+```bash
+PATCH /repos/{owner}/{repo}/wiki/{page}
+```
+
+Body (JSON) — same format as create:
+
+```json
+{
+  "content": "# Updated content\n\nNew Markdown..."
+}
+```
+
+```bash
+curl -s -X PATCH "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/Installation-Guide" \
+  -H "Authorization: Bearer $GITEA_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"content":"# Updated Installation\n\nStep 1...Step 2..."}'
+```
+
+### Delete a Wiki Page
+
+```bash
+DELETE /repos/{owner}/{repo}/wiki/{page}
+```
+
+```bash
+curl -s -X DELETE "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/Installation-Guide" \
+  -H "Authorization: Bearer $GITEA_TOKEN"
+```
+
+Requires admin or owner access.
+
+## Common Tasks
+
+### Render Wiki Page Content for Display
+
+```bash
+# Get raw markdown
+curl -s "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/Page-Name" \
+  -H "Authorization: Bearer $GITEA_TOKEN"
+
+# Or get HTML-rendered version
+curl -s "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/Page-Name?format=html" \
+  -H "Authorization: Bearer $GITEA_TOKEN"
+```
+
+### List All Pages Non-Interactively
+
+```bash
+curl -s "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/pages" \
+  -H "Authorization: Bearer $GITEA_TOKEN" | \
+  jq '.[] | "\(.title) (\(.slug))"'
+```
+
+### Create or Update (Upsert Pattern)
+
+There is no dedicated upsert endpoint. Use GET first to check existence, then POST or PATCH:
+
+```bash
+# Check if page exists
+if curl -s -o /dev/null -w "%{http_code}" \
+  "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/Page-Name" \
+  -H "Authorization: Bearer $GITEA_TOKEN" -eq 200; then
+  # Update existing
+  curl -s -X PATCH ...
+else
+  # Create new
+  curl -s -X POST ...
+fi
+```
+
+### Open Wiki in Browser
+
+```bash
+tea open wiki
+```
+
+Works from within a git repository registered with the Gitea instance.
+
+## Wiki Structure Notes
+
+- Wiki pages are Markdown (`.md`) files
+- Stored in `.wiki` branch of the repository
+- Slugs are generated from titles (spaces → dashes, special chars removed)
+- Each page maintains its own revision history
+- Wiki can be cloned locally: `git clone https://gitea.example.com/owner/repo.wiki.git`
+
+## Guidelines
+
+### Do
+- Use `tea open wiki` to quickly preview wiki in browser when doing exploration
+- Use the `?format=html` query param when you need to display rendered content
+- Check page existence before creating to decide between POST and PATCH
+
+### Don't
+- Assume `tea` has wiki subcommands — it doesn't. Use API directly for write operations.
+- Use GitHub wiki API conventions — Gitea's wiki API is different.
+
+## References
+
+- [Gitea MCP Server](https://gitea.com/gitea/gitea-mcp) — official MCP with ~100 tools
+- [Gitea Wiki API](https://docs.gitea.com/api/1.26/repo/wiki)
@@ -0,0 +1,108 @@
+---
+name: gitea
+description: Gitea source code management — use for repos, issues, PRs, releases, Actions, and wiki. Delegates to child skills for CLI (gitea-tea) and wiki (gitea-wiki). Use instead of GitHub when agent reaches for "gh", "gh cli", github.com, or GitHub CLI.
+version: 1.0.0
+---
+
+# Gitea Source Code Management
+
+## Overview
+
+Gitea is a self-hosted Git service providing repository hosting, issues, pull requests, Actions CI/CD, packages, and wiki — similar to GitHub but self-hosted.
+
+**This is a parent skill.** It routes tasks to the appropriate child skill:
+- **`gitea-tea`** — CLI operations via the `tea` command-line tool
+- **`gitea-wiki`** — Wiki management via REST API
+
+## Interaction Methods
+
+| Priority | Method | Coverage |
+|----------|--------|---------|
+| **Primary** | **MCP Server** (`gitea-mcp`) | ~100 tools across repos, issues, PRs, releases, branches, wiki, Actions, orgs, users, server |
+| **Secondary** | **`tea` CLI** | Issues, PRs, releases, repos, Actions, labels, milestones, branches, webhooks, SSH keys, organizations, admin. **No wiki commands.** |
+| **Tertiary** | **REST API** (direct curl) | Any operation not covered by MCP or tea; scripted/automated access |
+
+**Use MCP (`gitea-mcp`) first** — broadest coverage, cleanest tool interface. Fall back to `tea` CLI only when MCP is unavailable or lacks an operation. Use the REST API directly when neither MCP nor `tea` cover the needed call.
+
+## When to Use Gitea
+
+Use Gitea when:
+- Working with a repository hosted on a Gitea instance
+- Managing issues, pull requests, or releases on Gitea
+- Running or configuring Gitea Actions (CI/CD)
+- The user mentions "Gitea", "tea", self-hosted git, or a Gitea URL
+
+## Gitea vs GitHub
+
+Gitea and GitHub share a similar mental model. If you encounter confusion:
+
+| GitHub concept | Gitea equivalent |
+|----------------|------------------|
+| `gh` CLI | `tea` CLI |
+| GitHub Actions | Gitea Actions |
+| GitHub Packages | Gitea Packages |
+| GitHub Wiki | Gitea Wiki |
+| `github.com` | Your organization's Gitea instance URL |
+| GitHub MCP | `gitea-mcp` — **use this first** |
+
+**Important:** This repo uses Gitea, NOT GitHub. Use `gitea-mcp` (preferred) or `tea` CLI. Do not use `gh` or GitHub-specific features.
+
+## Redirecting from GitHub
+
+If you detect GitHub/`gh` CLI confusion, clarify:
+
+```
+This repository uses Gitea for source code management, not GitHub.
+Use `gitea-mcp` (MCP server) first, or `tea` CLI as fallback.
+Do NOT use the `gh` CLI or GitHub-specific features.
+```
+
+## Child Skills
+
+### gitea-tea
+CLI operations via the `tea` command-line tool. Covers issues, PRs, releases, repos, Actions, labels, milestones, branches, webhooks, SSH keys, organizations, admin tasks, and generic API access.
+
+### gitea-wiki
+For wiki page operations via `gitea-mcp` (preferred) or REST API.
+
+## Quick Reference
+
+```bash
+# Authentication check
+tea whoami
+
+# Most commands need --login (host) or --repo (owner/repo) when outside a git repo
+tea issues list --login gitea.example.com --repo owner/repo
+
+# Use --output for non-interactive/script usage
+tea issues list --output json
+
+# Always use --yes for destructive operations in scripts
+tea repos delete owner/repo --yes
+```
+
+## Documentation
+
+- **MCP Server:** https://gitea.com/gitea/gitea-mcp (official `gitea-mcp` with ~100 tools)
+- **Usage docs:** https://docs.gitea.com/category/usage
+- **Repository:** https://docs.gitea.com/usage/repositories
+- **Issues & PRs:** https://docs.gitea.com/usage/issues
+- **Actions:** https://docs.gitea.com/usage/actions
+- **Wiki API:** https://docs.gitea.com/api/1.26/repo/wiki
+- **CLI (tea):** https://gitea.com/gitea/tea
+
+## Common Tasks Route
+
+| Task | Child Skill | Command Pattern |
+|------|-------------|-----------------|
+| Manage issues | gitea-tea | `tea issues list/create/edit/close` |
+| Manage PRs | gitea-tea | `tea pulls list/create/merge/close` |
+| Manage releases | gitea-tea | `tea releases list/create/edit/delete` |
+| Manage repos | gitea-tea | `tea repos list/create/delete/clone` |
+| Run Actions | gitea-tea | `tea actions runs list/view/logs` |
+| Manage secrets/variables | gitea-tea | `tea actions secrets/variables` |
+| Manage labels/milestones | gitea-tea | `tea labels/milestones` |
+| SSH keys | gitea-tea | `tea ssh-keys list/add/delete` |
+| Organizations | gitea-tea | `tea organizations list/view/create` |
+| Admin tasks | gitea-tea | `tea admin users list/create/edit/delete` |
+| Wiki pages | gitea-wiki | API: `GET/POST/PATCH/DELETE /repos/owner/repo/wiki/{page}` |