alexion/gitea-axi
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(skill): steer find-then-act instead of open-ended discovery

Browse Source 
The bundled skill's Discovery section told the agent to run the bare
dashboard and reach for --help proactively, and advertised overlapping
find-paths — inducing exploratory commands that made the gitea-axi arm the
most expensive of the benchmark's four. Replace it with a "find the target,
then act" section, name the non-obvious mutation flags so common edits do
not need --help, and drop the setup line and the over-tea/raw/git bullets
that only duplicated the description. A same-time A/B cut cost-equivalent
tokens ~10% and collapsed bare-dashboard use from 60% to 7% with no loss of
success.
This commit is contained in:
alexion
2026-07-19 09:41:13 -04:00
parent dd58cd9dad
commit d56b1d0707
2 changed files with 32 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
skills/gitea-axi/SKILL.md
View File

@@ -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 <name>` (or set `GITEA_AXI_LOGIN=<name>`) 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 <name>`, or set `GITEA_AXI_LOGIN`.
So outside a checkout with the token in the environment, `gitea-axi <command> -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 <command> -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 "<query>"` and pull requests with `search prs "<query>"` (a bare `search "<query>"` 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 "<query>"` and `search prs "<query>"` — full-text search (a bare `search "<query>"` is not valid).
To read one issue's fields, reach straight for `issue view <number>`: 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 <command> --help` (or `gitea-axi <group> <command> --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 "<query>"` for a title or keyword, or `issue list --state all --label <name>` to narrow by a property — not both.
- **Read one issue or PR.** `issue view <number>` (or `pr view <number>`) 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 <number>` and `pr edit <number>` change fields with repeatable `--add-label` / `--remove-label` and `--add-assignee` / `--remove-assignee`, plus `--title`, `--body`, and `--milestone`.
Reviewing is `pr review <number>` with exactly one of `--approve`, `--request-changes`, or `--comment`, and an optional `--body`.
A comment is `issue comment <number> --body <text>`; a new label is `label create --name <text> --color <hex-without-#>`.

18
test/skill.test.ts
View File

@@ -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");
});
});