@napplet/skills

Agent skills that let a coding agent make, design, build, port, and test a napplet end-to-end, installed through napplet skills into whatever location your agent reads.

A napplet is a sandboxed Nostr iframe app (NIP-5D). These skills carry the exact, verified API surface and protocol constraints an agent needs so that one well-scoped prompt produces a working, conformant napplet.

• npm: @napplet/skills
• JSR: @napplet/skills
• Source: packages/skills

The skills

Skill	When	Covers
make-napplet	One-prompt end-to-end builds	Orchestrates project-state triage, port/design/build/test, NAP-THEME whole-surface application, Paja runtime preview, OUTBOX-first behavior, and the final evidence checklist.
design-napplet	First — plan before code	Sandbox/loading constraints, OUTBOX-first NAP selection, hard-vs-optional shell domains, NAP-THEME mappings including the page background, responsive layout for any viewport (full-screen → tiny widget), and the build spec to hand off.
build-napplet	Implementation	Starts from the correct project state, preserves the starter substrate, applies NAP-THEME to the full surface including html/body backgrounds, uses @napplet/sdk, and previews through Paja rather than reporting a raw Vite URL.
port-nostr-app	Migrating an existing Nostr app	Replace direct relay pools, window.nostr, local storage, direct fetch/media loads, and app-owned signing/routing with shell-owned NAP boundaries and SDK helper imports before building.
test-napplet	Before publishing	Protocol conformance via napplet-conformance (real Chromium + reference shell), interpreting failures, the runtime guard, CI wiring.

Each skill is a self-contained SKILL.md with YAML frontmatter (name, description) — the format Claude Code, Cursor, and most agents consume.

Scaffolding substrate

For new napplet projects, build-napplet and the top-level make-napplet workflow treat napplet create and its @napplet/boilerplate implementation as authoritative. Agents should scaffold through the CLI, run napplet init for deployment metadata, keep its package manager pin, Vite config, scripts, file layout, README/docs structure, and conformance wiring, then edit only project-specific surfaces such as nappletType, requires, config schema, src/main.ts, src/styles.css, title/root markup, and README content.

Current package guidance is SDK-first. Napplet code should use @napplet/sdk wrappers for domain calls, use window.napplet?.domain only for optional fallback checks after runtime injection, and keep optional enhancements such as shell-managed key reservation out of requires unless the napplet cannot function without them.

Generated napplets should run the boilerplate's own validation before completion:

pnpm verify
pnpm test:conformance

Manual package/script/Vite wiring belongs only to explicit existing-app retrofits, and should mirror the boilerplate contract.

Install routes

No build step needed — the CLI ships the Markdown and places it for you.

napplet skills install --to claude

--to	Destination	Layout
claude	.claude/skills/<skill>/SKILL.md	one folder per skill
claude-user	~/.claude/skills/<skill>/SKILL.md	global, all projects
cursor	.cursor/rules/<skill>.mdc	one rule file per skill
windsurf	.windsurf/rules/<skill>.md	one rule file per skill
agents	AGENTS.md	appended block (Codex, Amp, Jules, generic)
gemini	GEMINI.md	appended block (Gemini CLI)
copilot	.github/copilot-instructions.md	appended block

agents / gemini / copilot are idempotent — re-running replaces the managed <!-- @napplet/skills:start -->…<!-- @napplet/skills:end --> block without duplicating it. The rest of the file is untouched.

Custom locations & single skills

napplet skills install --dir vendor/skills        # writes <dir>/<skill>/SKILL.md
napplet skills install --to claude --symlink      # symlink instead of copy
napplet skills install make-napplet --to agents   # one-prompt workflow only
napplet skills install build-napplet --to gemini  # just one skill
napplet skills print build-napplet > skill.md     # raw markdown to stdout

Programmatic API

import { listSkills, readSkill, install } from '@napplet/skills';

listSkills();                      // [{ name, description, path }, …]
readSkill('build-napplet');        // full SKILL.md source
install({ to: 'claude' });         // → InstallResult[]

See also

• Getting started — scaffold and run your first napplet
• @napplet/boilerplate — the starter template the build skill targets
• @napplet/conformance-cli — the runner the test skill drives