Ship an AI-agent skill bundle via `http-nu skills` subcommand

[joeblew999]

Problem

The README documents a lot of http-nu-specific surface area that an LLM coding assistant otherwise has to re-derive each session or guess at: the {|req| ...} closure shape, metadata set for response status/headers, content-type inference order, to sse, the http-nu/html DSL, http-nu/datastar SDK, http-nu/router dispatch/mount, http-nu/http cookies, store-backed handlers via .cat/.append/.bus, etc.

Multiple coding assistants now read project-local context files — Claude Code (.claude/skills/), Cursor (.cursor/rules/), the emerging AGENTS.md convention, plus Codex / Gemini CLI / Aider / Windsurf and others. When a user runs any of these inside an http-nu project, that knowledge should already be there.

Proposal

Ship the knowledge as data inside the binary; let the user route it to whichever tool they use.

http-nu skills export                       # writes SKILL.md to stdout
http-nu skills export --path <dir>          # writes the full bundle to <dir>
http-nu skills export --format agents-md    # single AGENTS.md
http-nu skills install --target claude      # ~/.claude/skills/http-nu/
http-nu skills install --target claude --project   # ./.claude/skills/http-nu/
http-nu skills install --target cursor      # ./.cursor/rules/http-nu.mdc
http-nu skills install --target agents-md   # ./AGENTS.md (merge/append)
http-nu skills list                         # what's bundled, with versions

The canonical form is a SKILL.md (YAML frontmatter + markdown, per agentskills.io) plus reference files. Adapters convert to other shapes. export is the composable primitive; install --target is sugar over known layouts.

The bundle lives in the repo (e.g. skills/http-nu/SKILL.md plus reference files), is embedded via include_bytes!, and is extracted on demand — same pattern as the embedded Datastar JS bundle.

Prior art

The upstream nushell repo already ships an AGENTS.md at root with CLAUDE.md as a symlink to it — tool-agnostic by design, single source of truth. http-nu projects routinely pull both in, so the layouts should compose:

my-project/
├── AGENTS.md                      # project's own rules
└── .claude/skills/
    ├── nushell/SKILL.md           # (hypothetical, mirrors nushell's AGENTS.md)
    └── http-nu/SKILL.md           # from `http-nu skills install --project`

Why in the binary

• The bundle stays in lockstep with the installed http-nu version — no version drift between a separate registry and the CLI.
• One command, parallel to rustup completions or gh completion install.
• The eval subcommand already establishes that the binary is comfortable being its own toolbox.
• Tool-agnostic by design: when a new agent convention emerges, add an adapter, don't rewrite the content.

Bundle content sketch

Progressive-disclosure layout:

• SKILL.md — trigger description and high-level map
• Handler closure shape and request record fields
• Response metadata (status, headers, multi-value headers)
• Content-type precedence rules
• Streaming responses and to sse
• .static, .reverse-proxy, .run
• Embedded modules: http-nu/router, http-nu/html, http-nu/datastar, http-nu/http
• Store-backed patterns (.cat --follow, .last --follow, .bus pub/sub)
• eval for unit testing handlers

Reference files (REFERENCE-datastar.md, REFERENCE-router.md, etc.) so SKILL.md stays under the trigger-description budget.

Open questions

• Initial set of --target adapters: claude, cursor, agents-md seems like the minimum useful trio. Others on request.
• Include the http-nu version in the bundle so the agent knows which release it's pinned to.
• Slash-command equivalents: most tools have a notion of named commands; worth scoping separately.
• Bundle for cross.stream / xs would be a natural sibling — same mechanism.

Happy to take a first cut if useful.