From 3ddee00edab33e8dc57c6841fe91267006453e00 Mon Sep 17 00:00:00 2001 From: Chris Farhood Date: Wed, 27 May 2026 09:30:29 -0400 Subject: [PATCH] add more comprehensive gitea skills --- gitea-tea/SKILL.md | 4 +- gitea-wiki/SKILL.md | 228 ++++++++++++++++++++++++++++++++++++++++++++ gitea/SKILL.md | 108 +++++++++++++++++++++ 3 files changed, 339 insertions(+), 1 deletion(-) create mode 100644 gitea-wiki/SKILL.md create mode 100644 gitea/SKILL.md diff --git a/gitea-tea/SKILL.md b/gitea-tea/SKILL.md index 981ae83..cd8354a 100644 --- a/gitea-tea/SKILL.md +++ b/gitea-tea/SKILL.md @@ -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 diff --git a/gitea-wiki/SKILL.md b/gitea-wiki/SKILL.md new file mode 100644 index 0000000..0aaae03 --- /dev/null +++ b/gitea-wiki/SKILL.md @@ -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= + +# 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 ) +``` + +## 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) diff --git a/gitea/SKILL.md b/gitea/SKILL.md new file mode 100644 index 0000000..2993542 --- /dev/null +++ b/gitea/SKILL.md @@ -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}` |