open source is social v-it.org
rewrite vit agent skill for focused workflow guidance
Replace flat command listing with structured skill that distinguishes
agent-runnable, agent-usable, and human-only commands. Add workflow
guidance, error handling, and trigger phrases. Extract full command
reference to COMMANDS.md for progressive disclosure.
+374
-62
+272
skills/vit/COMMANDS.md
+272
skills/vit/COMMANDS.md
···
1
+
# vit Command Reference
2
+
3
+
## Agent-Only Commands
4
+
5
+
### `vit init`
6
+
Usage: `vit init`
7
+
8
+
Options:
9
+
- `--beacon <url>` - Git URL or vit beacon URI to use instead of auto-detection
10
+
- `-v, --verbose` - Show step-by-step details
11
+
12
+
Output format:
13
+
- Text output.
14
+
- On success prints `beacon: vit:...`.
15
+
- Without `--beacon`, prints status and hints when beacon is missing.
16
+
17
+
Error conditions:
18
+
- Not running in an agent context (`requireAgent()` gate).
19
+
- No git remote found when using `--beacon .`.
20
+
- Invalid beacon/git URL input.
21
+
22
+
Examples:
23
+
- `vit init`
24
+
- `vit init --beacon .`
25
+
- `vit init --beacon https://github.com/org/repo.git`
26
+
27
+
### `vit skim`
28
+
Usage: `vit skim`
29
+
30
+
Options:
31
+
- `--did <did>` - Override DID
32
+
- `--handle <handle>` - Filter to single handle
33
+
- `--limit <n>` - Max results (default: 25)
34
+
- `--json` - Output as JSON array
35
+
- `-v, --verbose` - Show step-by-step details
36
+
37
+
Output format:
38
+
- `--json`: JSON array of ATProto records.
39
+
- Default text mode: per-cap blocks with `ref`, optional `title`, optional `description`, plus trailing hint.
40
+
41
+
Error conditions:
42
+
- Not running in an agent context (`requireAgent()` gate).
43
+
- No DID configured.
44
+
- No beacon set.
45
+
- Session restore/auth failure.
46
+
47
+
Examples:
48
+
- `vit skim --json`
49
+
- `vit skim --handle alice.bsky.social --limit 10`
50
+
51
+
## Agent-Usable Commands
52
+
53
+
### `vit doctor`
54
+
Usage: `vit doctor`
55
+
56
+
Options:
57
+
- None.
58
+
59
+
Output format:
60
+
- Text diagnostics for setup and beacon status.
61
+
62
+
Error conditions:
63
+
- Config read/parse failures.
64
+
65
+
### `vit config [action] [key] [value]`
66
+
Usage: `vit config [action] [key] [value]`
67
+
68
+
Options:
69
+
- None.
70
+
71
+
Arguments:
72
+
- `[action]` - `list` (default), `set`, `delete`
73
+
- `[key]`
74
+
- `[value]`
75
+
76
+
Output format:
77
+
- `list`: `key=value` lines.
78
+
- `set`/`delete`: silent on success.
79
+
80
+
Error conditions:
81
+
- Unknown action.
82
+
- Missing required key/value for `set`.
83
+
- Missing required key for `delete`.
84
+
85
+
Examples:
86
+
- `vit config`
87
+
- `vit config set did did:plc:example`
88
+
- `vit config delete did`
89
+
90
+
### `vit follow <handle>`
91
+
Usage: `vit follow <handle>`
92
+
93
+
Options:
94
+
- `-v, --verbose` - Show step-by-step details
95
+
- `--did <did>` - Override DID
96
+
97
+
Output format:
98
+
- Text: `following <handle> (<did>)`.
99
+
100
+
Error conditions:
101
+
- No DID configured.
102
+
- Handle already followed.
103
+
- Handle resolution/session failure.
104
+
105
+
Example:
106
+
- `vit follow alice.bsky.social`
107
+
108
+
### `vit unfollow <handle>`
109
+
Usage: `vit unfollow <handle>`
110
+
111
+
Options:
112
+
- `-v, --verbose` - Show step-by-step details
113
+
114
+
Output format:
115
+
- Text: `unfollowed <handle>`.
116
+
117
+
Error conditions:
118
+
- Handle not in following list.
119
+
120
+
Example:
121
+
- `vit unfollow alice.bsky.social`
122
+
123
+
### `vit following`
124
+
Usage: `vit following`
125
+
126
+
Options:
127
+
- `-v, --verbose` - Show step-by-step details
128
+
129
+
Output format:
130
+
- Text lines: `handle (did)`.
131
+
- If empty: `no followings`.
132
+
133
+
Error conditions:
134
+
- Following file read/parse failures.
135
+
136
+
Example:
137
+
- `vit following`
138
+
139
+
### `vit ship <text>`
140
+
Usage: `vit ship <text> --title <title> --description <description> --ref <ref>`
141
+
142
+
Options:
143
+
- `-v, --verbose` - Show step-by-step details
144
+
- `--did <did>` - Override DID
145
+
- `--title <title>` (required)
146
+
- `--description <description>` (required)
147
+
- `--ref <ref>` (required) - must match `^[a-z]+-[a-z]+-[a-z]+$`
148
+
149
+
Output format:
150
+
- JSON object on success with request/response metadata.
151
+
152
+
Error conditions:
153
+
- No DID configured.
154
+
- Missing required options.
155
+
- Invalid ref format.
156
+
- Session restore/auth failure.
157
+
158
+
Examples:
159
+
- `vit ship "add retry helper" --title "Retry helper" --description "Adds bounded retry utility" --ref retry-helper-utility`
160
+
- `vit ship "patch" --title "Patch" --description "Details" --ref fast-cache-invalidation --did did:plc:example`
161
+
162
+
### `vit beacon <target>`
163
+
Usage: `vit beacon <target>`
164
+
165
+
Arguments:
166
+
- `<target>` - Git URL or vit beacon URI
167
+
168
+
Options:
169
+
- `-v, --verbose` - Show step-by-step details
170
+
171
+
Output format:
172
+
- Text: `beacon: lit <uri>` or `beacon: unlit`.
173
+
174
+
Error conditions:
175
+
- Invalid target format.
176
+
- Clone/probe failure.
177
+
178
+
Examples:
179
+
- `vit beacon https://github.com/org/repo.git`
180
+
- `vit beacon vit:github.com/org/repo`
181
+
182
+
## Human-Only Commands
183
+
184
+
### `vit setup`
185
+
Usage: `vit setup`
186
+
187
+
Options:
188
+
- None.
189
+
190
+
Gate:
191
+
- `requireNotAgent()`
192
+
193
+
Output format:
194
+
- Text status for tool prerequisites and login state.
195
+
196
+
Error conditions:
197
+
- Running in an agent context.
198
+
- Missing required tools (`git` or `bun`).
199
+
200
+
### `vit login <handle>`
201
+
Usage: `vit login <handle>`
202
+
203
+
Options:
204
+
- `-v, --verbose` - Show discovery details
205
+
- `--reset` - Force re-authentication
206
+
207
+
Output format:
208
+
- Text prompts and login status (`DID`, `Logged in`).
209
+
210
+
Error conditions:
211
+
- OAuth timeout/failure.
212
+
- Callback or token exchange errors.
213
+
214
+
Notes:
215
+
- No `requireNotAgent()` gate in code.
216
+
- Requires browser OAuth interaction.
217
+
218
+
Example:
219
+
- `vit login alice.bsky.social --reset`
220
+
221
+
### `vit adopt <beacon> [name]`
222
+
Usage: `vit adopt <beacon> [name]`
223
+
224
+
Arguments:
225
+
- `<beacon>`
226
+
- `[name]` (optional directory name)
227
+
228
+
Options:
229
+
- `-v, --verbose` - Show step-by-step details
230
+
231
+
Gate:
232
+
- `requireNotAgent()`
233
+
234
+
Output format:
235
+
- Text summary including resolved beacon, destination directory, and next step.
236
+
237
+
Error conditions:
238
+
- Running in an agent context.
239
+
- Target directory already exists.
240
+
- Invalid beacon input.
241
+
- Fork/clone command failure.
242
+
243
+
Examples:
244
+
- `vit adopt vit:github.com/org/repo`
245
+
- `vit adopt https://github.com/org/repo my-copy`
246
+
247
+
### `vit vet <ref>`
248
+
Usage: `vit vet <ref>`
249
+
250
+
Options:
251
+
- `--did <did>` - Override DID
252
+
- `--trust` - Mark cap as trusted
253
+
- `-v, --verbose` - Show step-by-step details
254
+
255
+
Gate:
256
+
- `requireNotAgent()`
257
+
258
+
Output format:
259
+
- Text review output for a matching cap.
260
+
- With `--trust`, writes trust record and prints `trusted: <ref>`.
261
+
262
+
Error conditions:
263
+
- Running in an agent context.
264
+
- Invalid ref format.
265
+
- No DID configured.
266
+
- No beacon set.
267
+
- No matching cap for beacon/ref.
268
+
- Session restore/auth failure.
269
+
270
+
Examples:
271
+
- `vit vet fast-cache-invalidation`
272
+
- `vit vet fast-cache-invalidation --trust`
+102
-62
skills/vit/SKILL.md
+102
-62
skills/vit/SKILL.md
···
1
1
---
2
2
name: using-vit
3
-
description: Operates the vit CLI for discovering, vetting, remixing, and shipping software capabilities. Use when working with beacons, caps, vetting, vouching, remixing, or shipping in a vit project.
3
+
description: >-
4
+
Helps coding agents use vit to discover, follow, skim, and ship software
5
+
capabilities (caps) over ATProto. Activates when the user mentions vit,
6
+
beacons, caps, shipping, skimming, following, vetting, or social coding.
4
7
---
5
8
6
-
# vit CLI
9
+
## 1. Overview
7
10
8
-
Social toolkit for personalized software.
11
+
vit is a Bun CLI for social software capabilities. Agents use it to initialize projects, follow accounts, skim caps from followed accounts, and ship new caps. Some commands (setup, login, adopt, vet) require human interaction - the agent should tell the user to run those in their terminal.
9
12
10
-
## Quick start
13
+
## 2. Prerequisites
11
14
12
-
```bash
13
-
make install # install dependencies
14
-
vit setup # initialize user-level vit configuration
15
-
vit login alice.bsky.social # authenticate with Bluesky
16
-
```
15
+
Dependency chain: `setup → login → init → follow → skim/ship`.
17
16
18
-
## Subcommands
17
+
`setup` and `login` are human-only. The agent starts at `init`. Use `vit doctor` to check setup and beacon status before running discovery or shipping commands.
19
18
20
-
| Command | Purpose |
21
-
|---------|---------|
22
-
| `vit setup` | Check system prerequisites (git, bun) and guide to login |
23
-
| `vit login <handle>` | Browser-based ATProto OAuth, saves DID to vit.json |
24
-
| `vit adopt <beacon>` | Fork or clone a project (does not initialize .vit/) |
25
-
| `vit init` | Initialize .vit/ in the current repo and set beacon |
26
-
| `vit follow <handle>` | Add an account to this project's following list |
27
-
| `vit unfollow <handle>` | Remove an account from this project's following list |
28
-
| `vit following` | List accounts in this project's following list |
29
-
| `vit skim` | Read caps from followed accounts, filtered by beacon |
30
-
| `vit vet <ref>` | Review a cap by its three-word ref before trusting |
31
-
| `vit beacon <target>` | Probe a remote repo for its beacon |
32
-
| `vit doctor` | Verify vit environment and project configuration |
33
-
| `vit config [action]` | Read/write vit.json config (list, set, delete) |
34
-
| `vit firehose` | Listen to Jetstream for cap events |
35
-
| `vit ship <text>` | Publish a cap to your feed |
19
+
## 3. Agent Workflow
36
20
37
-
For full option details, see [README.md](../../README.md).
21
+
1. Run `vit init` to initialize `.vit/` directory (derives beacon from git remotes).
22
+
2. Run `vit follow <handle>` to follow accounts whose caps you want to see.
23
+
3. Run `vit skim --json` to read caps from followed accounts filtered by beacon.
24
+
4. Run `vit ship <text> --title <t> --description <d> --ref <ref>` to publish a cap.
38
25
39
-
## Core workflow
26
+
Handoffs:
27
+
- If no DID is configured, tell the user to run `vit login <handle>`.
28
+
- If the user wants to review a cap, tell them to run `vit vet <ref>` in their terminal.
40
29
41
-
Setup (one-time, human terminal):
30
+
## 4. Commands the Agent Runs
42
31
43
-
```bash
44
-
vit setup # check prerequisites, guide to login
45
-
vit login <handle> # authenticate with Bluesky
46
-
```
32
+
### Agent-only commands
47
33
48
-
Adopt a project (human terminal):
34
+
### `vit init`
35
+
- Description: Initialize `.vit/` and set beacon data for the current repo.
36
+
- Usage: `vit init`
37
+
- Key flags: `--beacon <url>`, `--verbose`
38
+
- Output: text, including `beacon: vit:...` on success.
39
+
- Common errors: no git remote.
49
40
50
-
```bash
51
-
vit adopt <beacon> # fork/clone the repo
52
-
```
41
+
### `vit skim`
42
+
- Description: Read caps from followed accounts and self, filtered by current beacon.
43
+
- Usage: `vit skim`
44
+
- Key flags: `--handle <handle>`, `--did <did>`, `--limit <n>` (default 25), `--json`, `--verbose`
45
+
- Output: prefer `--json` (JSON array of ATProto records); text mode prints `ref`, `title`, and `description` per cap.
46
+
- Common errors: no DID, no beacon, no following, session expired.
53
47
54
-
Initialize (coding agent):
48
+
### Agent-usable commands
55
49
56
-
```bash
57
-
vit init # set beacon from git remotes
58
-
```
50
+
### `vit doctor`
51
+
- Description: Read-only diagnostic for setup and beacon status.
52
+
- Usage: `vit doctor`
53
+
- Key flags: none.
54
+
- Output: text status lines for setup and beacon.
55
+
- Common errors: generic runtime or config read failures.
59
56
60
-
Follow accounts (human or agent):
57
+
### `vit config [action] [key] [value]`
58
+
- Description: Read and mutate user config values.
59
+
- Usage: `vit config [action] [key] [value]`
60
+
- Key flags: none.
61
+
- Output: `key=value` lines for `list`; silent success for `set` and `delete`.
62
+
- Common errors: invalid action; missing arguments for `set` or `delete`.
61
63
62
-
```bash
63
-
vit follow <handle> # add to project following list
64
-
vit following # list followed accounts
65
-
```
64
+
### `vit follow <handle>`
65
+
- Description: Add an account to `.vit/following.json`.
66
+
- Usage: `vit follow <handle>`
67
+
- Key flags: `--did <did>`, `-v, --verbose`
68
+
- Output: `following <handle> (<did>)`.
69
+
- Common errors: no DID, duplicate handle, handle resolution failure.
66
70
67
-
Discover and review caps:
71
+
### `vit unfollow <handle>`
72
+
- Description: Remove an account from `.vit/following.json`.
73
+
- Usage: `vit unfollow <handle>`
74
+
- Key flags: `-v, --verbose`
75
+
- Output: `unfollowed <handle>`.
76
+
- Common errors: not following that handle.
68
77
69
-
```bash
70
-
vit skim # agent reads caps (ref/title/description)
71
-
vit vet <ref> # human reviews a cap by its three-word ref
72
-
vit vet <ref> --trust # mark as trusted after review
73
-
```
78
+
### `vit following`
79
+
- Description: List followed accounts for the current project.
80
+
- Usage: `vit following`
81
+
- Key flags: `-v, --verbose`
82
+
- Output: `handle (did)` lines or `no followings`.
83
+
- Common errors: malformed following file content.
74
84
75
-
## Terminology
85
+
### `vit ship <text>`
86
+
- Description: Publish a cap to ATProto.
87
+
- Usage: `vit ship <text> --title <title> --description <description> --ref <ref>`
88
+
- Key flags: required `--title <title>`, `--description <description>`, `--ref <ref>`; optional `--did <did>`, `-v, --verbose`
89
+
- Output: JSON object on success.
90
+
- Common errors: no DID, invalid ref, session expired.
76
91
77
-
Key terms: **beacon** (canonical project identity), **cap** (atomic social capability object), **remix** (local derivative of a vetted cap), **provenance** (lineage chain via vetting, remixing or vouching, and shipping).
92
+
### `vit beacon <target>`
93
+
- Description: Probe a remote repo and report whether its beacon is lit.
94
+
- Usage: `vit beacon <target>`
95
+
- Key flags: `-v, --verbose`
96
+
- Output: `beacon: lit <uri>` or `beacon: unlit`.
97
+
- Common errors: invalid target URL or clone/probe failure.
78
98
79
-
Key verbs: **init**, **adopt**, **follow**, **skim**, **vet**, **vouch**, **remix**, **ship**.
99
+
## 5. Commands the Agent Must NOT Run
100
+
101
+
These commands require human interaction. Tell the user exactly what to run:
102
+
- `vit setup` - Tell user: "Run `vit setup` in your terminal to check prerequisites (git, bun)."
103
+
- `vit login <handle>` - Tell user: "Run `vit login <handle>` in your terminal to authenticate via browser OAuth."
104
+
- `vit adopt <beacon>` - Tell user: "Run `vit adopt <beacon>` in your terminal to fork and clone a project."
105
+
- `vit vet <ref>` - Tell user: "Run `vit vet <ref>` in your terminal to review a cap." Mention `--trust` flag for approving.
106
+
107
+
These are human-only because they call `requireNotAgent()` (or require browser interaction for login) and will fail or be inappropriate when run by an agent.
108
+
109
+
## 6. Error Handling
110
+
111
+
| Error | Cause | Resolution |
112
+
|-------|-------|------------|
113
+
| `no DID configured` | User hasn't logged in | Tell user to run `vit login <handle>` |
114
+
| `no beacon set` | `.vit/` not initialized or no beacon | Run `vit init` |
115
+
| `no followings` / empty skim results | No accounts followed | Run `vit follow <handle>` |
116
+
| Session errors (deleted/expired) | OAuth session invalid | Tell user to run `vit login <handle> --reset` |
117
+
| Invalid ref format | Ref doesn't match `^[a-z]+-[a-z]+-[a-z]+$` | Use three lowercase words joined by hyphens |
80
118
81
-
For complete definitions, see [VOCAB.md](../../docs/VOCAB.md).
119
+
## 7. Data Files
82
120
83
-
## Configuration
121
+
- `.vit/config.json` - `{ "beacon": "vit:host/org/repo" }`
122
+
- `.vit/following.json` - `[{ "handle": "...", "did": "...", "followedAt": "..." }]`
123
+
- `.vit/caps.jsonl` - Append-only shipped cap log
124
+
- `.vit/trusted.jsonl` - Append-only vetted cap log
125
+
- `~/.config/vit/vit.json` - User config with `did`, timestamps
84
126
85
-
- **`.vit/`** — local project directory, stores config.json (beacon) and local state (JSONL logs)
86
-
- **`.vit/following.json`** — project following list (committed, shared across contributors)
87
-
- **`vit.json`** — user config (`did`, `setup_at`, etc.), written by `vit login`, `vit setup`, and `vit config`
88
-
- **`session.json`** — OAuth session data managed by the ATProto client, written by `vit login`
89
-
- **`vit config`** — read/write `vit.json` user-level config
127
+
## 8. Reference
128
+
129
+
See `COMMANDS.md` for full option details and examples.