Skip to content

Commit af4918b

Browse files
zloeberzloeber
authored
Merge pull request #44 from zloeber/zloeber/skills
Add skills installer, GitLab bundle extension, and capability catalog
2 parents d80f62b + 9b5088c commit af4918b

41 files changed

Lines changed: 3238 additions & 313 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.cursor/skills/secretzero-agent-adopt/SKILL.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
---
2+
name: secretzero-agent-adopt
3+
description: |
4+
Use for agent runtime integration: discover Hermes/OpenClaw installs,
5+
bootstrap SecretZero environments with `secretzero agent list` / `agent adopt`,
6+
lockfile preseed, and restore loops. Inherits absolute rule from
7+
`skills/secretzero/SKILL.md` (SecretZero only; never secrets in context).
8+
---
9+
10+
# SecretZero Agent Adopt Skill
11+
12+
Use when an agent runtime (Hermes, OpenClaw, or future claw-like installs) needs a
13+
SecretZero environment, disaster recovery, or GitOps capture of **present** credentials.
14+
15+
Pair with `skills/secretzero-agent/SKILL.md` (sync vectors) and
16+
`skills/secretzero-handle/SKILL.md` (spill-safe mode).
17+
18+
## Cold-start (remote repo)
19+
20+
1. Read repository `README.md` HTML comment `agent-entrypoint` block.
21+
2. Install CLI: `uv tool install -U "secretzero[all]"`.
22+
3. Set spill-safe mode when automating: `export SZ_AGENT_MODE=true`.
23+
4. Discover installs (read-only):
24+
25+
```bash
26+
secretzero agent list --format json
27+
```
28+
29+
5. Plan adopt (no writes):
30+
31+
```bash
32+
secretzero agent adopt --dry-run --format json
33+
```
34+
35+
6. Bootstrap environment (default output = agent home):
36+
37+
```bash
38+
secretzero agent adopt --format json
39+
```
40+
41+
GitOps capture into the workspace:
42+
43+
```bash
44+
secretzero agent adopt --target hermes --source-dir ~/.hermes --output-dir ./agents/hermes --template
45+
```
46+
47+
## Command map
48+
49+
| Command | Purpose |
50+
|---------|---------|
51+
| `secretzero agent list` | Detect Hermes/OpenClaw installs + existing SecretZero envs |
52+
| `secretzero agent adopt` | Write `Secretfile.yml` (present credentials only) |
53+
| `secretzero agent backup` | Alias of `adopt` — **not** `secretzero backup create` |
54+
55+
## Safety contract
56+
57+
- stdout/JSON is **metadata only** (names, paths, counts).
58+
- Generated manifests use `default: null` — never copy live values into YAML.
59+
- Use `--preseed-lockfile` to hash present values without printing them.
60+
- For missing secrets after restore: `secretzero agent sync --web`.
61+
- Encrypted DR payloads: `secretzero backup create --encrypted` **after** adopt/sync.
62+
63+
## Standard restore loop
64+
65+
```bash
66+
secretzero agent list --format json
67+
secretzero agent adopt --target hermes --preseed-lockfile --format json
68+
secretzero validate -f ~/.hermes/Secretfile.yml
69+
secretzero agent sync --json -f ~/.hermes/Secretfile.yml
70+
secretzero sync -f ~/.hermes/Secretfile.yml
71+
```
72+
73+
Repeat `agent sync` until `pending_secrets` is empty.
74+
75+
## Autodetect rules
76+
77+
- `--target` omitted → try **Hermes**, then **OpenClaw**.
78+
- `--source-dir` omitted → default install paths (`~/.hermes`, `~/.openclaw`, env overrides).
79+
- If target or source cannot be resolved → **no files written**; JSON includes `reason`.
80+
81+
## Definition of done
82+
83+
- SecretZero env exists at chosen `output-dir`.
84+
- Lockfile preseeded when requested.
85+
- `agent sync` / `sync` complete with no pending manual secrets.
86+
- No secret values appeared in agent context or logs.

‎.cursor/skills/secretzero-agent/SKILL.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
---
2+
name: secretzero-agent
3+
description: |
4+
Use for agentic and operational SecretZero workflows including unified
5+
`agent sync`, CLI/API parity, secure human-in-the-loop vectors, and
6+
automation-safe run loops.
7+
---
8+
9+
# SecretZero Agent Skill
10+
11+
Use this skill when running SecretZero in agentic workflows (manual-assisted, web-assisted, or fully automated), or when guiding users through runtime usage scenarios.
12+
13+
## Install / Verify
14+
15+
Preferred install:
16+
17+
```bash
18+
uv tool install -U "secretzero[all]"
19+
```
20+
21+
Lean or provider-specific installs:
22+
23+
```bash
24+
uv tool install -U secretzero
25+
uv tool install -U "secretzero[aws]"
26+
uv tool install -U "secretzero[azure]"
27+
```
28+
29+
Alternative:
30+
31+
```bash
32+
pip install -U "secretzero[all]"
33+
```
34+
35+
Verify CLI:
36+
37+
```bash
38+
secretzero --help
39+
secretzero agent sync --help
40+
```
41+
42+
## Core Agent Contract
43+
44+
**Absolute rule:** `skills/secretzero/SKILL.md` — never consume secrets in context; use SecretZero for all handling (`agent sync`, `--web`, validate, status). Never request, receive, or print plaintext secret values.
45+
- Prefer JSON output for machine handling.
46+
- When running in automation or spill-sensitive hosts, set **`SZ_AGENT_MODE=true`** so the CLI blocks or redacts commands that would dump secret-bearing config (see `skills/secretzero-handle/SKILL.md`).
47+
- Use the unified entrypoint:
48+
49+
```bash
50+
secretzero agent sync --json [--web] [--dry-run] [--verbose]
51+
```
52+
53+
## Three Usage Vectors
54+
55+
1. **Human-instructed (Vector 1)**
56+
- Run `secretzero agent sync --json`.
57+
- Relay `pending_secrets[].summary` and ordered `steps` exactly.
58+
- Re-run until clean.
59+
60+
2. **Secure local web capture (Vector 2)**
61+
- Run `secretzero agent sync --web` (add `--json` only when you also need structured stdout after the run finishes).
62+
- **Do not block the whole agent session on the foreground TTY if your environment allows it:** start the command in a **background terminal** (or equivalent job control) on the operator’s machine so the process can stay alive until the form is submitted, and **capture stdout** if you need to quote the URL line back reliably.
63+
- When the CLI prints the localhost URL, **relay the complete URL verbatim** to the user (scheme, host, port, and path — no truncation). Vector 2 binds to `127.0.0.1`; the printed URL is the handoff surface (this is **not** the same as `secretzero web`, which uses a separate **bootstrap token** for the network dashboard — if you use that command, pass through its **full login URL including the token** per that command’s output).
64+
- Remind the operator **not to paste secret values into chat**; only the URL and UI instructions belong in the agent thread.
65+
- Remind the operator to **submit the form once** and close the browser tab when done: the CLI helper **stops the temporary localhost server** after a successful submit; if they walk away, **Ctrl+C** (or waiting for timeout) ends the wait.
66+
- **API Vector 2:** `POST /agent/sync` with `web: true` returns `web_url` and `web_session_id` — give the operator the **exact `web_url`**, poll `GET /agent/sync/web/{web_session_id}` until `done`, and treat the session id as sensitive correlation data. The API process may keep that localhost port open until restart; do not forward `web_url` beyond the trusted operator.
67+
- Poll/re-run `agent sync --json` until `pending_secrets` clears.
68+
69+
3. **Fully automated (Vector 3)**
70+
- Ensure provider auth is available (and optionally `SZ_AGENT=true`).
71+
- Run `secretzero agent sync --json`.
72+
- Handle `failed_secrets` with manifest fixes and retry.
73+
74+
## Agent runtime integration
75+
76+
When bootstrapping or restoring Hermes/OpenClaw installs:
77+
78+
```bash
79+
secretzero agent list --format json
80+
secretzero agent adopt --dry-run --format json
81+
secretzero agent adopt --preseed-lockfile --format json
82+
```
83+
84+
Load `skills/secretzero-agent-adopt/SKILL.md` for the full adopt/restore playbook. `agent backup` is an alias of `agent adopt` (not `secretzero backup create`).
85+
86+
## Standard Agent Loop
87+
88+
1. Run `secretzero agent sync --json` first; escalate to `--web` when you need the localhost form (see Vector 2 handoff above).
89+
2. Parse status and `pending_secrets`/`failed_secrets`.
90+
3. Execute the appropriate vector behavior.
91+
4. Re-run command until both arrays are empty.
92+
5. Continue downstream only after clean completion.
93+
94+
## API Parity
95+
96+
Use API when running remote orchestration:
97+
98+
- `POST /agent/sync` with `{ dry_run, web, lockfile?, sz_agent? }`
99+
- For Vector 2 polling: `GET /agent/sync/web/{session_id}`
100+
101+
Treat API payload semantics the same as CLI semantics.
102+
103+
## Operational Playbooks
104+
105+
- **Agent adopt (Hermes/OpenClaw):** see `skills/secretzero-agent-adopt/SKILL.md` — `agent list` → `agent adopt` → `agent sync`
106+
- **Bootstrap:** `validate` -> `init --install` -> `test` -> `agent sync --json`
107+
- **Preflight:** `secretzero sync --dry-run` before mutating runs
108+
- **Maintenance:** pair with `secretzero rotate`, `secretzero drift`, `secretzero status --format json`
109+
110+
## Common Failure Handling
111+
112+
- Missing extras/provider dependencies -> run install/`secretzero init --install`
113+
- Auth missing/expired -> fix provider auth, re-run `secretzero test`
114+
- Manual-seeded secret lacks instructions -> add `agent_instructions`, retry
115+
- Variable interpolation issues -> check vars and `--var-file` usage
116+
117+
## Definition of Done
118+
119+
- Secret bootstrap/sync flow reaches no pending or failed secrets.
120+
- Workflow used secure vector handling with no secret leakage.
121+
- CLI/API behavior stays consistent for the selected scenario.

0 commit comments

Comments
 (0)