Skip to content

Add sprout-cli agent skill to nest initialization#613

Merged
wpfleger96 merged 11 commits into
mainfrom
cli-agent-skill
May 22, 2026
Merged

Add sprout-cli agent skill to nest initialization#613
wpfleger96 merged 11 commits into
mainfrom
cli-agent-skill

Conversation

@wpfleger96
Copy link
Copy Markdown
Collaborator

@wpfleger96 wpfleger96 commented May 18, 2026 •
edited
Loading

Agents migrating from the MCP server to the CLI have no structured guidance on command usage, output formats, or polling patterns. The existing ~/.sprout/AGENTS.md still documents MCP tools, not CLI commands.

Ships a SKILL.md covering all 13 CLI command groups and 62 subcommands (messaging, channels, canvas, reactions, DMs, users, workflows, feed, social, repos, upload, mem, pack), written to ~/.sprout/.claude/skills/sprout-cli/SKILL.md on first launch. Uses the same idempotent O_CREAT|O_EXCL pattern as AGENTS.md so user edits are never overwritten.

Skill content covers:

  • Environment setup (SPROUT_PRIVATE_KEY, SPROUT_RELAY_URL, output conventions, error format, exit codes 0-5)
  • Parameter conventions (UUID channels, hex-64 events/pubkeys, stdin via -)
  • All 62 subcommands with usage examples and output contracts
  • Output asymmetries agents must know: normalized JSON (messages/channels/etc.), raw Nostr JSON including sig (social/repos), raw markdown (canvas get), pretty-printed blob descriptors (upload), stderr-only progress (mem write commands)
  • Polling pattern (no push/webhook support, --since cursor advancement)
  • Quick Reference table organized by output pattern (read, write, raw, other) for fast lookup

Implementation:

  • Creates nest_skill.md with YAML frontmatter (name: sprout-cli, version: 1) compiled in via include_str!
  • Extends ensure_nest_at() to create .claude/skills/sprout-cli/ and write SKILL.md; sets 700 Unix permissions on all three intermediate dirs — symlink-safe
  • 3 unit tests: file creation, idempotent no-overwrite, 700 permissions on all intermediate dirs

Companion to #612 — the skill documents the CLI's behavior after the parity fixes land.

@wpfleger96 wpfleger96 requested a review from wesbillman as a code owner May 18, 2026 22:41
@wpfleger96 wpfleger96 mentioned this pull request May 18, 2026
Merged
@wpfleger96 wpfleger96 marked this pull request as draft May 19, 2026 21:31
@wpfleger96 wpfleger96 force-pushed the cli-agent-skill branch 4 times, most recently from 5af942b to 3474e1e Compare May 20, 2026 21:56
@wpfleger96 wpfleger96 marked this pull request as ready for review May 21, 2026 16:25
@wpfleger96 wpfleger96 requested a review from a team as a code owner May 21, 2026 16:25
wpfleger96 and others added 10 commits May 22, 2026 10:42
@wpfleger96
feat(nest): add sprout-cli agent skill to nest initialization
5f6002a 
Agents migrating from the MCP server to the CLI have no structured
guidance on command usage, output formats, or polling patterns. Ships
a 1,350-word SKILL.md covering all 12 command groups, written to
~/.sprout/.claude/skills/sprout-cli/ on first launch using the same
idempotent O_CREAT|O_EXCL pattern as AGENTS.md.

Signed-off-by: Will Pfleger <wpfleger@block.xyz>
@wpfleger96
fix(nest): correct skill content inaccuracies + chmod intermediate dirs
1983a85 
Four inaccuracies in nest_skill.md caught by comparing against CLI source:

1. canvas get returns a JSON array of kind:40100 events (markdown in
   `content`), not a plain markdown string. Agents parsing this as a
   raw string would get the Nostr event wrapper, not the content.

2. reactions get returns a raw JSON array of kind:7 events, not the
   aggregated {"reactions": [...]} shape. No aggregation happens in
   cmd_get_reactions.

3. Error stderr category field values were placeholder text ("input error",
   "network/relay error") instead of the actual enum values emitted by
   error.rs: user_error, relay_error, network_error, auth_error, key_error.

4. set-presence documents as working but cmd_set_presence has an explicit
   comment noting it always fails — kind:20001 is ephemeral and the relay
   rejects it over HTTP POST. Added a "this will fail" caveat.

Also fixes a permission gap in nest.rs: create_dir_all(".claude/skills/
sprout-cli") created the intermediate .claude/ and .claude/skills/ dirs
with umask-default permissions (typically 755), but only the final
sprout-cli/ dir was chmod'd to 700. Lock down all three dirs in the
skill path, matching how NEST_DIRS are handled. Test updated to assert
all three dirs get 700 on Unix.

Docstring for ensure_nest_at updated to mention SKILL.md.

Signed-off-by: Will Pfleger <wpfleger@block.xyz>
@wpfleger96
fix(nest): update skill content for CLI parity changes
6d77694 
Sync SKILL.md descriptions with post-review CLI output shapes: canvas
get returns markdown string or null (not event array), reactions get
returns grouped {emoji, count, pubkeys} (not raw events), users get
always returns array, workflows get documents normalized shape, workflows
runs notes empty-result limitation. Quick reference table updated.

Signed-off-by: Will Pfleger <wpfleger@block.xyz>
@wpfleger96
style: fix rustfmt formatting after rebase
e3f1e11 
Reformat code after rebasing onto main (which includes PR #614's
nest.rs additions). No logic changes.

Signed-off-by: Will Pfleger <wpfleger@block.xyz>
@wpfleger96
docs(cli-skill): update skill file to match CLI parity changes
a366514 
Brings the agent skill file to parity with all 62 CLI subcommands
across 13 command groups after PR #612's output normalization and bug
fixes. Adds 5 missing command groups (social, repos, upload, mem,
pack), 5 missing subcommands in existing groups (channels update/
add-member/remove-member, workflows update/delete), missing flags
(--file, --mention, --kinds, --depth-limit, --limit), fixes output
contract inaccuracies (channels get pubkey field, workflows list
pubkey, exit code 5, feed description), and restructures the Quick
Reference table by output pattern for scannability.

Signed-off-by: Will Pfleger <wpfleger@block.xyz>
@wpfleger96
docs(cli-skill): add --limit and --format compact to skill file
4932cc7 
Documents the new --limit flag on channels list and the global
--format json|compact flag added in PR #612. Compact mode reduces
read output: channels → {channel_id, name}, messages → {id, content,
created_at}, users → {pubkey, display_name}.

Signed-off-by: Will Pfleger <wpfleger@block.xyz>
@wpfleger96
docs(cli-skill): fix 6 documentation gaps in skill file
933cf42 
Add missing send-diff optional flags, mark repos create --name as
optional, document --owner on all mem subcommands, add --allow-empty to
mem patch, remove dead --depth-limit from thread example, and document
social set-list --content.

Signed-off-by: Will Pfleger <wpfleger@block.xyz>
@wpfleger96
Condense sprout-cli skill to ~90 lines of navigation context
990df78 
The skill duplicated the CLI's own per-subcommand --help (usage, flags,
examples). Rewrite to teach what --help can't: discovery, conventions
(UUID vs hex, stdin -, --format), output asymmetries, error/exit
contract, polling. Point to 'sprout <cmd> --help' for the rest.
630 deletions, 78 insertions.

Signed-off-by: Will Pfleger <wpfleger@block.xyz>
@wpfleger96
Fix sprout-cli skill: correct claims to match CLI source
ea9757e 
Source audit (crates/sprout-cli/) caught five wrong claims inherited
from or worsened by the original file:
- No --format flag exists; removed all references.
- Reads are NOT normalized — every read prints the raw relay /query
  response (raw Nostr events with sig). Reframed accordingly.
- canvas get returns kind:40100 event JSON, not a markdown string.
- Default get kinds are [9, 40002], not the 5-kind list.
- --kind on send is dead code (#[allow(dead_code)]); send is always
  kind:9. Removed the forum-routing claim.
Also: feed ordering is relay-determined, not a CLI guarantee.
Every retained claim verified against source + live binary.

Signed-off-by: Will Pfleger <wpfleger@block.xyz>
@wpfleger96
refactor(cli-skill): rewrite skill file for token efficiency
604939d 
650 → 100 lines (85% reduction). Agents can discover flags via
`sprout --help` — the skill now documents only what --help can't:
output contracts, compact format projections, behavioral gotchas,
mem patch workflow, and polling pattern.

Signed-off-by: Will Pfleger <wpfleger@block.xyz>
@wpfleger96 wpfleger96 enabled auto-merge (squash) May 22, 2026 14:45
@wpfleger96 wpfleger96 disabled auto-merge May 22, 2026 14:59
@wpfleger96 wpfleger96 merged commit 55190b1 into main May 22, 2026
15 checks passed
@wpfleger96 wpfleger96 deleted the cli-agent-skill branch May 22, 2026 15:28
wpfleger96 added a commit that referenced this pull request May 22, 2026
@wpfleger96
style: fix formatting and bump nest.rs file size override
77bac96 
rustfmt fixes after rebase onto main (extra blank lines in lib.rs and
nest.rs). Bump nest.rs file size override from 800 to 960 to account
for skill file init code merged from #613.

Signed-off-by: Will Pfleger <wpfleger@block.xyz>
wpfleger96 added a commit that referenced this pull request May 22, 2026
@wpfleger96
style: fix formatting and bump nest.rs file size override
21eeff5 
rustfmt fixes after rebase onto main (extra blank lines in lib.rs and
nest.rs). Bump nest.rs file size override from 800 to 960 to account
for skill file init code merged from #613.

Signed-off-by: Will Pfleger <wpfleger@block.xyz>
wpfleger96 added a commit that referenced this pull request May 22, 2026
@wpfleger96
style: fix formatting and bump nest.rs file size override
0c90ad7 
rustfmt fixes after rebase onto main (extra blank lines in lib.rs and
nest.rs). Bump nest.rs file size override from 800 to 960 to account
for skill file init code merged from #613.

Signed-off-by: Will Pfleger <wpfleger@block.xyz>
wpfleger96 added a commit that referenced this pull request May 23, 2026
@wpfleger96
style: fix formatting and bump nest.rs file size override
ed6c20e 
rustfmt fixes after rebase onto main (extra blank lines in lib.rs and
nest.rs). Bump nest.rs file size override from 800 to 960 to account
for skill file init code merged from #613.

Signed-off-by: Will Pfleger <wpfleger@block.xyz>
wpfleger96 added a commit that referenced this pull request May 26, 2026
@wpfleger96
style: fix formatting and bump nest.rs file size override
70bb0bd 
rustfmt fixes after rebase onto main (extra blank lines in lib.rs and
nest.rs). Bump nest.rs file size override from 800 to 960 to account
for skill file init code merged from #613.

Signed-off-by: Will Pfleger <wpfleger@block.xyz>
wpfleger96 added a commit that referenced this pull request May 26, 2026
@wpfleger96
style: fix formatting and bump nest.rs file size override
9c974ea 
rustfmt fixes after rebase onto main (extra blank lines in lib.rs and
nest.rs). Bump nest.rs file size override from 800 to 960 to account
for skill file init code merged from #613.

Signed-off-by: Will Pfleger <wpfleger@block.xyz>
This was referenced May 28, 2026
Merged
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@wesbillman wesbillman Awaiting requested review from wesbillman

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@wpfleger96