agentleFS
BlockKnown publisherblock/berd/.agents/skills/berdctl-new-command/SKILL.md

berdctl-new-command

Skill1k starsChanged 3 months agoApache-2.0View on GitHub

Use when adding, extending, modifying, or removing berdctl commands, verbs, nouns, schemas, help text, or any of the berdctl surface.

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 5 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Distinctive:

    Delete, bulk, silent, invisible, or broadly destructive work requires auth/confirmation design review.

    line 16
  2. Distinctive:

    Put bounds in zod; clap mirrors them.

    line 18
  3. Very specific:

    Keep descriptors import-pure.

    line 19
  4. Distinctive:

    Do not hand-edit generated contract JSON.

    line 21
  5. Very specific:

    Keep the broker command-agnostic.

    line 22
  6. Very specific:

    Add commands with just new-command <noun> <verb>.

    line 29
  7. Very specific:

    Update inventories only when needed: registry.ts group cli.about, top-level help pins in tree.rs, and distro/skills/berdctl/SKILL.md for …

    line 33
  8. Distinctive:

    Before review, confirm the verb is UI-visible and either reversible or a direct visible product action, help is complete, error messages …

    line 39
  9. Distinctive:

    Keep CLI shapes expressible by the generated field walker.

    line 43

≈ “Common” is an estimate: at least 1 in 5 of the 308,232 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

berdctl command changes

One command is one renderer module. Descriptors are the source for zod validation, TS input types, CLI help, and generated contract JSON. Background: docs/berdctl-architecture.md.

Rules

  • Verbs must be UI-visible. Prefer reversible mutations, but one-way visible product actions like creating a session or sending a prompt are allowed. Delete, bulk, silent, invisible, or broadly destructive work requires auth/confirmation design review.
  • Put bounds in zod; clap mirrors them.
  • Keep descriptors import-pure. Import stores, Tauri APIs, navigation, providers, and caches only inside execute/precheck.
  • Do not hand-edit generated contract JSON.
  • Keep the broker command-agnostic; normal command changes do not touch src-tauri/plugins/berdctl/.
  • Breaking wire reshapes bump both discovery.rs constants and the contract mirror. New commands and optional fields are not reshapes.

Workflow

  • Add commands with just new-command <noun> <verb>.
  • Implement src/features/berdctl/commands/impl/<verbNoun>.ts with: .strict() schema, .describe() on every field, summary, description, helpFooter, safety metadata, optional precheck, and execute.
  • Update inventories only when needed: registry.ts group cli.about, top-level help pins in tree.rs, and distro/skills/berdctl/SKILL.md for overview changes.
  • Run pnpm generate:berdctl-contract, pnpm vitest run src/features/berdctl, and cargo test -p berdctl from src-tauri/.
  • Before review, confirm the verb is UI-visible and either reversible or a direct visible product action, help is complete, error messages name the fixing command, artifacts are regenerated, and tests cover the behavior.

Keep CLI shapes expressible by the generated field walker. If a requested operation needs an explicit null or another shape that generic flags cannot represent safely, model it as a separate command action instead of adding command-specific Rust mapping. Example: use session move --project-id <id> for moving into a project and session clear-project for moving out.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.