gitea-pr-review/skills/gitea-pr-review-cli/SKILL.md

name, description

name	description
gitea-pr-review-cli	Use when an agent needs to fetch a single Gitea PR and produce or consume the project's review document format with strict version checks.

gitea-pr-review CLI

Overview

Use this skill when you need PR review context from Gitea in a stable document format for LLM workflows.

The CLI supports two output formats (markdown, json) and one strict schema version (v1). Version mismatch must be treated as a hard failure.

When to Use

Use this skill when:

• You need to fetch one PR and convert it into LLM-friendly review documents.
• You need to re-render Markdown from a previously generated JSON file.
• You need deterministic output rules (numbering/version/header fields).

Do not use this skill when:

• You need cross-PR aggregation.
• You need full patch/diff bodies (this tool intentionally focuses on review context + diff stat).

Required Inputs

For fetch, these environment variables are required:

• GITEA_PR_CLI_API_TOKEN
• GITEA_PR_CLI_URL
• GITEA_PR_CLI_REPO

Quick Start

# 0) load env
source .local/env.sh

# 1) sanity check CLI document version contract
gitea-pr-review version
# expected: v1

# 2) fetch markdown to stdout (default)
gitea-pr-review fetch <pr-index>

# 3) fetch json to file
gitea-pr-review fetch <pr-index> --format json --out pr.json

# 4) render markdown from json
gitea-pr-review render-md --in pr.json --out pr.md

Command Reference

fetch <pr-index>

Fetch PR data from Gitea and output review document.

Options:

• --format markdown|json (default markdown)
• --out <path> (if omitted, write to stdout)

render-md --in <json_path>

Render Markdown from existing JSON document.

Options:

• --out <path> (if omitted, write to stdout)

Important:

• Input JSON must have version == "v1".
• If version mismatches, command exits non-zero.

version

Print current document version string.

Expected output:

• v1

Output Contract (v1)

Markdown header contains:

• Title line: # <repo> #<pr> <title>
• Numbering rule block
• version: v1
• fetched at: <rfc3339>
• PR description

JSON contains:

• Top-level version: "v1"
• meta.fetched_at (RFC3339 string)

Numbering hierarchy:

• Review: <pr>.<review>
• Comment: <pr>.<review>.<comment>
• Reply: <pr>.<review>.<comment>.<reply>

Failure Handling

If fetch fails:

1. Check all required env vars are set.
2. Re-run with same env using a small PR index to isolate auth/connectivity issues.
3. Confirm repo slug format is <owner>/<repo>.

If render-md fails:

1. Validate JSON is generated by this CLI.
2. Validate version is exactly v1.
3. Check JSON is complete (meta, reviews, threads, diff_stat).

Common Mistakes

• Running fetch without sourcing env file.
• Assuming schema compatibility across versions.
• Editing JSON version manually and expecting render-md to work.
• Treating position-only comments as lacking location; this CLI maps available position data to a displayed line when possible.