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.

4.0 KiB Raw Permalink Blame History