@wrongstack/core 0.277.2 → 0.280.1

package/skills/skill-creator/SKILL.md

@@ -3,14 +3,14 @@ name: skill-creator
 description: |
   Use this skill when the user wants to create a new AI skill in WrongStack.
   Triggers: user says "create a skill", "new skill", "add a skill", "skill definition".
-version: 1.1.0
+version: 1.2.0
 ---
 
 # Skill Creator — WrongStack
 
 ## Overview
 
-Guides the creation of new WrongStack skills. A skill is a Markdown file with YAML frontmatter — the first sentence of the description is the trigger. You are the wizard: ask questions, validate answers, write the file.
+Guides the creation of new WrongStack skills. A skill is a Markdown file with YAML frontmatter — the first sentence of the description is the trigger. You are the wizard: ask questions, validate answers, write the file. Use the `/skill-gen` sub-commands to do the mechanical parts (validation, scaffolding) deterministically.
 
 ## Rules
 
@@ -22,6 +22,22 @@ Guides the creation of new WrongStack skills. A skill is a Markdown file with YA
 6. End with "Skills in scope" listing related skills for delegation.
 7. Don't let skill names collide with existing skills.
 
+## Authoring commands (use these)
+
+The `/skill-gen` command is a toolkit — pick the right sub-command for the job instead of writing files by hand:
+
+| Sub-command | When to use |
+|---|---|
+| `/skill-gen` (bare) | Open-ended creation: you (the agent) ask questions one at a time, then write the file. Best for nuanced skills. |
+| `/skill-gen skeleton <name> --desc "..." --trigger a,b` | Quick scaffold: generates a valid SKILL.md skeleton the user edits. Use when the name + trigger are already known. |
+| `/skill-gen from-prompt "<text>"` | Turn an existing prompt/instruction into a skill draft. Use when the user hands you a prompt and says "make this a skill". |
+| `/skill-gen validate <name>` | Validate a name (format + collisions) before writing. **Always run this before creating a file.** |
+| `/skill-gen view <name>` | Read-only: show a skill's body. |
+| `/skill-gen edit <name>` | Open the skill in `$EDITOR`/`$VISUAL`. |
+| `/skill-gen list` | List skills with their source layer. |
+
+After writing a skill with the wizard flow, run `/skill-gen validate <name>` to confirm it loads cleanly.
+
 ## Patterns
 
 ### Do
@@ -95,16 +111,38 @@ What this skill does.
 2. Step two
 ```
 
-## File Location
+## File structure
+
+A skill is a directory containing `SKILL.md` plus optional resource subdirectories (the agentskills.io layout):
+
+```
+<name>/
+  SKILL.md            ← required: metadata + instructions
+  scripts/            ← optional: executable code (run via bash)
+  references/         ← optional: docs loaded on demand (REFERENCE.md, …)
+  assets/             ← optional: templates, data, snippets
+  …                   ← any other subdirectories
+```
 
-Skills live in directories under these paths (priority order):
+Skills live under these paths (priority order, first-seen wins by name):
 
-1. **Project**: `<project>/.wrongstack/skills/<name>/SKILL.md`
-2. **User global**: `~/.wrongstack/skills/<name>/SKILL.md`
-3. **Bundled**: `packages/core/skills/<name>/SKILL.md` (read-only, for core team)
+1. **Project**: `<project>/.wrongstack/skills/<name>/`
+2. **Project foreign**: `<project>/.claude/skills/<name>/`, `<project>/.{codex,cursor,agents,…}/skills/<name>/`
+3. **User global**: `~/.wrongstack/skills/<name>/`
+4. **User foreign**: `~/.claude/skills/<name>/`, `~/.{codex,cursor,agents,…}/skills/<name>/`
+5. **Bundled**: `packages/core/skills/<name>/` (read-only, core team)
 
 For user-created skills: always use path 1 (project level).
 
+## Resource files (scripts / references / assets)
+
+Bundled resources are NOT injected into the prompt — the agent loads them on demand via the `skill` tool (agentskills.io progressive disclosure, tier 3):
+
+- `skill({ name: "<name>" })` → lists every bundled file (scripts/, references/, assets/, any subdir, recursively).
+- `skill({ name: "<name>", resource: "references/REF.md" })` → returns that file's content. Scripts come back with an absolute path so the agent runs them via `bash`.
+
+Keep `SKILL.md` under ~500 lines; move deep reference material into `references/`. Reference files with relative paths from the skill root. Scripts must be self-contained and safe to run. Only add the subdirectories a skill actually needs — empty directories don't persist in git, so create a file (e.g. `scripts/README.md`) if you want the directory tracked.
+
 ## Workflow
 
 1. **Ask the name** — suggest kebab-case, validate format

package/skills/wrongstack-mailbox/SKILL.md

@@ -374,38 +374,35 @@ setInterval(() => {
 ### Poll, don't long-poll
 
 The bridge does not support long-polling or websockets. Poll for new
-messages on a 5–10 s interval using the `since` filter. Don't poll
-faster than 1 Hz — that's noisy and gives nothing useful.
+messages on a 5–10 s interval. Don't poll faster than 1 Hz — that's noisy
+and gives nothing useful.
 
-```ts
-let lastSeen: string | undefined;
+For normal inbox catch-up, prefer `/mailbox/check` over manual
+`/mailbox/query` + `/mailbox/ack-many`. It checks direct mail,
+`baseId` alias mail, and broadcasts in one call, dedupes messages, and
+can optionally mark them read or completed via one batch ack.
 
+```ts
 async function pollOnce(): Promise<void> {
-  const args: Record<string, unknown> = {
-    to: agentId,             // mail addressed to me
-    incompleteOnly: true,    // only work I haven't finished
+  const result = await mb('/mailbox/check', {
+    agentId,
+    baseId: 'claude-code',       // optional: your bare alias
     limit: 50,
-  };
-  if (lastSeen !== undefined) args['since'] = lastSeen;
-  const result = await mb('/mailbox/query', args) as { data: MailboxMessage[] };
+  }) as { data: MailboxMessage[] };
 
   for (const m of result.data) {
     console.log(`[${m.type}] from=${m.from} subject=${m.subject}`);
     // ...handle the message...
-    await mb('/mailbox/ack', {
-      messageId: m.id,
-      readerId: agentId,
-      read: true,
-    });
-  }
-  if (result.data.length > 0) {
-    lastSeen = result.data[result.data.length - 1]!.timestamp;
   }
 }
 
 setInterval(pollOnce, 5_000);
 ```
 
+Use `/mailbox/query` directly when you need custom searches such as
+`from`, `type`, `since`, or `minPriority` filters rather than inbox
+catch-up.
+
 ### Reply with `replyTo`
 
 Set `replyTo` to the id of the message you're replying to. The original
@@ -424,11 +421,32 @@ await mb('/mailbox/send', {
 });
 ```
 
+### Complete messages while checking inbox
+
+If handling a message finishes the requested work, mark it completed in the
+same `/mailbox/check` call. This preserves read receipts and completion
+state with one batch ack:
+
+```ts
+const result = await mb('/mailbox/check', {
+  agentId,
+  baseId: 'claude-code',
+  completed: true,
+  outcome: 'handled',
+}) as { data: MailboxMessage[] };
+```
+
+Use `markRead: false` to peek without consuming messages:
+
+```ts
+await mb('/mailbox/check', { agentId, markRead: false });
+```
+
 ### Ack in batches
 
-If you've just consumed a backlog, don't ack them one at a time. Use
-`/mailbox/ack-many` — one HTTP request, one file-lock acquisition, one
-JSONL rewrite inside WrongStack:
+If you've just consumed a backlog through custom `/mailbox/query` filters,
+don't ack them one at a time. Use `/mailbox/ack-many` — one HTTP request,
+one file-lock acquisition, one JSONL rewrite inside WrongStack:
 
 ```ts
 await mb('/mailbox/ack-many', {
@@ -488,6 +506,7 @@ All routes take JSON bodies on POST (or no body on GET). All require
 |--------|------|---------|
 | POST | `/mailbox/send` | Send a message |
 | POST | `/mailbox/query` | Query messages (filters: `to`, `from`, `unreadBy`, `type`, `minPriority`, `incompleteOnly`, `limit`, `since`) |
+| POST | `/mailbox/check` | Read inbox mail for `agentId`/`baseId` plus broadcasts; optionally `markRead=false`, `completed=true`, `outcome` |
 | POST | `/mailbox/ack` | Acknowledge one message |
 | POST | `/mailbox/ack-many` | Acknowledge many in one batch |
 | POST | `/mailbox/unread-count` | Count unread for an agent |