# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Overview

This is a **Claude Code skills repository**. Skills are reusable tools that extend Claude Code's capabilities. Each skill lives in its own top-level directory.

## Skill Structure

Each skill follows this convention:
- **`<skill-name>/SKILL.md`** — Required. YAML frontmatter (`name`, `description`, optionally `version`, `allowed-tools`) MUST start on line 1. This is the entry point Claude Code reads when invoking the skill.
- **`<skill-name>/CLAUDE.md`** — Optional. Maintainer / implementation notes kept out of the user-facing SKILL.md to reduce per-invocation token cost.
- **`<skill-name>/scripts/`** — Optional. Implementation scripts (typically bash). Scripts use `set -euo pipefail` and the `die()` pattern for error handling. Invoke scripts via `bash scripts/<name>.sh` so they work even when the executable bit did not survive deployment — but also `chmod +x` them on commit.
- **`<skill-name>/references/`** — Optional. Supporting files such as YAML templates or long-form reference documentation.

## Parent / child skill pattern

A skill may act as a router that delegates to siblings. The `gitea` skill is the canonical example: its `SKILL.md` describes the overall domain and dispatches to `gitea-tea` (CLI) and `gitea-wiki` (wiki) child skills. When adding a child skill, reference the parent in the child's `description` and keep the parent's routing table current.

## Current Skills

- **`agent-setup`** — Validates `AGENT_HOME`, derives `GH_CONFIG_DIR=$AGENT_HOME/.github`, and exports both to a session dotfile (`~/.env`) for child shells / sibling skills.
- **`github-app-token`** — Generates a short-lived GitHub App installation access token, writes it to `.gh-token` under `$GH_CONFIG_DIR` (preferred) or `$AGENT_HOME` (fallback), and authenticates the `gh` CLI. Requires `GITHUB_APP_ID`, `GITHUB_APP_INSTALLATION_ID`, and one of `GITHUB_APP_PEM` (inline PEM) or `GITHUB_APP_PEM_FILE` (path). Depends on `openssl`, `curl`, `jq`, `gh`.
- **`gitea`** — Parent skill for Gitea SCM (repos, issues, PRs, releases, Actions, wiki). Routes to `gitea-tea` and `gitea-wiki`. Prefer this — and the `gitea` MCP server wired up in `.mcp.json` — over `gh`/GitHub for repos hosted on the team's Gitea instance.
- **`gitea-tea`** — Terminal operations via the `tea` CLI. Always invoke non-interactively with `--output` and explicit args.
- **`gitea-wiki`** — Wiki page CRUD via the `gitea-mcp` server (preferred) or REST API. `tea` has no wiki subcommands.
- **`kubernetes-reflector`** — Documents Kubernetes Reflector annotations for mirroring secrets and configmaps across namespaces. Documentation only — no scripts.
- **`minimax-image-generation`** — Generates images from MiniMax's `image-01` model via `/v1/image_generation`. Requires `MINIMAX_API_KEY`; `MINIMAX_API_BASE_URL` is optional. Depends on `curl`, `jq`, `base64`.
- **`trebuchet`** — Drive the Trebuchet pentest API (start scans, poll status, retrieve findings). Scans run as K8s Jobs orchestrated by Temporal; typical duration ~36 min.

## MCP

`.mcp.json` registers the `gitea` MCP server (`https://git-mcp.farh.net/mcp`) using `${GITEA_TOKEN}` as a bearer. Skills that work against Gitea should prefer MCP tools over shelling out where an equivalent MCP call exists.

## Key Patterns

- Standard Unix tools only (`openssl`, `curl`, `jq`, `base64`). Any skill-specific runtime requirement (e.g. `gh`, `tea`) is declared in that skill's `SKILL.md`.
- `die()` prints errors to stderr and exits non-zero.
- Scripts validate required env vars up front and fail loudly rather than defaulting to `mktemp`/`/tmp` for anything secret.
- `AGENT_HOME` / `GH_CONFIG_DIR` are the shared conventions for where session state (tokens, config) lives — new skills that persist credentials should write under one of these, not `$HOME`.

## No Build/Test/Lint System

There is no centralized build, test, or lint tooling. Each skill is self-contained.