@hivey/cli 0.0.0-stage → 0.9.36
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +235 -2
- package/bin/hivey.js +98 -0
- package/native/darwin-arm64/hivey +0 -0
- package/package.json +36 -4
- package/platforms.json +3 -0
- package/repo/LICENSE +201 -0
- package/repo/NOTICE +18 -0
- package/repo/README.md +148 -0
- package/repo/install.sh +365 -0
- package/repo/pets/README.md +25 -0
- package/repo/pets/hivey-dot/CLAUDE.md +55 -0
- package/repo/pets/hivey-dot/build.sh +34 -0
- package/repo/pets/hivey-dot/main.swift +750 -0
- package/repo/pets/hivey-h/CLAUDE.md +75 -0
- package/repo/pets/hivey-h/build.sh +34 -0
- package/repo/pets/hivey-h/main.swift +739 -0
- package/repo/pets/hivey-prompt/CLAUDE.md +59 -0
- package/repo/pets/hivey-prompt/build.sh +34 -0
- package/repo/pets/hivey-prompt/main.swift +691 -0
- package/repo/pets/pet.py +288 -0
- package/repo/pets/shared/HiveyWatch.swift +437 -0
- package/repo/pets/test_pet.py +122 -0
- package/repo/plugins/README.md +108 -0
- package/repo/plugins/agent-creator/herdr-plugin.toml +17 -0
- package/repo/plugins/dashboard/dashboard.py +507 -0
- package/repo/plugins/dashboard/herdr-plugin.toml +14 -0
- package/repo/plugins/dashboard/test_dashboard.py +134 -0
- package/repo/plugins/github/github.py +261 -0
- package/repo/plugins/github/herdr-plugin.toml +14 -0
- package/repo/plugins/github/test_github.py +49 -0
- package/repo/plugins/skills/herdr-plugin.toml +11 -0
- package/repo/plugins/skills/skills.md +41 -0
- package/repo/plugins/slack-relay/connect.py +198 -0
- package/repo/plugins/slack-relay/create_channel.py +134 -0
- package/repo/plugins/slack-relay/herdr-plugin.toml +15 -0
- package/repo/plugins/slack-relay/relay.py +401 -0
- package/repo/plugins/slack-relay/slack-app-manifest.json +30 -0
- package/repo/plugins/slack-relay/test_connect.py +66 -0
- package/repo/plugins/slack-relay/test_create_channel.py +61 -0
- package/repo/plugins/slack-relay/test_relay.py +254 -0
- package/repo/plugins/swarm-creator/herdr-plugin.toml +17 -0
- package/repo/plugins/swarm-watcher/dashboard.py +333 -0
- package/repo/plugins/swarm-watcher/herdr-plugin.toml +16 -0
- package/repo/plugins/swarm-watcher/usage.py +129 -0
- package/repo/plugins/swarm-watcher/watcher.py +191 -0
- package/repo/plugins/team-template/herdr-plugin.toml +15 -0
- package/repo/plugins/team-template/setup.py +211 -0
- package/repo/plugins/team-template/test_setup.py +73 -0
- package/repo/plugins/tts/herdr-plugin.toml +15 -0
- package/repo/skills/herdr/SKILL.md +214 -0
- package/repo/skills/hivey/SKILL.md +322 -0
- package/repo/skills/hivey/scripts/handoff.py +27 -0
- package/repo/skills/hivey/scripts/new_wiki.py +143 -0
- package/repo/skills/hivey-agent-creator/SKILL.md +303 -0
- package/repo/skills/hivey-agent-creator/references/agent-claude-md.md +256 -0
- package/repo/skills/hivey-agent-creator/references/global-guidelines.md +67 -0
- package/repo/skills/hivey-agent-creator/references/reviewer-agent.md +35 -0
- package/repo/skills/hivey-agent-creator/scripts/agent_context.py +76 -0
- package/repo/skills/hivey-agent-creator/scripts/agent_gate.py +78 -0
- package/repo/skills/hivey-agent-creator/scripts/setup_agent.py +288 -0
- package/repo/skills/hivey-agy/SKILL.md +123 -0
- package/repo/skills/hivey-agy/references/gemini-prompting.md +134 -0
- package/repo/skills/hivey-agy/scripts/agy_run.py +146 -0
- package/repo/skills/hivey-codex/SKILL.md +66 -0
- package/repo/skills/hivey-context7/SKILL.md +56 -0
- package/repo/skills/hivey-create-wiki/SKILL.md +329 -0
- package/repo/skills/hivey-grok/SKILL.md +101 -0
- package/repo/skills/hivey-grok/scripts/grok_run.py +139 -0
- package/repo/skills/hivey-swarm-creator/SKILL.md +384 -0
- package/repo/skills/hivey-swarm-creator/references/agent-claude-md.md +313 -0
- package/repo/skills/hivey-swarm-creator/references/archify-report.md +24 -0
- package/repo/skills/hivey-swarm-creator/references/dashboard.md +46 -0
- package/repo/skills/hivey-swarm-creator/references/retrospective.md +23 -0
- package/repo/skills/hivey-swarm-creator/references/shared-rules.md +39 -0
- package/repo/skills/hivey-swarm-creator/references/wiki-memory.md +30 -0
- package/repo/skills/hivey-swarm-creator/scripts/setup_agent.py +76 -0
- package/repo/skills/hivey-swarm-creator/scripts/shared_rules.py +50 -0
- package/repo/skills/hivey-swarm-creator/scripts/swarm_tasks.py +171 -0
- package/repo/skills/hivey-wiki-ingest/SKILL.md +45 -0
- package/repo/skills/hivey-wiki-lint/SKILL.md +38 -0
- package/repo/skills/hivey-wiki-list/SKILL.md +46 -0
- package/repo/skills/hivey-wiki-log/SKILL.md +45 -0
- package/repo/skills/hivey-wiki-query/SKILL.md +44 -0
|
@@ -0,0 +1,288 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""Scaffold (or update) the folder of one hivey solo agent.
|
|
3
|
+
|
|
4
|
+
Writes, inside the agent folder only (never the global Claude Code config):
|
|
5
|
+
CLAUDE.md a skeleton with the brief's sections and Status markers, if missing
|
|
6
|
+
.claude/settings.json additionalDirectories (the folder + --dirs; hivey launch turns them
|
|
7
|
+
into --add-dir), allow/deny rules (git push is always denied),
|
|
8
|
+
enabledMcpjsonServers, and with --gate the done-gate (Stop) and
|
|
9
|
+
resume-context (SessionStart) hooks
|
|
10
|
+
.mcp.json project-scoped MCP servers given with --mcp
|
|
11
|
+
.codex/config.toml the same MCP servers for a Codex agent
|
|
12
|
+
.agent/config.json the run check (--check-cmd) and optional progress log
|
|
13
|
+
.claude/agents/reviewer.md with --reviewer (Claude Code only)
|
|
14
|
+
.gitignore keeps files that may hold keys and runtime state out of git
|
|
15
|
+
|
|
16
|
+
Idempotent: re-running only adds. Skills are not installed here: follow `hivey skills guide`.
|
|
17
|
+
Standard library only. Prints a JSON report.
|
|
18
|
+
"""
|
|
19
|
+
import argparse
|
|
20
|
+
import json
|
|
21
|
+
import re
|
|
22
|
+
import shutil
|
|
23
|
+
import subprocess
|
|
24
|
+
from pathlib import Path
|
|
25
|
+
|
|
26
|
+
HERE = Path(__file__).absolute().parent # keep the installed path (hooks point at it)
|
|
27
|
+
PROJECT_HOOKS = { # event -> script registered in the agent's own .claude/settings.json
|
|
28
|
+
"Stop": HERE / "agent_gate.py",
|
|
29
|
+
"SessionStart": HERE / "agent_context.py",
|
|
30
|
+
}
|
|
31
|
+
NAME_RE = re.compile(r"^[a-z][a-z0-9-]{0,31}$")
|
|
32
|
+
KINDS = ("claude", "codex", "grok", "agy")
|
|
33
|
+
ALWAYS_DENY = ["Bash(git push:*)"]
|
|
34
|
+
GITIGNORE = [".mcp.json", ".codex/", ".agent/state/", "logs/"]
|
|
35
|
+
|
|
36
|
+
SKELETON = """# {name} — <one-line role>
|
|
37
|
+
|
|
38
|
+
> You are **{name}**, a solo hivey agent (address `{name}/master`). This file defines your role.
|
|
39
|
+
|
|
40
|
+
## Rules
|
|
41
|
+
|
|
42
|
+
## Start of every session
|
|
43
|
+
|
|
44
|
+
## The ask
|
|
45
|
+
|
|
46
|
+
## Your mission
|
|
47
|
+
|
|
48
|
+
## Deliverables
|
|
49
|
+
| # | Deliverable | Path | Done when | Check |
|
|
50
|
+
|---|-------------|------|-----------|-------|
|
|
51
|
+
|
|
52
|
+
## Where you work
|
|
53
|
+
- Home: `{dir}`
|
|
54
|
+
|
|
55
|
+
## Your toolkit
|
|
56
|
+
|
|
57
|
+
## Method
|
|
58
|
+
|
|
59
|
+
## Run protocol (every run, on demand or scheduled)
|
|
60
|
+
|
|
61
|
+
## Memory
|
|
62
|
+
|
|
63
|
+
## Other agents
|
|
64
|
+
|
|
65
|
+
## Definition of done
|
|
66
|
+
|
|
67
|
+
---
|
|
68
|
+
|
|
69
|
+
## Status
|
|
70
|
+
<!-- STATUS:START -->
|
|
71
|
+
_Not started yet._
|
|
72
|
+
<!-- STATUS:END -->
|
|
73
|
+
"""
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def add_unique(lst, items):
|
|
77
|
+
for item in items:
|
|
78
|
+
if item not in lst:
|
|
79
|
+
lst.append(item)
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
def read_json(path):
|
|
83
|
+
if not path.exists():
|
|
84
|
+
return {}
|
|
85
|
+
try:
|
|
86
|
+
return json.loads(path.read_text())
|
|
87
|
+
except json.JSONDecodeError as err:
|
|
88
|
+
raise SystemExit(f"{path} is not valid JSON ({err}); fix it first")
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def write_json(path, data):
|
|
92
|
+
path.parent.mkdir(parents=True, exist_ok=True)
|
|
93
|
+
path.write_text(json.dumps(data, indent=2) + "\n")
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
def toml_str(value):
|
|
97
|
+
return json.dumps(str(value)) # JSON string escapes are valid TOML basic strings
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def codex_mcp_tables(servers):
|
|
101
|
+
"""Render .mcp.json server entries as Codex [mcp_servers.<name>] TOML tables."""
|
|
102
|
+
out = []
|
|
103
|
+
for name, cfg in servers.items():
|
|
104
|
+
out.append(f"[mcp_servers.{toml_str(name)}]")
|
|
105
|
+
if cfg.get("url"):
|
|
106
|
+
out.append(f"url = {toml_str(cfg['url'])}")
|
|
107
|
+
else:
|
|
108
|
+
out.append(f"command = {toml_str(cfg.get('command', ''))}")
|
|
109
|
+
if cfg.get("args"):
|
|
110
|
+
out.append("args = [" + ", ".join(toml_str(a) for a in cfg["args"]) + "]")
|
|
111
|
+
if cfg.get("env"):
|
|
112
|
+
out.append(f"[mcp_servers.{toml_str(name)}.env]")
|
|
113
|
+
out += [f"{toml_str(k)} = {toml_str(v)}" for k, v in cfg["env"].items()]
|
|
114
|
+
out.append("")
|
|
115
|
+
return out
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
def parse_mcp(spec):
|
|
119
|
+
"""NAME=JSON -> (name, server config)."""
|
|
120
|
+
name, sep, raw = spec.partition("=")
|
|
121
|
+
name = name.strip()
|
|
122
|
+
if not sep or not name:
|
|
123
|
+
raise SystemExit(f"--mcp {spec!r}: expected NAME=JSON, e.g. "
|
|
124
|
+
"'fetch={\"command\":\"uvx\",\"args\":[\"mcp-server-fetch\"]}'")
|
|
125
|
+
try:
|
|
126
|
+
cfg = json.loads(raw)
|
|
127
|
+
except json.JSONDecodeError as err:
|
|
128
|
+
raise SystemExit(f"--mcp {name}: invalid JSON ({err})")
|
|
129
|
+
if not isinstance(cfg, dict) or not (cfg.get("command") or cfg.get("url")):
|
|
130
|
+
raise SystemExit(f"--mcp {name}: the JSON needs a \"command\" or a \"url\"")
|
|
131
|
+
return name, cfg
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
def add_project_hooks(settings):
|
|
135
|
+
"""Register the done gate + resume-context hooks in the agent's settings (idempotent)."""
|
|
136
|
+
hooks = settings.setdefault("hooks", {})
|
|
137
|
+
added = []
|
|
138
|
+
for event, script in PROJECT_HOOKS.items():
|
|
139
|
+
cmd = f"python3 {script}"
|
|
140
|
+
entries = hooks.setdefault(event, [])
|
|
141
|
+
if any(h.get("command") == cmd for m in entries for h in m.get("hooks", [])):
|
|
142
|
+
continue
|
|
143
|
+
entries.append({"hooks": [{"type": "command", "command": cmd, "timeout": 330}]})
|
|
144
|
+
added.append(event)
|
|
145
|
+
return added
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
def in_git_repo(folder):
|
|
149
|
+
try:
|
|
150
|
+
r = subprocess.run(["git", "-C", str(folder), "rev-parse", "--is-inside-work-tree"],
|
|
151
|
+
capture_output=True, text=True)
|
|
152
|
+
except FileNotFoundError:
|
|
153
|
+
return None
|
|
154
|
+
return r.returncode == 0
|
|
155
|
+
|
|
156
|
+
|
|
157
|
+
def main():
|
|
158
|
+
p = argparse.ArgumentParser(
|
|
159
|
+
description="Scaffold or update a hivey solo agent's folder (see SKILL.md step 5).",
|
|
160
|
+
formatter_class=argparse.RawDescriptionHelpFormatter,
|
|
161
|
+
epilog="example:\n setup_agent.py ~/agents/seo-auditor --name seo-auditor --kind claude \\\n"
|
|
162
|
+
" --check-cmd 'bash scripts/check.sh' --gate --reviewer --git")
|
|
163
|
+
p.add_argument("folder", help="the agent folder (created if missing)")
|
|
164
|
+
p.add_argument("--name", required=True, help="agent name / slug, [a-z][a-z0-9-]{0,31}")
|
|
165
|
+
p.add_argument("--kind", choices=KINDS, default="claude", help="coding agent (default claude)")
|
|
166
|
+
p.add_argument("--dirs", default="", help="comma-separated extra folders the agent may use")
|
|
167
|
+
p.add_argument("--allow", action="append", default=[], help="Claude Code allow rule (repeatable)")
|
|
168
|
+
p.add_argument("--deny", action="append", default=[], help="Claude Code deny rule (repeatable)")
|
|
169
|
+
p.add_argument("--mcp", action="append", default=[], metavar="NAME=JSON",
|
|
170
|
+
help="add a project MCP server to .mcp.json (repeatable)")
|
|
171
|
+
p.add_argument("--enable-mcps", default="", help="pre-approve servers already in .mcp.json")
|
|
172
|
+
p.add_argument("--check-cmd", help="run check, run in the agent folder; exit 0 = run done")
|
|
173
|
+
p.add_argument("--progress-log", help="a newest-first log file the resume context summarizes")
|
|
174
|
+
p.add_argument("--gate", action="store_true",
|
|
175
|
+
help="register the done gate and resume-context hooks (Claude Code only)")
|
|
176
|
+
p.add_argument("--reviewer", action="store_true",
|
|
177
|
+
help="install the read-only reviewer subagent (Claude Code only)")
|
|
178
|
+
p.add_argument("--git", action="store_true", help="git init the folder if it isn't in a repo")
|
|
179
|
+
args = p.parse_args()
|
|
180
|
+
|
|
181
|
+
if not NAME_RE.match(args.name):
|
|
182
|
+
raise SystemExit(f"invalid name {args.name!r}: must match {NAME_RE.pattern}")
|
|
183
|
+
agent_dir = Path(args.folder).expanduser().resolve()
|
|
184
|
+
if agent_dir == Path.home().resolve():
|
|
185
|
+
raise SystemExit("refusing to use your home folder as an agent folder")
|
|
186
|
+
if args.gate and not (args.check_cmd or read_json(agent_dir / ".agent" / "config.json").get("check")):
|
|
187
|
+
raise SystemExit("--gate needs a run check: pass --check-cmd")
|
|
188
|
+
agent_dir.mkdir(parents=True, exist_ok=True)
|
|
189
|
+
result = {"agent": args.name, "kind": args.kind, "dir": str(agent_dir), "notes": []}
|
|
190
|
+
|
|
191
|
+
brief = agent_dir / "CLAUDE.md"
|
|
192
|
+
if not brief.exists():
|
|
193
|
+
brief.write_text(SKELETON.format(name=args.name, dir=agent_dir))
|
|
194
|
+
result["claude_md"] = "skeleton written"
|
|
195
|
+
else:
|
|
196
|
+
result["claude_md"] = "kept"
|
|
197
|
+
|
|
198
|
+
settings_path = agent_dir / ".claude" / "settings.json"
|
|
199
|
+
settings = read_json(settings_path)
|
|
200
|
+
perms = settings.setdefault("permissions", {})
|
|
201
|
+
dirs = [str(agent_dir)] + [str(Path(d.strip()).expanduser().resolve())
|
|
202
|
+
for d in args.dirs.split(",") if d.strip()]
|
|
203
|
+
add_unique(perms.setdefault("additionalDirectories", []), dirs)
|
|
204
|
+
if args.allow:
|
|
205
|
+
add_unique(perms.setdefault("allow", []), args.allow)
|
|
206
|
+
add_unique(perms.setdefault("deny", []), ALWAYS_DENY + args.deny)
|
|
207
|
+
if args.kind == "grok" and len(dirs) > 1:
|
|
208
|
+
result["notes"].append("grok can't use extra folders: keep its work inside the agent folder")
|
|
209
|
+
if args.kind != "claude" and (args.allow or args.deny):
|
|
210
|
+
result["notes"].append("allow/deny rules apply to Claude Code only")
|
|
211
|
+
|
|
212
|
+
mcp_names = [m.strip() for m in args.enable_mcps.split(",") if m.strip()]
|
|
213
|
+
mcp_path = agent_dir / ".mcp.json"
|
|
214
|
+
if args.mcp:
|
|
215
|
+
mcp = read_json(mcp_path)
|
|
216
|
+
servers = mcp.setdefault("mcpServers", {})
|
|
217
|
+
for spec in args.mcp:
|
|
218
|
+
name, cfg = parse_mcp(spec)
|
|
219
|
+
servers[name] = cfg
|
|
220
|
+
add_unique(mcp_names, [name])
|
|
221
|
+
write_json(mcp_path, mcp)
|
|
222
|
+
if mcp_names:
|
|
223
|
+
servers = read_json(mcp_path).get("mcpServers", {})
|
|
224
|
+
result["mcps_missing"] = [m for m in mcp_names if m not in servers]
|
|
225
|
+
found = {m: servers[m] for m in mcp_names if m in servers}
|
|
226
|
+
add_unique(settings.setdefault("enabledMcpjsonServers", []), sorted(found))
|
|
227
|
+
result["mcps"] = sorted(found)
|
|
228
|
+
result["mcps_with_env"] = sorted(m for m, cfg in found.items() if cfg.get("env"))
|
|
229
|
+
if args.kind == "codex":
|
|
230
|
+
codex_cfg = agent_dir / ".codex" / "config.toml"
|
|
231
|
+
codex_cfg.parent.mkdir(exist_ok=True)
|
|
232
|
+
all_servers = read_json(mcp_path).get("mcpServers", {})
|
|
233
|
+
codex_cfg.write_text("# Project-scoped Codex config written by hivey-agent-creator "
|
|
234
|
+
"(may hold MCP keys; git-ignored)\n\n"
|
|
235
|
+
+ "\n".join(codex_mcp_tables(all_servers)))
|
|
236
|
+
result["codex_config"] = str(codex_cfg)
|
|
237
|
+
elif args.kind in ("grok", "agy"):
|
|
238
|
+
result["notes"].append(f"{args.kind} doesn't read .mcp.json: set up its MCP servers "
|
|
239
|
+
"with its own CLI, or prefer a CLI tool")
|
|
240
|
+
|
|
241
|
+
cfg_path = agent_dir / ".agent" / "config.json"
|
|
242
|
+
if args.check_cmd or args.progress_log:
|
|
243
|
+
cfg = read_json(cfg_path)
|
|
244
|
+
if args.check_cmd:
|
|
245
|
+
cfg["check"] = args.check_cmd
|
|
246
|
+
if args.progress_log:
|
|
247
|
+
cfg["progress_log"] = str(Path(args.progress_log).expanduser())
|
|
248
|
+
write_json(cfg_path, cfg)
|
|
249
|
+
result["agent_config"] = cfg
|
|
250
|
+
(agent_dir / ".agent" / "state").mkdir(parents=True, exist_ok=True)
|
|
251
|
+
(agent_dir / "logs").mkdir(exist_ok=True)
|
|
252
|
+
|
|
253
|
+
if args.gate:
|
|
254
|
+
if args.kind == "claude":
|
|
255
|
+
result["hooks_added"] = add_project_hooks(settings)
|
|
256
|
+
else:
|
|
257
|
+
result["notes"].append("the done gate is a Claude Code hook: the brief tells this "
|
|
258
|
+
"agent to run the check itself")
|
|
259
|
+
if args.reviewer:
|
|
260
|
+
if args.kind != "claude":
|
|
261
|
+
result["reviewer"] = "skipped: the reviewer subagent is Claude Code only"
|
|
262
|
+
else:
|
|
263
|
+
dest = agent_dir / ".claude" / "agents" / "reviewer.md"
|
|
264
|
+
dest.parent.mkdir(parents=True, exist_ok=True)
|
|
265
|
+
shutil.copy(HERE.parent / "references" / "reviewer-agent.md", dest)
|
|
266
|
+
result["reviewer"] = str(dest)
|
|
267
|
+
|
|
268
|
+
write_json(settings_path, settings)
|
|
269
|
+
result["settings"] = str(settings_path)
|
|
270
|
+
|
|
271
|
+
gitignore = agent_dir / ".gitignore"
|
|
272
|
+
lines = gitignore.read_text().splitlines() if gitignore.exists() else []
|
|
273
|
+
add_unique(lines, GITIGNORE)
|
|
274
|
+
gitignore.write_text("\n".join(lines) + "\n")
|
|
275
|
+
|
|
276
|
+
repo = in_git_repo(agent_dir)
|
|
277
|
+
if args.git and repo is False:
|
|
278
|
+
subprocess.run(["git", "init", "-q", str(agent_dir)], check=True)
|
|
279
|
+
repo = True
|
|
280
|
+
result["git"] = "initialized"
|
|
281
|
+
else:
|
|
282
|
+
result["git"] = {True: "in a repo", False: "not a repo (pass --git)", None: "git missing"}[repo]
|
|
283
|
+
|
|
284
|
+
print(json.dumps(result, indent=2))
|
|
285
|
+
|
|
286
|
+
|
|
287
|
+
if __name__ == "__main__":
|
|
288
|
+
main()
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: hivey-agy
|
|
3
|
+
description: Run a task with Google's Antigravity CLI (`agy`, the replacement for Gemini CLI). Picks the right model and effort for the task (Gemini 3.8 Flash low/medium/high, Gemini 3.1 Pro, or Claude / gpt-oss through agy), writes an effective Gemini-style prompt, runs agy headless through a bundled uv Python runner, and checks the result, including any files the task should create. Use it whenever the user wants something done "with agy", "with Antigravity", "with Gemini", "ask Gemini", wants a Gemini second opinion, or wants to hand a coding, research, summarising, extraction or image-generation task to agy. Also use it when they ask which agy model to use or how to prompt Gemini, even if they don't say "agy". Not for driving the Antigravity IDE app, and not for calling the Gemini API from code.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
> Local additions: if `EXTRA_SKILL.md` exists in this skill's folder, read it too and follow it.
|
|
7
|
+
> It holds this machine's own additions; hivey updates never touch it, so put local changes
|
|
8
|
+
> there, never here.
|
|
9
|
+
|
|
10
|
+
# agy: run a task with the right model and prompt
|
|
11
|
+
|
|
12
|
+
The user gives a task. Your job is to (1) choose the agy model, (2) write the prompt agy gets,
|
|
13
|
+
(3) run it headless, (4) check the result and report. agy is a full agent: it can read and
|
|
14
|
+
write files in its workspace, run shell commands, search the web, browse, and generate images.
|
|
15
|
+
|
|
16
|
+
Runner: `uv run -q --script ~/.claude/skills/hivey-agy/scripts/agy_run.py` (called `RUN` below).
|
|
17
|
+
It's stdlib-only and wraps `~/.local/bin/agy`. Call agy by full path or through `RUN`: some
|
|
18
|
+
shells still carry an old `alias agy="agy . …"` that breaks bare `agy`.
|
|
19
|
+
|
|
20
|
+
## 1. Understand the task
|
|
21
|
+
|
|
22
|
+
Work out four things. Usually you can infer them, so don't interrogate the user:
|
|
23
|
+
- **Kind**: quick answer · structured extraction · summary/writing · research (needs web) ·
|
|
24
|
+
coding/file work in a folder · image · multi-turn conversation.
|
|
25
|
+
- **Workspace**: which folder agy should work in (`--cwd`). For pure Q&A, use a scratch dir
|
|
26
|
+
like `/tmp/agy-<slug>` so agy doesn't wander around in your current folder.
|
|
27
|
+
- **Done-when**: what has to be true at the end (a file exists, tests pass, a JSON shape, an answer).
|
|
28
|
+
- **Model override**: if the user named a model or tier, use it.
|
|
29
|
+
|
|
30
|
+
Ask the user only when the missing piece would change what you run, such as which repo or what
|
|
31
|
+
the output file should be. Otherwise assume, and mention the assumption in your report.
|
|
32
|
+
|
|
33
|
+
## 2. Pick the model
|
|
34
|
+
|
|
35
|
+
Gemini slugs already encode effort (`-low/-medium/-high`), so don't add `--effort` for them.
|
|
36
|
+
Check what's currently available with `RUN --models`. The list changes as Google ships models.
|
|
37
|
+
|
|
38
|
+
| Task | Model | Why |
|
|
39
|
+
|---|---|---|
|
|
40
|
+
| One-line answers, reformatting, classification, `--schema` extraction | `gemini-3.8-flash-low` | Fast and cheap; reasoning isn't the bottleneck |
|
|
41
|
+
| Default: everyday coding, summaries, writing, explanations | `gemini-3.8-flash-medium` | Best speed/quality balance |
|
|
42
|
+
| Hard debugging, multi-file refactors, long agent runs, web research, planning | `gemini-3.8-flash-high` | 3.8 Flash high matches or beats 3.1 Pro on most coding/agent benchmarks |
|
|
43
|
+
| Very long documents (≫100k tokens), deep reasoning where flash-high already failed, a second opinion | `gemini-3.1-pro-high` | Different model family; use it as the escalation tier |
|
|
44
|
+
| User wants Claude through agy, or careful prose / code review | `claude-sonnet-4-6`, or `claude-opus-4-6-thinking` for the hardest | Available in agy at no extra setup |
|
|
45
|
+
| Cheap open-model second opinion | `gpt-oss-120b-medium` | Independent check |
|
|
46
|
+
|
|
47
|
+
Older 3.7/3.6 Flash slugs exist only for comparison. Don't pick them by default.
|
|
48
|
+
If a run fails or gives a shallow result, escalate one step (low → medium → high → pro-high)
|
|
49
|
+
instead of rewriting the prompt into a monster.
|
|
50
|
+
|
|
51
|
+
## 3. Write the prompt
|
|
52
|
+
|
|
53
|
+
Read `references/gemini-prompting.md` the first time you use this skill in a session. In short:
|
|
54
|
+
- **Direct, compact, structured.** Role, constraints and output format go at the top, in one
|
|
55
|
+
style (XML tags *or* Markdown headers). No hype, no "think step by step", no threats. The
|
|
56
|
+
`-high` tier already does the reasoning.
|
|
57
|
+
- **Long pasted data goes in the middle, and the question at the end**, starting with "Based on
|
|
58
|
+
the information above…".
|
|
59
|
+
- **Spell out output size and shape.** Gemini defaults to terse, so ask for length, sections
|
|
60
|
+
or a full file if you want them.
|
|
61
|
+
- **Give it a done-when and a report line** for agentic work. Headless agy can't ask questions,
|
|
62
|
+
so add "if unclear, assume reasonably and state the assumption".
|
|
63
|
+
- **Phrase rules positively.** Absolute bans ("never infer") make Gemini over-literal.
|
|
64
|
+
- **Use the user's own words for the goal**, and add the context they didn't think to give
|
|
65
|
+
(paths, versions, the repo's test command).
|
|
66
|
+
|
|
67
|
+
Use the templates in the reference: generic, long-context, agentic coding, and the task-type
|
|
68
|
+
patterns (research, extraction, writing, debugging, image).
|
|
69
|
+
|
|
70
|
+
## 4. Run it
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
RUN=~/.claude/skills/hivey-agy/scripts/agy_run.py
|
|
74
|
+
uv run -q --script $RUN -m <model> [flags] "<prompt>" # or: printf '%s' "$P" | … -
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Flags to choose:
|
|
78
|
+
- `--cwd <dir>` is the workspace agy reads and writes. Always set it for file work.
|
|
79
|
+
- `--schema '<json schema>'` returns parsed JSON for extraction. Prefer it over describing
|
|
80
|
+
JSON in prose.
|
|
81
|
+
- `--yolo` (= `--dangerously-skip-permissions`) is needed whenever agy must **run shell
|
|
82
|
+
commands, read web pages (research), or create images**. Headless agy soft-denies those, and
|
|
83
|
+
the run can still "succeed" with an empty or half-done answer. The runner prints
|
|
84
|
+
`[DENIED] …` when that happens. Use `--yolo` only in the task's own folder (a scratch dir for
|
|
85
|
+
research). For untrusted code, add `--sandbox`.
|
|
86
|
+
- `--expect <file>` (repeatable) makes the run exit 3 if the file wasn't created. Use it for
|
|
87
|
+
every task that should produce a file. agy can report SUCCESS after a tool failed upstream.
|
|
88
|
+
- `--timeout 20m` for long agent runs (the default is 10m).
|
|
89
|
+
- `--json` returns the full envelope (`conversation_id`, `usage`). Keep the id when a
|
|
90
|
+
follow-up is likely, then continue with `--conversation <id>` (or `-c` for the last one).
|
|
91
|
+
- `--chat` is an interactive multi-turn session. Use it only when the user wants to talk to
|
|
92
|
+
agy themselves.
|
|
93
|
+
|
|
94
|
+
For long prompts, write the prompt to a temp file and pipe it in (`… - < /tmp/agy-prompt.md`)
|
|
95
|
+
so shell quoting can't mangle it.
|
|
96
|
+
|
|
97
|
+
Runs can take minutes. For anything you expect to exceed ~2 minutes, run it in the background
|
|
98
|
+
and tell the user it's running.
|
|
99
|
+
|
|
100
|
+
## 5. Check and report
|
|
101
|
+
|
|
102
|
+
- **Exit codes:** 0 = success. 1 = agy error (read stderr: auth, unknown model, timeout).
|
|
103
|
+
3 = an expected file is missing. 4 = agy finished with an empty answer, usually because an
|
|
104
|
+
action was denied. Rerun with `--yolo`.
|
|
105
|
+
- **Look at the output yourself:** open the created file and run the tests it claimed to pass.
|
|
106
|
+
For images, use Read on the image file to look at it. Don't relay "done" from agy unchecked.
|
|
107
|
+
- **Image fallback:** if agy's image generation keeps failing (it returned upstream 500s on
|
|
108
|
+
2026-10-11), offer the user the `gemini-image-chrome` skill (Gemini in Chrome) as a fallback.
|
|
109
|
+
- **Report briefly:** which model and why (one line), the prompt you sent (collapsed or short
|
|
110
|
+
if it's long), the result or file paths, anything you verified, and any assumption you made.
|
|
111
|
+
|
|
112
|
+
## Example
|
|
113
|
+
|
|
114
|
+
User: "with agy, summarise ~/Downloads/report.pdf for my team in 5 bullets"
|
|
115
|
+
- Kind: summary. Model: `gemini-3.8-flash-medium`. Workspace: `~/Downloads`.
|
|
116
|
+
- Prompt:
|
|
117
|
+
```
|
|
118
|
+
<role>You summarise business documents for a busy engineering team.</role>
|
|
119
|
+
<task>Read report.pdf in the current folder and summarise it.</task>
|
|
120
|
+
<output_format>Exactly 5 Markdown bullets, each ≤25 words, keep key numbers and decisions.
|
|
121
|
+
Then one line "Open questions:" listing anything the report leaves unresolved.</output_format>
|
|
122
|
+
```
|
|
123
|
+
- Run: `uv run -q --script $RUN -m gemini-3.8-flash-medium --cwd ~/Downloads "<prompt>"`
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
# Prompting Gemini 3.x (what works, with sources)
|
|
2
|
+
|
|
3
|
+
Researched 2026-10-11. Sources at the bottom. Applies to every Gemini slug in `agy models`
|
|
4
|
+
(3.6/3.7/3.8 Flash, 3.1 Pro). Claude and gpt-oss slugs also do fine with these prompts.
|
|
5
|
+
|
|
6
|
+
## Contents
|
|
7
|
+
1. Core rules
|
|
8
|
+
2. Structure templates
|
|
9
|
+
3. Task-type patterns
|
|
10
|
+
4. Things that backfire
|
|
11
|
+
5. Sources
|
|
12
|
+
|
|
13
|
+
## 1. Core rules
|
|
14
|
+
|
|
15
|
+
- **Direct and short beats clever.** Gemini 3 "responds best to direct, clear instructions" and
|
|
16
|
+
"may over-analyze verbose or overly complex prompt engineering techniques used for older
|
|
17
|
+
models". Drop persuasion, threats, "you are the world's best…", and hand-written
|
|
18
|
+
chain-of-thought scaffolds. Reasoning depth comes from the model tier and effort
|
|
19
|
+
(the `-low/-medium/-high` slug), not from "think step by step".
|
|
20
|
+
- **Say how much output you want.** By default it's terse and direct. To get a long report, a
|
|
21
|
+
friendly tone, or a full file, ask for it explicitly (length, sections, tone).
|
|
22
|
+
- **Role and constraints go first, the question goes last.** Put the role, hard rules and output
|
|
23
|
+
format at the top. With big context (pasted docs, logs, code), put the data in the middle and
|
|
24
|
+
the actual question at the **end**, opening with "Based on the information above…".
|
|
25
|
+
- **One consistent structure.** Use either XML-style tags or Markdown headers, not both. Define
|
|
26
|
+
any ambiguous term ("short" = under 120 words; "recent" = after 2026-01-01).
|
|
27
|
+
- **State the done-condition.** For agentic work, say exactly what counts as finished: the file
|
|
28
|
+
exists, the tests pass, the answer is a JSON object. agy keeps going until it thinks the task
|
|
29
|
+
is done, so a vague done-condition gives you a vague stop.
|
|
30
|
+
- **Persistence for agentic tasks:** "Keep working until the task is completely done. If a tool
|
|
31
|
+
or command fails, read the error and try a different approach." This is useful with
|
|
32
|
+
`--dangerously-skip-permissions` runs.
|
|
33
|
+
- **Ambiguity:** "If something is unclear, make a reasonable assumption, state it in one line,
|
|
34
|
+
and continue." Headless runs can't ask the user, and an `ask_question` call just stalls or
|
|
35
|
+
gets soft-denied.
|
|
36
|
+
- **Leave temperature alone.** (agy doesn't expose it anyway.) Google recommends the default 1.0
|
|
37
|
+
for Gemini 3, because low temperatures cause looping.
|
|
38
|
+
|
|
39
|
+
## 2. Structure templates
|
|
40
|
+
|
|
41
|
+
### Generic task (XML)
|
|
42
|
+
```
|
|
43
|
+
<role>You are a {senior X} helping with {domain}.</role>
|
|
44
|
+
|
|
45
|
+
<task>{one-paragraph statement of the goal, in the user's terms}</task>
|
|
46
|
+
|
|
47
|
+
<context>
|
|
48
|
+
{facts, file paths, constraints the user gave, pasted data}
|
|
49
|
+
</context>
|
|
50
|
+
|
|
51
|
+
<constraints>
|
|
52
|
+
- {hard rule 1}
|
|
53
|
+
- {hard rule 2}
|
|
54
|
+
- Verbosity: {low|medium|high}. Tone: {…}.
|
|
55
|
+
- If something is unclear, assume reasonably and state the assumption.
|
|
56
|
+
</constraints>
|
|
57
|
+
|
|
58
|
+
<output_format>
|
|
59
|
+
{exact shape: "a Markdown table with columns A,B,C", "only the code, one block", "≤5 bullets"}
|
|
60
|
+
</output_format>
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
### Long context (data first, question last)
|
|
64
|
+
```
|
|
65
|
+
<role>…</role>
|
|
66
|
+
<constraints>…</constraints>
|
|
67
|
+
|
|
68
|
+
<document>
|
|
69
|
+
{the long thing}
|
|
70
|
+
</document>
|
|
71
|
+
|
|
72
|
+
Based on the information above, {question}. {output format}.
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
### Agentic coding / file work (run with --cwd and usually --yolo)
|
|
76
|
+
```
|
|
77
|
+
# Goal
|
|
78
|
+
{what must exist or change when you're done}
|
|
79
|
+
|
|
80
|
+
# Context
|
|
81
|
+
- Repo: {path}. Stack: {…}. Relevant files: {…}
|
|
82
|
+
- Conventions: {match existing style, no new deps, …}
|
|
83
|
+
|
|
84
|
+
# Steps you may take
|
|
85
|
+
Read files, run {test/lint commands}, edit files inside this folder only.
|
|
86
|
+
|
|
87
|
+
# Done when
|
|
88
|
+
- {tests command} passes
|
|
89
|
+
- {file} exists and contains {…}
|
|
90
|
+
|
|
91
|
+
# Report
|
|
92
|
+
End with: files changed, commands run and their result, anything left undone.
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
## 3. Task-type patterns
|
|
96
|
+
|
|
97
|
+
- **Research / web questions:** "Search the web. Decompose into sub-questions, answer each from
|
|
98
|
+
sources, cite every claim with its URL, and flag anything you couldn't verify." Use
|
|
99
|
+
flash-high. Ask for dates, because models can mix up versions.
|
|
100
|
+
- **Extraction / classification:** Use `--schema` (agy's `--json-schema`) instead of describing
|
|
101
|
+
JSON in prose. The prompt can then be one line. Use flash-low.
|
|
102
|
+
- **Summaries:** Give the audience and the length ("for a busy CTO, 5 bullets, each ≤20 words")
|
|
103
|
+
and say what to keep (numbers, names, decisions).
|
|
104
|
+
- **Writing / creative:** Give the audience, goal, voice, banned phrases, and one short example
|
|
105
|
+
of the tone. Ask for a self-review pass: "before answering, check for corporate jargon and
|
|
106
|
+
rewrite it".
|
|
107
|
+
- **Code review / debugging:** Give the symptom, the exact error, the repro command, and what
|
|
108
|
+
was already tried. Ask for the root cause first and the fix second.
|
|
109
|
+
- **Image generation (generate_image tool):** Describe the subject, style, composition,
|
|
110
|
+
lighting, aspect ratio and any text to render, in quotes. Then give the save path:
|
|
111
|
+
"save it as ./out/name.png and confirm with ls". It can fail upstream while the run still
|
|
112
|
+
reports SUCCESS, so always check the file.
|
|
113
|
+
- **Planning-before-doing (big tasks):** "First write a short numbered plan, then execute it,
|
|
114
|
+
ticking items off. At the end, verify each Done-when item." This is cheap, and it helps flash.
|
|
115
|
+
|
|
116
|
+
## 4. Things that backfire
|
|
117
|
+
|
|
118
|
+
- **Absolute negatives** like "do not infer" or "never guess". Gemini 3 can follow them too
|
|
119
|
+
literally and refuse basic arithmetic or refuse to connect facts across a document. Say what
|
|
120
|
+
you want instead: "only use facts from the document; if a fact is missing, say 'not in
|
|
121
|
+
document'".
|
|
122
|
+
- **Asking about something it can't access.** Split it: "First check whether X is available;
|
|
123
|
+
if it isn't, say so and stop."
|
|
124
|
+
- **Over-long prompts on flash-low.** Low effort plus a huge rubric gives shallow compliance.
|
|
125
|
+
Either shorten the prompt or raise the effort.
|
|
126
|
+
- **Mixing several unrelated jobs in one `-p`.** Run them as separate calls, or as a `--chat`
|
|
127
|
+
session.
|
|
128
|
+
|
|
129
|
+
## 5. Sources
|
|
130
|
+
- Google, Gemini 3 developer guide: https://ai.google.dev/gemini-api/docs/gemini-3
|
|
131
|
+
- Google Cloud, Gemini 3 prompting guide: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/start/gemini-3-prompting-guide
|
|
132
|
+
- Phil Schmid, Gemini 3 prompting best practices: https://www.philschmid.de/gemini-3-prompt-practices
|
|
133
|
+
- Antigravity CLI headless docs: https://antigravity.google/docs/cli/headless/
|
|
134
|
+
- Flash vs Pro: https://benchlm.ai/compare/gemini-3-1-pro-vs-gemini-3-8-flash , https://myclaw.ai/blog/gemini-3-8-flash-vs-3-1-pro
|