@nano-step/skill-manager 5.2.1 → 5.3.0

package/dist/utils.d.ts

@@ -1,4 +1,4 @@
-export declare const MANAGER_VERSION = "5.2.1";
+export declare const MANAGER_VERSION = "5.3.0";
 export interface SkillManifest {
     name: string;
     version: string;

package/dist/utils.js

@@ -13,7 +13,7 @@ exports.writeText = writeText;
 const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
-exports.MANAGER_VERSION = "5.2.1";
+exports.MANAGER_VERSION = "5.3.0";
 async function detectOpenCodePaths() {
     const homeConfig = path_1.default.join(os_1.default.homedir(), ".config", "opencode");
     const cwd = process.cwd();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nano-step/skill-manager",
-  "version": "5.2.1",
+  "version": "5.3.0",
   "description": "CLI tool that installs and manages AI agent skills, MCP tool routing, and workflow configurations.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skills/feature-analysis/SKILL.md

@@ -0,0 +1,290 @@
+---
+name: feature-analysis
+description: "Deep code analysis of any feature or service before writing docs, diagrams, or making changes. Enforces read-everything-first discipline. Traces exact execution paths, data transformations, guard clauses, bugs, and gaps between existing docs and actual code. Produces a validated Mermaid diagram and structured analysis output. Language and framework agnostic."
+compatibility: "OpenCode"
+metadata:
+  version: "2.0.0"
+tools:
+  required:
+    - Read (every file in the feature)
+    - Bash (find all files, run mermaid validator)
+  uses:
+    - mermaid-validator skill (validate any diagram produced)
+triggers:
+  - "analyze [feature]"
+  - "how does X work"
+  - "trace the flow of"
+  - "understand X"
+  - "what does X do"
+  - "deep dive into"
+  - "working on X - understand it first"
+  - "update docs/brain for"
+---
+
+# Feature Analysis Skill
+
+A disciplined protocol for deeply analyzing any feature in any codebase before producing docs, diagrams, or making changes. Framework-agnostic. Language-agnostic.
+
+---
+
+## The Core Rule
+
+**READ EVERYTHING. PRODUCE NOTHING. THEN SYNTHESIZE.**
+
+Do not write a single diagram node, doc line, or description until every file in the feature has been read. Every time you produce output before reading all files, you will miss something.
+
+---
+
+## Phase 1: Discovery — Find Every File
+
+Before reading anything, map the full file set.
+
+```bash
+# Find all source files for the feature
+find <feature-dir> -type f | sort
+
+# Check imports to catch shared utilities, decorators, helpers
+grep -r "import\|require" <feature-dir> | grep -v node_modules | sort -u
+```
+
+**Read in dependency order (bottom-up — foundations first):**
+
+1. **Entry point / bootstrap** — port, env vars, startup config
+2. **Schema / model files** — DB schema, columns, nullable, indexes, types
+3. **Utility / helper files** — every function, every transformation, every constant
+4. **Decorator / middleware files** — wrapping logic, side effects, return value handling
+5. **Infrastructure services** — cache, lock, queue, external connections
+6. **Core business logic** — the main service/handler files
+7. **External / fetch services** — HTTP calls, filters applied, error handling
+8. **Entry controllers / routers / handlers** — HTTP method, route, params, return
+9. **Wiring files** — module/DI config, middleware registration
+
+**Do not skip any file. Do not skim.**
+
+---
+
+## Phase 2: Per-File Checklist
+
+For each file, answer these questions before moving to the next.
+
+### Entry point / bootstrap
+- [ ] What port or address? (default? env override?)
+- [ ] Any global middleware, pipes, interceptors, or lifecycle hooks?
+
+### Schema / model files
+- [ ] Table/collection name
+- [ ] Every field: type, nullable, default, constraints, indexes
+- [ ] Relations / references to other entities
+
+### Utility / helper files
+- [ ] Every exported function — what does it do, step by step?
+- [ ] For transformations: what inputs? what outputs? what edge cases handled?
+- [ ] Where is this function called? (grep for usages)
+- [ ] How many times is it called within a single method? (once per batch? once per item?)
+
+### Decorator / middleware files
+- [ ] What does it wrap?
+- [ ] What side effects before / after the original method?
+- [ ] **Does it `return` the result of the original method?** (missing `return` = silent discard bug)
+- [ ] Does it use try/finally? What runs in finally?
+- [ ] What happens on the early-exit path?
+
+### Core business logic files
+- [ ] Every method: signature, return type
+- [ ] For each method: trace every line — no summarizing
+- [ ] Accumulator variables — where initialized, where incremented, where returned
+- [ ] Loop structure: sequential or parallel?
+- [ ] Every external call: what service/module, what args, what returned
+- [ ] Guard clauses: every early return / continue / throw
+- [ ] Every branch in conditionals
+
+### External / fetch service files
+- [ ] Exact URLs or endpoints (hardcoded or env?)
+- [ ] Filters applied to response data (which calls filter, which don't?)
+- [ ] Error handling on external calls
+
+### Entry controllers / routers / handlers
+- [ ] HTTP method (GET vs POST — don't assume)
+- [ ] Route path
+- [ ] What core method is called?
+- [ ] What is returned?
+
+### Wiring / module files
+- [ ] What is imported / registered?
+- [ ] What is exported / exposed?
+
+---
+
+## Phase 3: Execution Trace
+
+After reading all files, produce a numbered step-by-step trace of the full execution path. This is not prose — it is a precise trace.
+
+**Format:**
+```
+1. [HTTP METHOD] /route → HandlerName.methodName()
+2. HandlerName.methodName() → ServiceName.methodName()
+3. @DecoratorName: step A (e.g. acquire lock, check cache)
+4.   → if condition X: early return [what is returned / not returned]
+5. ServiceName.methodName():
+6.   step 1: call externalService.fetchAll() → parallel([fetchA(), fetchB()])
+7.     fetchA(): GET https://... → returns all items (no filter)
+8.     fetchB(): GET https://... → filter(x => x.field !== null) → returns filtered
+9.   step 2: parallel([processItems(a, 'typeA'), processItems(b, 'typeB')])
+10. processItems(items, type):
+11.   init: totalUpdated = 0, totalInserted = 0
+12.   for loop (sequential): i = 0 to items.length, step batchSize
+13.     batch = items.slice(i, i + batchSize)
+14.     { updated, inserted } = await processBatch(batch)
+15.     totalUpdated += updated; totalInserted += inserted
+16.   return { total: items.length, updated: totalUpdated, inserted: totalInserted }
+17. processBatch(batch):
+18.   guard: if batch.length === 0 → return { updated: 0, inserted: 0 }
+19.   step 1: names = batch.map(item => transform(item.field))   ← called ONCE per batch
+20.   step 2: existing = repo.find(WHERE field IN names)
+21.   step 3: map = existing.reduce(...)
+22.   step 4: for each item in batch:
+23.     value = transform(item.field)   ← called AGAIN per item
+24.     ...decision tree...
+25.   repo.save(itemsToSave)
+26.   return { updated, inserted }
+27. @DecoratorName finally: releaseLock()
+28. BUG: decorator does not return result → caller receives undefined
+```
+
+**Key things to call out in the trace:**
+- When a utility function is called more than once (note the count and context)
+- Every accumulator variable (where init, where increment, where return)
+- Every guard clause / early exit
+- Sequential vs parallel (for loop vs Promise.all / asyncio.gather / goroutines)
+- Any discarded return values
+
+---
+
+## Phase 4: Data Transformations Audit
+
+For every utility/transformation function used:
+
+| Function | What it does (step by step) | Called where | Called how many times |
+|----------|----------------------------|--------------|----------------------|
+| `transformFn(x)` | 1. step A 2. step B 3. step C | methodName | TWICE: once in step N (batch), once per item in loop |
+
+---
+
+## Phase 5: Gap Analysis — Docs vs Code
+
+Compare existing docs/brain files against what the code actually does:
+
+| Claim in docs | What code actually does | Verdict |
+|---------------|------------------------|---------|
+| "POST /endpoint" | `@Get()` in controller | ❌ Wrong |
+| "Port 3000" | `process.env.PORT \|\| 4001` in entrypoint | ❌ Wrong |
+| "function converts X" | Also does Y (undocumented) | ⚠️ Incomplete |
+| "returns JSON result" | Decorator discards return value | ❌ Bug |
+
+---
+
+## Phase 6: Produce Outputs
+
+Only now, after phases 1–5 are complete, produce:
+
+### 6a. Structured Analysis Document
+
+```markdown
+## Feature Analysis: [Feature Name]
+Repo: [repo] | Date: [date]
+
+### Files Read
+- `path/to/controller.ts` — entry point, GET /endpoint, calls ServiceA.run()
+- `path/to/service.ts` — core logic, orchestrates fetch + batch loop
+- [... every file ...]
+
+### Execution Trace
+[numbered trace from Phase 3]
+
+### Data Transformations
+[table from Phase 4]
+
+### Guard Clauses & Edge Cases
+- processBatch: empty batch guard → returns {0,0} immediately
+- fetchItems: filters items where field === null
+- LockManager: if lock not acquired → returns void immediately (no error thrown)
+
+### Bugs / Issues Found
+- path/to/decorator.ts line N: `await originalMethod.apply(this, args)` missing `return`
+  → result is discarded, caller always receives undefined
+- [any others]
+
+### Gaps: Docs vs Code
+[table from Phase 5]
+
+### Files to Update
+- [ ] `.agents/_repos/[repo].md` — update port, endpoint method, transformation description
+- [ ] `.agents/_domains/[domain].md` — if architecture changed
+```
+
+### 6b. Mermaid Diagram
+
+Write the diagram. Then **immediately run the validator before doing anything else.**
+
+If you have the mermaid-validator skill:
+```bash
+node /path/to/project/scripts/validate-mermaid.mjs [file.md]
+```
+
+Otherwise validate manually — common syntax errors:
+- Labels with `()` must be wrapped in `"double quotes"`: `A["method()"]`
+- No `\n` in node labels — use `<br/>` or shorten
+- No HTML entities (`&amp;`, `&gt;`) in labels — use literal characters
+- `end` is a reserved word in Mermaid — use `END` or `done` as node IDs
+
+If errors → fix → re-run. Do not proceed until clean.
+
+**Diagram must include:**
+- Every step from the execution trace
+- Data transformation nodes (show what the function does, not just its name)
+- Guard clauses as decision nodes
+- Parallel vs sequential clearly distinguished
+- Bugs annotated inline (e.g. "BUG: result discarded")
+
+### 6c. Doc / Brain File Updates
+
+Update relevant docs with:
+- Corrected facts (port, endpoint method, etc.)
+- The validated Mermaid diagram
+- Data transformation table
+- Known bugs section
+
+---
+
+## Anti-Patterns (What This Skill Prevents)
+
+| Anti-pattern | What gets missed | Rule violated |
+|---|---|---|
+| Drew diagram before reading utility files | Transformation called twice — not shown | READ EVERYTHING FIRST |
+| Trusted existing docs for endpoint method | GET vs POST wrong in docs | GAP ANALYSIS required |
+| Summarized service method instead of tracing | Guard clause (empty batch) missed | TRACE NOT SUMMARIZE |
+| Trusted existing docs for port/config | Wrong values | Verify entry point |
+| Read decorator without checking return | Silent result discard bug | RETURN VALUE AUDIT |
+| Merged H1/H2 paths into shared loop node | Sequential vs parallel distinction lost | TRACE LOOP STRUCTURE |
+| Assumed filter applies to all fetches | One fetch had no filter — skipped items | READ EVERY FETCH FILE |
+
+---
+
+## Quick Reference Checklist
+
+Before producing any output, verify:
+
+- [ ] Entry point read — port/address confirmed
+- [ ] All schema/model files read — every field noted
+- [ ] All utility files read — every transformation step documented
+- [ ] All decorator/middleware files read — return value audited
+- [ ] All core service files read — every method traced line by line
+- [ ] All fetch/external services read — filters noted (which have filters, which don't)
+- [ ] All controller/router/handler files read — HTTP method confirmed (not assumed)
+- [ ] All wiring/module files read — dependency graph understood
+- [ ] Utility functions: call count per method noted
+- [ ] All guard clauses documented
+- [ ] Accumulator variables traced (init → increment → return)
+- [ ] Loop structure confirmed (sequential vs parallel)
+- [ ] Existing docs compared against code (gap analysis done)
+- [ ] Mermaid diagram validated before saving

package/skills/feature-analysis/skill.json

@@ -0,0 +1,15 @@
+{
+    "name": "feature-analysis",
+    "version": "2.0.0",
+    "description": "Deep code analysis of any feature or service before writing docs, diagrams, or making changes. Enforces read-everything-first discipline with execution tracing, data transformation audits, and gap analysis.",
+    "compatibility": "OpenCode",
+    "agent": null,
+    "commands": [],
+    "tags": [
+        "analysis",
+        "code-review",
+        "documentation",
+        "mermaid",
+        "tracing"
+    ]
+}

package/skills/mermaid-validator/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: mermaid-validator
+description: "Validate and write correct Mermaid diagrams. Run the validator script before finalizing any .md file containing a mermaid block. Enforces syntax rules that prevent parse errors."
+compatibility: "OpenCode"
+metadata:
+  version: "2.0.0"
+tools:
+  required:
+    - bash (node scripts/validate-mermaid.mjs)
+---
+
+# Mermaid Validator Skill
+
+## MANDATORY WORKFLOW
+
+**Any time you write or edit a Mermaid diagram, you MUST:**
+
+1. Write the diagram
+2. Run the validator
+3. Fix any errors reported
+4. Re-run until clean
+
+**Never** mark a documentation task complete if the validator reports errors.
+
+---
+
+## Validator Script Setup (Per Project)
+
+This skill expects a zero-dependency Node.js validator script at `scripts/validate-mermaid.mjs` in the project root.
+
+If the script doesn't exist yet, create it — see the reference implementation in any project that has already set this up, or ask to scaffold it.
+
+```bash
+# Validate all markdown files (default: scans .agents/ directory)
+node scripts/validate-mermaid.mjs
+
+# Validate a specific file
+node scripts/validate-mermaid.mjs path/to/file.md
+
+# Validate a whole directory
+node scripts/validate-mermaid.mjs path/to/dir/
+```
+
+**Expected clean output:**
+```
+Scanned 12 file(s), 3 mermaid block(s).
+✅ All diagrams passed.
+```
+
+**Error output example:**
+```
+❌ path/to/file.md
+   Line 47 [no-literal-newline]: Literal \n inside node/edge label — use <br/> or rewrite as plain text
+   > B --> C[ServiceName.method\n@Decorator]
+```
+
+---
+
+## Mermaid Syntax Rules (Mandatory Reference)
+
+### ✅ Safe — No quoting needed
+```
+Letters, digits, spaces, hyphens, underscores, colons, slashes, dots, angle brackets
+```
+
+### ⚠️ Requires `"double quotes"` around the whole label
+| Character | Wrong | Right |
+|-----------|-------|-------|
+| Parentheses `()` | `A[label (detail)]` | `A["label (detail)"]` |
+| Percent `%` | `A[100%]` | `A["100%"]` |
+| Ampersand `&` | `A[foo & bar]` | `A["foo & bar"]` |
+| Hash `#` | `A[#tag]` | `A["#tag"]` |
+| At-sign `@` | `A[@lock]` | `A["@lock"]` |
+
+### ❌ Never use inside a diagram block
+| Pattern | Wrong | Fix |
+|---------|-------|-----|
+| Literal `\n` in label | `A[Line1\nLine2]` | `A["Line1<br/>Line2"]` or just `A[Line1 Line2]` |
+| HTML entities | `A[foo &amp; bar]` | `A["foo & bar"]` |
+| HTML numeric entities | `A[&#40;parens&#41;]` | `A["(parens)"]` |
+| Reserved word `end` as node ID | `end[task]` | `End[task]` |
+
+### Edge label quoting
+```
+A -- simple text --> B          ✅ fine
+A -- "text with (parens)" --> B ✅ quoted
+A -- text with (parens) --> B   ❌ breaks
+```
+
+### Node shape reference
+```
+A[Rectangle]
+A(Rounded)
+A([Stadium])        ← OK to have ( inside [ here — this is shape syntax
+A{Diamond}
+A[(Cylinder/DB)]
+A((Circle))
+A>Asymmetric]
+```
+
+### Mermaid entity codes (inside `"quoted"` labels only)
+```
+#40; = (    #41; = )    #35; = #    #37; = %
+```
+
+---
+
+## Writing a Mermaid Diagram — Checklist
+
+Before saving any diagram, mentally check each line:
+
+- [ ] No `\n` inside any label (bracket, brace, or paren)
+- [ ] No `&#NN;` or `&amp;` HTML entities
+- [ ] Any label containing `()` is wrapped in `"double quotes"`
+- [ ] Node IDs are alphanumeric + underscore only (no hyphens in ID itself)
+- [ ] No node ID named `end` (lowercase)
+- [ ] Edge labels containing special chars are `"quoted"`
+- [ ] Diagram has at least one node and one valid statement
+
+Then run the validator. If it passes, you're done.
+
+---
+
+## Common Diagram Patterns
+
+### Service method with decorator
+```mermaid
+flowchart TD
+    A[Controller] --> B["Service.method - @Decorator key ttl"]
+```
+Note: `@` is safe after the first non-@ character. Put the whole label in quotes to be safe.
+
+### Lock/cache decision
+```mermaid
+flowchart TD
+    A --> B{"Redis SET NX EX - key - TTL 1800s"}
+    B -- Lock held --> C([Return void])
+    B -- Lock acquired --> D[Continue]
+```
+
+### DB node (cylinder)
+```mermaid
+flowchart TD
+    A --> B[(database.table)]
+```
+
+### Parallel execution
+```mermaid
+flowchart TD
+    A["Promise.all"] --> B[Task 1]
+    A --> C[Task 2]
+```
+
+### Sequential batch loop
+```mermaid
+flowchart TD
+    A[Start loop] --> B["for i = 0 to items.length step batchSize"]
+    B --> C["batch = items.slice(i, i + batchSize)"]
+    C --> D["processBatch(batch)"]
+    D --> E{More batches?}
+    E -- Yes --> B
+    E -- No --> F[Return totals]
+```

package/skills/mermaid-validator/skill.json

@@ -0,0 +1,15 @@
+{
+    "name": "mermaid-validator",
+    "version": "2.0.0",
+    "description": "Validate and write correct Mermaid diagrams. Run the validator script before finalizing any .md file containing a mermaid block. Enforces syntax rules that prevent parse errors.",
+    "compatibility": "OpenCode",
+    "agent": null,
+    "commands": [],
+    "tags": [
+        "mermaid",
+        "validation",
+        "diagrams",
+        "documentation",
+        "syntax"
+    ]
+}

package/skills/nano-brain/AGENTS_SNIPPET.md

@@ -0,0 +1,46 @@
+<!-- OPENCODE-MEMORY:START -->
+<!-- Managed block - do not edit manually. Updated by: npx nano-brain init -->
+
+## Memory System (nano-brain)
+
+This project uses **nano-brain** for persistent context across sessions.
+
+### Quick Reference
+
+nano-brain supports two access methods. Try MCP first; if unavailable, use CLI.
+
+| I want to... | MCP Tool | CLI Fallback |
+|--------------|----------|--------------|
+| Recall past work on a topic | `memory_query("topic")` | `npx nano-brain query "topic"` |
+| Find exact error/function name | `memory_search("exact term")` | `npx nano-brain query "exact term"` |
+| Explore a concept semantically | `memory_vsearch("concept")` | `npx nano-brain query "concept"` |
+| Save a decision for future sessions | `memory_write("decision context")` | Create file in `~/.nano-brain/memory/` |
+| Check index health | `memory_status` | `npx nano-brain status` |
+
+### Session Workflow
+
+**Start of session:** Check memory for relevant past context before exploring the codebase.
+```
+# MCP (if available):
+memory_query("what have we done regarding {current task topic}")
+
+# CLI fallback:
+npx nano-brain query "what have we done regarding {current task topic}"
+```
+
+**End of session:** Save key decisions, patterns discovered, and debugging insights.
+```
+# MCP (if available):
+memory_write("## Summary\n- Decision: ...\n- Why: ...\n- Files: ...")
+
+# CLI fallback: create a markdown file
+# File: ~/.nano-brain/memory/YYYY-MM-DD-summary.md
+```
+
+### When to Search Memory vs Codebase
+
+- **"Have we done this before?"** → `memory_query` or `npx nano-brain query` (searches past sessions)
+- **"Where is this in the code?"** → grep / ast-grep (searches current files)
+- **"How does this concept work here?"** → Both (memory for past context + grep for current code)
+
+<!-- OPENCODE-MEMORY:END -->

package/skills/nano-brain/SKILL.md

@@ -0,0 +1,77 @@
+# nano-brain
+
+Persistent memory for AI coding agents. Hybrid search (BM25 + semantic + LLM reranking) across past sessions, codebase, notes, and daily logs.
+
+## Slash Commands
+
+| Command | When |
+|---------|------|
+| `/nano-brain-init` | First-time workspace setup |
+| `/nano-brain-status` | Health check, embedding progress |
+| `/nano-brain-reindex` | After branch switch, pull, or major changes |
+
+## When to Use Memory
+
+**Before work:** Recall past decisions, patterns, debugging insights, cross-session context.
+**After work:** Save key decisions, architecture choices, non-obvious fixes, domain knowledge.
+
+## Access Methods: MCP vs CLI
+
+nano-brain can be accessed via **MCP tools** (when the MCP server is configured) or **CLI** (always available).
+
+**Detection:** Try calling `memory_status` MCP tool first. If it fails with "MCP server not found", fall back to CLI.
+
+### MCP Tools (preferred when available)
+
+| Need | MCP Tool |
+|------|----------|
+| Exact keyword (error msg, function name) | `memory_search` via `skill_mcp(mcp_name="nano-brain", tool_name="memory_search")` |
+| Conceptual ("how does auth work") | `memory_vsearch` via `skill_mcp(mcp_name="nano-brain", tool_name="memory_vsearch")` |
+| Best quality, complex question | `memory_query` via `skill_mcp(mcp_name="nano-brain", tool_name="memory_query")` |
+| Retrieve specific doc | `memory_get` / `memory_multi_get` |
+| Save insight or decision (append to daily log) | `memory_write` via `skill_mcp(mcp_name="nano-brain", tool_name="memory_write")` |
+| Set/update a keyed memory (overwrites previous) | `memory_set` via `skill_mcp(mcp_name="nano-brain", tool_name="memory_set")` |
+| Delete a keyed memory | `memory_delete` via `skill_mcp(mcp_name="nano-brain", tool_name="memory_delete")` |
+| List all keyed memories | `memory_keys` via `skill_mcp(mcp_name="nano-brain", tool_name="memory_keys")` |
+| Check health | `memory_status` via `skill_mcp(mcp_name="nano-brain", tool_name="memory_status")` |
+| Rescan source files | `memory_index_codebase` |
+| Refresh all indexes | `memory_update` |
+
+### CLI Fallback (always available)
+
+When MCP server is not available, use the CLI via Bash tool:
+
+| Need | CLI Command |
+|------|-------------|
+| Best quality search (hybrid: BM25 + vector + reranking) | `npx nano-brain query "search terms"` |
+| Search with collection filter | `npx nano-brain query "terms" -c codebase` |
+| Search with more/fewer results | `npx nano-brain query "terms" -n 20` |
+| Show full content of results | `npx nano-brain query "terms" --full` |
+| Check health & stats | `npx nano-brain status` |
+| Initialize workspace | `npx nano-brain init --root=/path/to/workspace` |
+| Generate embeddings | `npx nano-brain embed` |
+| Harvest sessions | `npx nano-brain harvest` |
+| List collections | `npx nano-brain collection list` |
+
+**CLI limitations vs MCP:**
+- CLI only has `query` (unified hybrid search) — no separate `search` (BM25-only) or `vsearch` (vector-only)
+- CLI cannot `write` notes — use MCP or manually create files in `~/.nano-brain/memory/`
+- CLI cannot `get` specific docs by ID — use `query` with specific terms instead
+
+**Default:** Use `npx nano-brain query "..."` — it combines BM25 + vector + reranking for best results.
+
+## Collection Filtering
+
+Works with both MCP and CLI (`-c` flag):
+
+- `codebase` — source files only
+- `sessions` — past AI sessions only
+- `memory` — curated notes only
+- Omit — search everything (recommended)
+
+## Memory vs Native Tools
+
+Memory excels at **recall and semantics** — past sessions, conceptual search, cross-project knowledge.
+Native tools (grep, ast-grep, glob) excel at **precise code patterns** — exact matches, AST structure.
+
+**They are complementary.** Use both.

package/skills/nano-brain/skill.json

@@ -0,0 +1,15 @@
+{
+    "name": "nano-brain",
+    "version": "1.0.0",
+    "description": "Persistent memory for AI coding agents. Hybrid search (BM25 + semantic + LLM reranking) across past sessions, codebase, notes, and daily logs.",
+    "compatibility": "OpenCode",
+    "agent": null,
+    "commands": [],
+    "tags": [
+        "memory",
+        "persistence",
+        "search",
+        "context",
+        "sessions"
+    ]
+}

package/skills/pdf/SKILL.md

@@ -0,0 +1,303 @@
+---
+name: pdf
+description: "Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms. Use when filling PDF forms or programmatically processing, generating, or analyzing PDF documents."
+compatibility: "OpenCode"
+metadata:
+  author: openclaw/skillmd
+  version: "1.0.0"
+---
+
+# PDF Processing Guide
+
+## When This Skill Activates
+
+Activate when the user asks to:
+- Extract text or tables from PDFs
+- Create, merge, split, or rotate PDFs
+- Add watermarks or password protection
+- OCR scanned PDFs
+- Fill PDF forms
+- Convert PDFs to text
+
+## Quick Start
+```python
+from pypdf import PdfReader, PdfWriter
+
+# Read a PDF
+reader = PdfReader("document.pdf")
+print(f"Pages: {len(reader.pages)}")
+
+# Extract text
+text = ""
+for page in reader.pages:
+    text += page.extract_text()
+```
+
+## Python Libraries
+
+### pypdf - Basic Operations
+
+#### Merge PDFs
+```python
+from pypdf import PdfWriter, PdfReader
+
+writer = PdfWriter()
+for pdf_file in ["doc1.pdf", "doc2.pdf", "doc3.pdf"]:
+    reader = PdfReader(pdf_file)
+    for page in reader.pages:
+        writer.add_page(page)
+
+with open("merged.pdf", "wb") as output:
+    writer.write(output)
+```
+
+#### Split PDF
+```python
+reader = PdfReader("input.pdf")
+for i, page in enumerate(reader.pages):
+    writer = PdfWriter()
+    writer.add_page(page)
+    with open(f"page_{i+1}.pdf", "wb") as output:
+        writer.write(output)
+```
+
+#### Rotate Pages
+```python
+reader = PdfReader("input.pdf")
+writer = PdfWriter()
+
+page = reader.pages[0]
+page.rotate(90)  # Rotate 90 degrees clockwise
+writer.add_page(page)
+
+with open("rotated.pdf", "wb") as output:
+    writer.write(output)
+```
+
+#### Extract Metadata
+```python
+reader = PdfReader("document.pdf")
+meta = reader.metadata
+print(f"Author: {meta.author}")
+print(f"Title: {meta.title}")
+print(f"Subject: {meta.subject}")
+print(f"Creator: {meta.creator}")
+```
+
+### pdfplumber - Text and Table Extraction
+
+#### Extract Text
+```python
+import pdfplumber
+
+with pdfplumber.open("document.pdf") as pdf:
+    for page in pdf.pages:
+        text = page.extract_text()
+        print(text)
+```
+
+#### Extract Tables
+```python
+with pdfplumber.open("document.pdf") as pdf:
+    for i, page in enumerate(pdf.pages):
+        tables = page.extract_tables()
+        for j, table in enumerate(tables):
+            print(f"Table {j+1} on page {i+1}:")
+            for row in table:
+                print(row)
+```
+
+#### Extract Tables to DataFrame
+```python
+import pdfplumber
+import pandas as pd
+
+with pdfplumber.open("document.pdf") as pdf:
+    page = pdf.pages[0]
+    table = page.extract_table()
+    df = pd.DataFrame(table[1:], columns=table[0])
+    print(df)
+```
+
+### reportlab - Create PDFs
+
+#### Simple PDF
+```python
+from reportlab.lib.pagesizes import letter
+from reportlab.pdfgen import canvas
+
+c = canvas.Canvas("hello.pdf", pagesize=letter)
+width, height = letter
+
+c.drawString(100, height - 100, "Hello World!")
+c.line(100, height - 140, 400, height - 140)
+c.save()
+```
+
+#### Multi-page with Platypus
+```python
+from reportlab.lib.pagesizes import letter
+from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer
+from reportlab.lib.styles import getSampleStyleSheet
+
+doc = SimpleDocTemplate("report.pdf", pagesize=letter)
+styles = getSampleStyleSheet()
+story = []
+
+story.append(Paragraph("Report Title", styles['Title']))
+story.append(Spacer(1, 12))
+story.append(Paragraph("This is the body text.", styles['Normal']))
+
+doc.build(story)
+```
+
+## Command-Line Tools
+
+### pdftotext (poppler-utils)
+```bash
+# Extract text
+pdftotext input.pdf output.txt
+
+# Preserve layout
+pdftotext -layout input.pdf output.txt
+
+# Specific pages
+pdftotext -f 1 -l 5 input.pdf output.txt
+```
+
+### qpdf
+```bash
+# Merge PDFs
+qpdf --empty --pages file1.pdf file2.pdf -- merged.pdf
+
+# Split pages
+qpdf input.pdf --pages . 1-5 -- pages1-5.pdf
+
+# Rotate pages
+qpdf input.pdf output.pdf --rotate=+90:1
+
+# Remove password
+qpdf --password=mypassword --decrypt encrypted.pdf decrypted.pdf
+
+# Linearize (optimize for web)
+qpdf --linearize input.pdf output.pdf
+```
+
+## Common Tasks
+
+### OCR Scanned PDFs
+```python
+import pytesseract
+from pdf2image import convert_from_path
+
+images = convert_from_path('scanned.pdf')
+text = ""
+for i, image in enumerate(images):
+    text += f"Page {i+1}:\n"
+    text += pytesseract.image_to_string(image)
+    text += "\n\n"
+```
+
+### Add Watermark
+```python
+from pypdf import PdfReader, PdfWriter
+
+watermark = PdfReader("watermark.pdf").pages[0]
+reader = PdfReader("document.pdf")
+writer = PdfWriter()
+
+for page in reader.pages:
+    page.merge_page(watermark)
+    writer.add_page(page)
+
+with open("watermarked.pdf", "wb") as output:
+    writer.write(output)
+```
+
+### Password Protection
+```python
+from pypdf import PdfReader, PdfWriter
+
+reader = PdfReader("input.pdf")
+writer = PdfWriter()
+
+for page in reader.pages:
+    writer.add_page(page)
+
+writer.encrypt("userpassword", "ownerpassword")
+
+with open("encrypted.pdf", "wb") as output:
+    writer.write(output)
+```
+
+### Fill PDF Forms
+```python
+from pypdf import PdfReader, PdfWriter
+
+reader = PdfReader("form.pdf")
+writer = PdfWriter()
+writer.append(reader)
+
+# Get form field names
+fields = reader.get_fields()
+for name, field in fields.items():
+    print(f"Field: {name}, Type: {field.get('/FT')}")
+
+# Fill fields
+writer.update_page_form_field_values(
+    writer.pages[0],
+    {"field_name": "value", "another_field": "another_value"}
+)
+
+with open("filled_form.pdf", "wb") as output:
+    writer.write(output)
+```
+
+### PDF to Images
+```python
+from pdf2image import convert_from_path
+
+# Convert all pages
+images = convert_from_path('document.pdf', dpi=300)
+for i, image in enumerate(images):
+    image.save(f'page_{i+1}.png', 'PNG')
+
+# Convert specific pages
+images = convert_from_path('document.pdf', first_page=1, last_page=3)
+```
+
+## Installation Commands
+
+```bash
+# Core libraries
+pip install pypdf pdfplumber reportlab
+
+# OCR support
+pip install pytesseract pdf2image
+# Also needs: apt-get install tesseract-ocr poppler-utils
+
+# CLI tools
+apt-get install poppler-utils qpdf
+
+# All at once
+pip install pypdf pdfplumber reportlab pytesseract pdf2image
+```
+
+## Quick Reference
+
+| Task | Best Tool | Command/Code |
+|------|-----------|--------------|
+| Read/extract text | pdfplumber | `page.extract_text()` |
+| Extract tables | pdfplumber | `page.extract_tables()` |
+| Merge PDFs | pypdf | `writer.add_page(page)` |
+| Split PDFs | pypdf | One page per PdfWriter |
+| Rotate pages | pypdf | `page.rotate(90)` |
+| Create PDFs | reportlab | Canvas or Platypus |
+| Fill forms | pypdf | `update_page_form_field_values()` |
+| Add watermark | pypdf | `page.merge_page(watermark)` |
+| Password protect | pypdf | `writer.encrypt()` |
+| OCR scanned PDFs | pytesseract + pdf2image | Convert to image first |
+| CLI text extract | poppler-utils | `pdftotext input.pdf` |
+| CLI merge/split | qpdf | `qpdf --empty --pages ...` |
+| PDF to images | pdf2image | `convert_from_path()` |
+| Extract metadata | pypdf | `reader.metadata` |

package/skills/pdf/skill.json

@@ -0,0 +1,17 @@
+{
+    "name": "pdf",
+    "version": "1.0.0",
+    "description": "PDF manipulation toolkit \u2014 extract text/tables, create, merge, split, rotate, OCR, fill forms, watermark, and password protect",
+    "compatibility": "OpenCode",
+    "agent": null,
+    "commands": [],
+    "tags": [
+        "pdf",
+        "extract",
+        "merge",
+        "ocr",
+        "forms",
+        "reportlab",
+        "pypdf"
+    ]
+}

package/skills/rtk/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: rtk
+description: "Token optimizer for AI coding agents. Wraps common CLI commands with rtk to reduce LLM token consumption by 60-90%."
+compatibility: "OpenCode with RTK binary installed"
+metadata:
+  author: Sisyphus
+  version: "1.0.0"
+---
+
+# RTK — Rust Token Killer
+
+**Purpose**: Reduce token consumption by 60-90% on shell commands. RTK filters and compresses command output before it reaches your context.
+
+## When This Skill Activates
+
+This skill is loaded automatically. Once active, **always** prefix supported commands with `rtk`.
+
+## Command Mappings (MANDATORY)
+
+When running shell commands via Bash tool, use `rtk` prefix for these commands:
+
+| Instead of | Use | Savings |
+|-----------|-----|---------|
+| `git status` | `rtk git status` | ~80% |
+| `git diff` | `rtk git diff` | ~75% |
+| `git log` | `rtk git log` | ~80% |
+| `git add/commit/push/pull` | `rtk git add/commit/push/pull` | ~90% |
+| `ls` / `ls -la` | `rtk ls` | ~80% |
+| `cat file` | `rtk read file` | ~70% |
+| `grep pattern .` | `rtk grep pattern .` | ~80% |
+| `rg pattern` | `rtk grep pattern .` | ~80% |
+| `npm test` / `cargo test` / `pytest` | `rtk test <cmd>` | ~90% |
+| `npm run build` / `cargo build` | `rtk err <cmd>` | ~80% |
+| `gh pr list/view` | `rtk gh pr list/view` | ~70% |
+| `docker ps` | `rtk docker ps` | ~80% |
+| `eslint` / `tsc` | `rtk lint` / `rtk tsc` | ~80% |
+
+## Searching Inside `node_modules` / Ignored Directories
+
+By default, `rtk grep` respects `.gitignore` rules — meaning `node_modules`, `.nuxt`, `dist`, etc. are **excluded**. This is the right behavior 99% of the time.
+
+When you **need** to search inside ignored directories (debugging a library, checking an API signature, tracing a dependency bug):
+
+```bash
+# Search all files including node_modules (--no-ignore bypasses .gitignore)
+rtk grep "defineStore" . --no-ignore
+
+# Search a specific package only (combine --no-ignore with --glob)
+rtk grep "defineStore" . --no-ignore --glob 'node_modules/pinia/**'
+```
+
+**What does NOT work:**
+- `rtk grep "pattern" node_modules/pinia/` — still excluded even with direct path
+- `rtk grep "pattern" . --glob 'node_modules/**'` — glob alone doesn't override .gitignore
+
+**Key flag: `--no-ignore`** — this is the ONLY way to search ignored directories with rtk grep.
+
+### Other useful `rtk grep` flags
+
+```bash
+rtk grep "pattern" . -t ts          # Filter by file type (ts, py, rust, etc.)
+rtk grep "pattern" . -m 100         # Increase max results (default: 50)
+rtk grep "pattern" . -u             # Ultra-compact mode (even fewer tokens)
+rtk grep "pattern" . -l 120         # Max line length before truncation (default: 80)
+```
+
+## Commands to NOT Wrap
+
+Do NOT prefix these with `rtk` (unsupported or counterproductive):
+
+- `npx`, `npm install`, `pip install` (package managers)
+- `node`, `python3`, `ruby` (interpreters)
+- `nano-brain`, `openspec`, `opencode` (custom tools)
+- Heredocs (`<<EOF`)
+- Piped commands (`cmd1 | cmd2`) — wrap only the first command if applicable
+- Commands already prefixed with `rtk`
+
+## How RTK Works
+
+```
+Without RTK:  git status → 50 lines raw output → 2,000 tokens
+With RTK:     rtk git status → "3 modified, 1 untracked ✓" → 200 tokens
+```
+
+RTK runs the real command, then filters/compresses the output. The agent sees a compact summary instead of verbose raw output.
+
+## Detection
+
+Before using RTK commands, verify it's installed:
+```bash
+rtk --version
+```
+
+If `rtk` is not found, skip this skill — run commands normally without the `rtk` prefix.
+
+## Token Savings Reference
+
+Typical 30-min coding session:
+- Without RTK: ~150,000 tokens
+- With RTK: ~45,000 tokens
+- **Savings: ~70%**
+
+Biggest wins: test output (`rtk test` — 90%), git operations (`rtk git` — 80%), file reading (`rtk read` — 70%).

package/skills/rtk/skill.json

@@ -0,0 +1,15 @@
+{
+    "name": "rtk",
+    "version": "1.0.0",
+    "description": "Token optimizer for AI coding agents. Wraps common CLI commands with rtk to reduce LLM token consumption by 60-90%.",
+    "compatibility": "OpenCode with RTK binary installed",
+    "agent": null,
+    "commands": [],
+    "tags": [
+        "rtk",
+        "token-saving",
+        "optimization",
+        "cli",
+        "productivity"
+    ]
+}