vsync v0.14.0 — Agent skill spec (onboarding-first)

Status: design · supersedes the deleted skills/vsync-skill/ · target deliverable: a single skill file (or thin skill bundle) that helps an LLM-driven assistant onboard a user to vsync without reimplementing the CLI's logic.

One theme: the skill exists to shorten the path from "I just heard about vsync" to "first push lands and my teammate's first pull works." Everything else — sync-target nuance, rotation, audit-log interpretation — is documented on the website and lives in vsync --help. The skill should NOT try to be a second source of truth.

The old skill (deleted in this commit) was 7.6 KB of prescriptive prose plus a references/ directory of recipe docs. It treated the assistant as an apprentice that needed to internalise every CLI flag and every footgun. That's the wrong shape — assistants are good at running the engine; they should not be carrying a manual.

For prior context, see v0.10-runtime-token-cli.md, v0.13-profiles-init-status.md, and the live site at https://muthuishere.github.io/vsync/.

---

1. Purpose — what the skill is for

The skill is a trigger + workflow + reference bundle that an LLM (Claude / GPT / etc.) loads when the user says something vsync-shaped. Its only job is to:

1. Recognise the moment. The user is about to start, stuck mid-flow, or onboarding a teammate.
2. Pick a workflow. First-time setup, teammate onboarding, daily push/pull, fanout, rotation, "something broke."
3. Run the canonical commands. Show the command, confirm, exec. The CLI is the engine.
4. Link to deeper material. Point at the docs site or vsync <sub> --help when the user needs more than the workflow covers.

It does NOT:

• Reimplement init / push / pull logic
• Enumerate every CLI flag in prose
• Maintain prescriptive "never do X" lists longer than five items
• Track internal session state the CLI doesn't already track
• Try to be a manual

If the user wants the full manual, that's vsync <sub> --help and the docs site. The skill's job is shorter than that.

2. Onboarding-first design principle

The single most-common assist a user needs is getting from zero to a working vault on day one. The skill is shaped around that path:

1. User mentions "I want to share secrets with my team" → skill detects → triages.
2. Skill asks the two questions that matter: which S3 backend, and is the user the owner or a teammate.
3. Skill walks the owner through profile add → init → push → export. Or the teammate through import → pull → use.
4. Done in 5 minutes; user has a working vault.

Every other workflow (rotation, fanout, audit) is secondary — the skill should know they exist and gesture at them, not lead with them.

3. Skill metadata — the YAML frontmatter

A skill is one Markdown file with YAML frontmatter. The frontmatter MUST be tight:

---
name: vsync
description: >
  Help users share environment secrets across a team with `vsync` —
  encrypted vault on any S3-compatible bucket (AWS / Hetzner / R2 / MinIO /
  B2), per-machine AES key in the OS keychain, one-passphrase teammate
  onboarding via `.share` files, append-only audit log, fanout to
  GitHub / GCP / AWS / Azure / HashiCorp Vault, and runtime libraries
  for Python / TypeScript / Go / Java that read the vault at boot.

  Trigger on: "share secrets with my team", "encrypt my .env",
  "onboard teammate with credentials", "stop pasting secrets in Slack",
  "vault for env files", "sync secrets across machines", "rotate
  team secret key", "fanout secrets to GitHub Actions", or any
  mention of `vsync`, `@muthuishere/vsync`, or `vsync-s3-client`.

  Install via `bun install -g @muthuishere/vsync` (or `npm install -g`).
  Min runtime: Bun ≥ 1.2.21.

  Docs: https://muthuishere.github.io/vsync/
license: MIT
---

• name — short. The CLI name itself works.
• description — three paragraphs at most: what the skill does, what to trigger on, and where deeper docs live. Don't pad with feature flags or version history; that goes on the website.
• license — present so downstream skill registries can index it.

The old skill's frontmatter had a 25-line trigger list that read like SEO. Don't do that — modern LLMs trigger on semantic intent, not exhaustive phrase enumeration. Six to ten representative phrases is plenty.

4. Body — three sections, in this order

The Markdown body has exactly three top-level sections:

4.1 What vsync is, in one paragraph

# vsync

`vsync` is a CLI that turns a folder of secrets (`.env` files, JSON keys,
TLS certs) into an encrypted vault on any S3-compatible bucket. A
per-machine AES key lives in the OS keychain; the bucket alone is
useless without it. Teammates onboard via a one-shot `.share` file
delivered out of band. Apps that need the vault at runtime read it via
the matching Python / TypeScript / Go / Java library. Full docs:
https://muthuishere.github.io/vsync/

That's it. Don't repeat the marketing on the website.

4.2 The five workflows the skill knows

Each workflow is 3–8 commands and one decision point. The skill picks one based on what the user said and walks them through it. Workflows are NOT prescriptive policy documents — they are checklists.

The five workflows:

1. Owner first-time setup — vsync profile add → vsync init <env> --profile=… → drop secrets into infra/vault/<env>/ → vsync push <env>. Decision point: which S3 backend.
2. Teammate onboarding — vsync import <env> <share-file> → vsync pull <env> → vsync use <env>. Decision point: where the .share file landed locally.
3. Daily push / pull — vsync push <env> (after editing) or vsync pull <env> (before working). Decision point: none — single command each.
4. Production runtime — vsync runtime-token --env=prod → paste the blob into the deployment platform's secret store → app uses the runtime library to read it. Decision point: which platform (Vercel / ECS / Cloud Run / Azure / VPS).
5. Something broke — vsync status → identify orphan / drift → recover. Decision point: what status actually showed.

Each workflow is presented as the command sequence first, prose second. The assistant should show the commands, name the decision point, ask the question, and execute.

4.3 Five rules — minimal, not maximal

The skill needs a small set of inviolable rules. Five is the budget. The deleted skill had eight to twelve depending on how you counted. Most were CLI flag warnings that belong in vsync sync --help, not in a behavioural contract for the assistant.

The five rules:

1. Don't auto-install. If vsync isn't on PATH, surface the install command and stop. Never run npm install -g without explicit user consent.
2. .share file and passphrase travel on different channels. Always say this when walking through vsync export. Same channel defeats the threat model.
3. Never paste a passphrase or share-file content into a chat transcript. The skill operates on filenames and prompts the user to type secrets locally.
4. Two halves required. A (repo, env) pair has a config file + a keychain key. When the user reports an error, identify which half is missing before suggesting fixes. The CLI's --help text and vsync status are the diagnostic tools — don't reinvent them.
5. No per-user revoke. vsync is small-team-shared-key. Offboarding = rotate + re-export. If the user asks for per-user ACLs, explain the model honestly and point at the docs.

Five rules. No more.

5. References — what NOT to include

The deleted skill shipped six references/*.md files (recipes, sync-flags, taskfile-template, team-setup, setup-scripts, mental-model). That's a maintenance liability and duplicates vsync --help + the docs site.

The new skill's references directory should be at most three files, each one screen long:

File	Contents	When the assistant loads it
references/workflows.md	The five workflows from §4.2 in detail (~150 lines total).	After triaging the user's intent.
references/troubleshooting.md	The most-common five errors and how vsync status diagnoses each. (~80 lines.)	When the user reports a failure.
references/decision-points.md	The choice matrix for §4 workflows: which S3 backend, owner vs teammate, single-env vs multi-env. (~50 lines.)	Before the first command runs.

Anything beyond those three is a sign the skill is trying to be a manual. The website at https://muthuishere.github.io/vsync/ is the manual.

6. Triggers — broad but bounded

The skill should activate on semantic intent, not on a phrase whitelist. Six to ten representative phrases in the description are enough; an LLM with reasonable embedding-grade triggering will generalise.

Acceptable triggers:

• "Share secrets with my team"
• "Encrypt my .env"
• "Onboard teammate with credentials"
• "Stop pasting secrets in Slack"
• "Vault for environment files"
• Any direct mention of vsync, @muthuishere/vsync, vsync-s3-client

Unacceptable (over-eager) triggers:

• "I need secrets" → too broad; could be password manager
• "How do I store config?" → too broad
• "AES-256-GCM" → user is asking about crypto, not about vsync

The frontmatter's description should set both bounds explicitly.

7. Pattern: how the assistant should run

When the skill is loaded and triggered, the assistant follows this loop:

1. One-line greeting that names the workflow it picked. ("Got it — sounds like first-time setup. Let me walk you through init → push.")
2. Ask the decision point for that workflow. Single question, no monologue.
3. Show the next command (verbatim), explain it in one sentence, run it after user confirmation.
4. Repeat until the workflow completes or the user changes direction.
5. End with a pointer to the docs page or vsync <sub> --help for what's next.

Anti-pattern (what the deleted skill encouraged): the assistant emits a 300-word essay about the threat model before running the first command. The user wanted to share secrets; the threat model is in the docs.

8. Onboarding-narrative — the assistant's "first ten minutes"

The skill's success metric is the user's first ten minutes. Concretely:

Minute	What the user sees	What the assistant does
0:00	"I want to share secrets with my team"	Triggers, greets, asks: owner or joining?
0:30	"I'm the owner, our backend is AWS S3"	Suggests vsync profile add aws-prod. Runs it.
2:00	profile is created, bucket configured	Suggests vsync init prod --profile=aws-prod. Runs it.
4:00	env created, vault folder ready	Asks user to drop secrets into infra/vault/prod/. Confirms.
6:00	secrets in place	Suggests vsync push prod. Runs it.
8:00	push successful	Suggests vsync export prod to onboard the first teammate.
10:00	.share file in hand	Reminds user to send file + passphrase on different channels. Points at the website.

Ten minutes. Five commands. One concept (different channels). Done.

9. Out of scope for the skill (and where it lives instead)

Topic	Lives at
Full CLI flag reference	vsync <sub> --help (every subcommand has detailed help — see commit fb6f735)
Per-target sync flags	https://muthuishere.github.io/vsync/guide/sync
Runtime library API	https://muthuishere.github.io/vsync/libraries/
Crypto envelope internals	docs/specs/v0.2-secret-lib.md
Audit log row format	docs/specs/v0.4-audit-log.md
Migration from 0.10 → 0.11	https://muthuishere.github.io/vsync/guide/upgrade-to-0.11
Examples for every framework	https://muthuishere.github.io/vsync/examples/

The skill knows these exist and links to them. It does NOT carry them.

10. Acceptance criteria — when is the skill "done"

The skill (when implemented per this spec) should:

1. Be one file (SKILL.md) plus at most three references/*.md files. Total under 600 lines of Markdown.
2. Walk a new user from "I just heard about vsync" to "first push lands" in five commands and under ten minutes of conversation.
3. Walk a teammate from "I got a .share file" to "I have the env decrypted" in three commands.
4. Recognise the five canonical workflows from §4.2 and dispatch without ambiguity.
5. Never reimplement the CLI's logic in prose. Every operation is "show the command, run it."
6. Survive the question "what about X?" by pointing at the docs site or --help, not by extending its own prose.

If a future contribution makes the skill longer than 600 lines, that contribution probably belongs on the website, not in the skill.

11. What's intentionally out of scope (in this spec)

• An actual skill implementation. This spec is a contract; the implementation lands in skills/ (or wherever the project's skill-discovery convention puts it) in a follow-up commit when the user is ready.
• A spec for skills in other languages. The vsync CLI is one engine; a polyglot-runtime skill would be a sibling spec.
• Versioning of the skill itself. Treat it as the same 0.x.x train as the CLI — bump when the CLI surface bumps. No separate semver thread.

---

Summary. A proper vsync agent skill is small, onboarding-shaped, and respectful of the boundary between "the assistant" and "the engine." The CLI is the engine. The skill is the friction-reduction layer over the first ten minutes. The website is the manual.