diff --git a/skills/gitea-axi/SKILL.md b/skills/gitea-axi/SKILL.md index 5e30a48..02951b3 100644 --- a/skills/gitea-axi/SKILL.md +++ b/skills/gitea-axi/SKILL.md @@ -6,43 +6,34 @@ description: Use when working with a Gitea repository's issues, pull requests, l # gitea-axi `gitea-axi` is an agent-ergonomic CLI for a Gitea repository's issues and pull requests. -Its output is compact TOON built for another program to read, and its errors are structured with actionable suggestions. - -## When to use it - -Reach for `gitea-axi` whenever a task touches a Gitea repository's issues, pull requests, labels, or reviews. - -- **Over `tea`:** `gitea-axi` returns structured output and typed errors instead of human-formatted tables, and it defaults the repository and login from the local checkout. -- **Over raw Gitea API calls:** it handles auth, pagination, name-to-ID resolution, and review-decision aggregation for you, so you do not hand-roll HTTP. -- **Over improvised `git`:** for anything about issues or pull requests as entities (state, reviews, labels, comments) rather than local commits and branches. +Its output is compact TOON meant to be read directly, and a failed command's error names the fix — follow that suggestion rather than guessing at another command. ## Targeting and authentication -Every command resolves two things: which repository to act on, and which credentials to authenticate with. -Get both right on the first call — they are the usual reason a command fails and has to be retried. +Every command resolves a repository and credentials; getting both right on the first call is the difference between one command and a retry. -- **Repository.** Inside a Gitea checkout it is taken from the `origin` remote automatically. - Outside a checkout you must name it: pass `-R OWNER/NAME` on every command (or set `GITEA_AXI_REPO=OWNER/NAME` once for the session). -- **Credentials.** When the environment is pre-configured — `GITEA_AXI_TOKEN` together with `GITEA_AXI_API_URL` — authentication is automatic and you need nothing more. - Otherwise credentials come from a `tea` login: pass `--login ` (or set `GITEA_AXI_LOGIN=`) unless the checkout's remote already selects one. +- **Repository.** Inside a Gitea checkout it comes from the `origin` remote. + Outside one, pass `-R OWNER/NAME` on every command, or set `GITEA_AXI_REPO=OWNER/NAME` once for the session. +- **Credentials.** With `GITEA_AXI_TOKEN` and `GITEA_AXI_API_URL` set, authentication is automatic. + Otherwise pass `--login `, or set `GITEA_AXI_LOGIN`. -So outside a checkout with the token in the environment, `gitea-axi -R OWNER/NAME …` is all you need; do not go hunting for a config file or a login profile. +Outside a checkout with the token in the environment, `gitea-axi -R OWNER/NAME …` is the whole invocation — don't look for a config file or a login profile. -## Command groups +## Commands -- `issue` — list, view, create, comment on, edit, close/reopen, pin, and link issues. -- `pr` — create, view, comment on, edit, review, merge, check out, diff, and inspect the checks of pull requests. -- `label` — list, create, edit, and delete labels. -- `search` — full-text search; it takes a subcommand, so search issues with `search issues ""` and pull requests with `search prs ""` (a bare `search ""` is not valid). -- `setup` — install this skill (`setup`) and, opt-in, the SessionStart dashboard hook (`setup hooks`). +- `issue` — list, view, create, comment, edit, close, reopen, pin, and link (blocks / blocked-by). +- `pr` — list, view, create, comment, edit, review, merge, close, reopen, diff, checks, and checkout. +- `label` — list, create, edit, delete. +- `search issues ""` and `search prs ""` — full-text search (a bare `search ""` is not valid). -To read one issue's fields, reach straight for `issue view `: it shows labels and state by default, and takes `--fields assignees,milestone,…` for the rest. -You rarely need `issue list` to answer a question about a single issue. +## Finding and acting -## Discovery +Find the target, then act on it — two commands, not a survey of the repository. -This skill is a pointer, not a command reference — the CLI is the single source of truth for its own interface. - -- Run `gitea-axi` with no arguments for the repository dashboard (open issues and pull requests). - Add `--full` for the open-PR table and issue counts by label. -- Run `gitea-axi --help` (or `gitea-axi --help`) for the exact flags of any command. +- **Find it.** If you already know the number, act on it directly. + Otherwise reach for one command — `search issues ""` for a title or keyword, or `issue list --state all --label ` to narrow by a property — not both. +- **Read one issue or PR.** `issue view ` (or `pr view `) shows labels and state by default, and takes `--fields assignees,milestone,…` for the rest. + You do not need `issue list` to answer a question about a single known issue. +- **Act on it.** `issue edit ` and `pr edit ` change fields with repeatable `--add-label` / `--remove-label` and `--add-assignee` / `--remove-assignee`, plus `--title`, `--body`, and `--milestone`. + Reviewing is `pr review ` with exactly one of `--approve`, `--request-changes`, or `--comment`, and an optional `--body`. + A comment is `issue comment --body `; a new label is `label create --name --color `. diff --git a/test/skill.test.ts b/test/skill.test.ts index bde0c3a..b8942db 100644 --- a/test/skill.test.ts +++ b/test/skill.test.ts @@ -36,19 +36,23 @@ describe("bundled Agent Skill markdown", () => { it("references each command group as a one-liner", () => { const body = skill.toLowerCase(); - for (const group of ["issue", "pr", "label", "search", "setup"]) { + for (const group of ["issue", "pr", "label", "search"]) { expect(body, `expected the skill to mention the ${group} command group`).toContain( group, ); } }); - it("points at the bare dashboard and per-command help for discovery", () => { + it("steers find-then-act and does not push exploratory discovery", () => { const body = skill.toLowerCase(); - // Bare dashboard: running the binary with no arguments. - expect(body).toContain("no argument"); - expect(body).toContain("dashboard"); - // Per-command help. - expect(body).toContain("--help"); + // The intended steering: find the target, then act on it. + expect(body).toContain("find the target"); + expect(body).toContain("act on it"); + // The find/act discipline: not a full survey, and not both find commands at once. + expect(body).toContain("not a survey"); + expect(body).toContain("not both"); + // The removed exploratory anti-pattern must be gone. + expect(body).not.toContain("dashboard"); + expect(body).not.toContain("no argument"); }); });