gb_flea/skills
1
0
Fork 0
forked from farhoodlabs/skills
Code Pull Requests Activity

update/enhance gitea skills

Browse Source
This commit is contained in:
Chris Farhood
2026-05-27 09:59:50 -04:00
parent 3ddee00eda
commit 5be276b945
6 changed files with 963 additions and 1007 deletions
Download Patch File Download Diff File Expand all files Collapse all files
gitea-wiki/SKILL.md
+119 -164
View File
@@ -1,228 +1,183 @@
---
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
version: 1.1.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.
Gitea wikis are git-backed Markdown pages attached to a repository. The MCP server exposes them through two consolidated tools (`wiki_read`, `wiki_write`); the REST API at `/api/v1/repos/{owner}/{repo}/wiki/...` is the fallback. `tea` has no wiki subcommands.
## 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 |
| Priority | Method | Notes |
|----------|--------|-------|
| **Primary** | MCP `mcp__gitea__wiki_read` / `mcp__gitea__wiki_write` | Configured in repo `.mcp.json`; auth via `GITEA_TOKEN` |
| Fallback | REST API via `curl` | For automation outside an MCP-aware client |
| — | `tea` CLI | Not supported — `tea` has no wiki commands |
**Use `gitea-mcp` first.** The `tea` CLI does not have wiki commands; the REST API is the fallback.
## MCP tools
## Authentication
Both tools take `owner`, `repo`, and a `method` discriminator.
### `wiki_read` — methods
| `method` | Other args | Returns |
|----------|-----------|---------|
| `list` | — | All page titles + slugs + content URLs |
| `get` | `pageName` | Page metadata + raw markdown |
| `get_revisions` | `pageName` | Commit history for that page |
### `wiki_write` — methods
| `method` | Required args | Notes |
|----------|--------------|-------|
| `create` | `title`, `content` | Title becomes the slug (spaces → dashes). Optional `message` for commit msg. |
| `update` | `pageName`, `content` | `pageName` is the slug. `title` and `message` are optional. |
| `delete` | `pageName` | Requires write access to the wiki. |
### Examples
List pages in `farh/example`:
```
mcp__gitea__wiki_read(method="list", owner="farh", repo="example")
```
Read the `Home` page:
```
mcp__gitea__wiki_read(method="get", owner="farh", repo="example", pageName="Home")
```
Create `Installation-Guide`:
```
mcp__gitea__wiki_write(
method="create",
owner="farh", repo="example",
title="Installation Guide",
content="# Installation\n\nStep 1...",
message="docs(wiki): add installation guide"
)
```
Update existing page:
```
mcp__gitea__wiki_write(
method="update",
owner="farh", repo="example",
pageName="Installation-Guide",
content="# Installation\n\nUpdated...",
message="docs(wiki): update installation"
)
```
Delete page:
```
mcp__gitea__wiki_write(method="delete", owner="farh", repo="example", pageName="Old-Page")
```
## REST API fallback
The MCP server wraps these endpoints. Use `curl` directly only when MCP isn't reachable.
| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/repos/{owner}/{repo}/wiki/pages` | GET | List all pages |
| `/repos/{owner}/{repo}/wiki/page/{slug}` | GET | Get a page (raw markdown by default; add `?format=html` for rendered HTML) |
| `/repos/{owner}/{repo}/wiki/revisions/{slug}` | GET | Page commit history |
| `/repos/{owner}/{repo}/wiki/new` | POST | Create a page |
| `/repos/{owner}/{repo}/wiki/page/{slug}` | PATCH | Update a page |
| `/repos/{owner}/{repo}/wiki/page/{slug}` | DELETE | Delete a page |
> Slug rules: take the title, replace spaces with `-`, drop characters that aren't `[A-Za-z0-9_./-]`. Gitea returns the canonical slug as `sub_url` in the page metadata — when in doubt, list first and read the slug back.
### Auth
```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>)
# Repo MCP config uses: Authorization: Bearer ${GITEA_TOKEN}
```
## Wiki API Endpoints
### List All Pages
```bash
GET /repos/{owner}/{repo}/wiki/pages
```
### Listing pages
```bash
curl -s "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/pages" \
-H "Authorization: Bearer $GITEA_TOKEN"
-H "Authorization: Bearer $GITEA_TOKEN" \
| jq -r '.[] | "\(.title)\t\(.sub_url)"'
```
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
### Creating a 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" \
curl -s -X POST "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/new" \
-H "Authorization: Bearer $GITEA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"title":"Installation Guide","content":"# Installation\n\nStep 1..."}'
```
### Edit/Update a Wiki Page
`content_base64` is also accepted in place of `content` for binary-safe payloads.
### Updating a 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" \
curl -s -X PATCH "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/page/Installation-Guide" \
-H "Authorization: Bearer $GITEA_TOKEN" \
-H "Content-Type: application/json" \
-d '{"content":"# Updated Installation\n\nStep 1...Step 2..."}'
-d '{"content":"# Installation\n\nUpdated..."}'
```
### Delete a Wiki Page
### Deleting a page
```bash
DELETE /repos/{owner}/{repo}/wiki/{page}
```
```bash
curl -s -X DELETE "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/Installation-Guide" \
curl -s -X DELETE "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/page/Installation-Guide" \
-H "Authorization: Bearer $GITEA_TOKEN"
```
Requires admin or owner access.
## Common Tasks
### Render Wiki Page Content for Display
### Rendered HTML
```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" \
curl -s "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/page/Home?format=html" \
-H "Authorization: Bearer $GITEA_TOKEN"
```
### List All Pages Non-Interactively
### Upsert pattern (no dedicated endpoint)
```bash
curl -s "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/pages" \
-H "Authorization: Bearer $GITEA_TOKEN" | \
jq '.[] | "\(.title) (\(.slug))"'
```
status=$(curl -s -o /dev/null -w "%{http_code}" \
"$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/page/$SLUG" \
-H "Authorization: Bearer $GITEA_TOKEN")
### 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 ...
if [ "$status" = "200" ]; then
curl -s -X PATCH "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/page/$SLUG" \
-H "Authorization: Bearer $GITEA_TOKEN" -H "Content-Type: application/json" \
-d "{\"content\":$(jq -Rs . <body.md)}"
else
# Create new
curl -s -X POST ...
curl -s -X POST "$GITEA_SERVER_URL/api/v1/repos/$OWNER/$REPO/wiki/new" \
-H "Authorization: Bearer $GITEA_TOKEN" -H "Content-Type: application/json" \
-d "{\"title\":\"$TITLE\",\"content\":$(jq -Rs . <body.md)}"
fi
```
### Open Wiki in Browser
## Wiki structure notes
```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`
- Pages are Markdown files in a dedicated `.wiki` git branch.
- Slug = sanitized title; revision history is per page.
- The whole wiki can be cloned: `git clone $GITEA_SERVER_URL/$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
- Prefer `wiki_read` / `wiki_write` MCP calls — they hide the slug/encoding rules.
- When unsure of a slug, `wiki_read` with `method="list"` and pick the canonical slug from the response.
- Add a `message` on writes — wiki commits are visible in the page revision log.
### 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.
- Assume the slug equals the title. Spaces become `-`; punctuation gets stripped.
- Use the REST API when MCP is available — MCP handles auth and slug encoding.
- Apply GitHub Wiki API conventions; Gitea's endpoints differ in path shape (`wiki/page/{slug}`, `wiki/new`).
## 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)
- [Gitea MCP server](https://gitea.com/gitea/gitea-mcp)
- [Gitea Wiki API](https://docs.gitea.com/api/next/#tag/repository/operation/repoGetWikiPages)