Skip to content
Back to search

shokunin

職人 Shokunin 62 AI agent skills for OpenCode, Claude Code, Cursor, Windsurf. ChromaDB memory, MCP servers, declarative self-updates. Multi-model, open source, zero cost.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/eliasoulkadi--shokunin/badge.svg)](/listings/eliasoulkadi--shokunin)

HTML

<a href="/listings/eliasoulkadi--shokunin"><img src="/api/listings/eliasoulkadi--shokunin/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

**Windows:**

# 1. Install
irm https://raw.githubusercontent.com/EliasOulkadi/shokunin/master/install.ps1 | iex

# 2. (Optional) Free NVIDIA API key, or skip, OpenCode Go works without it
#    https://build.nvidia.com/

# 3. Start OpenCode (with memory capture)
.\run-opencode.ps1

# Or without memory capture (simple mode):
opencode

**Linux:**

# 1. Install
bash <(curl -sL https://raw.githubusercontent.com/EliasOulkadi/shokunin/master/install.sh)

# 2. (Optional) Free NVIDIA API key, or skip, OpenCode Go works without it
#    https://build.nvidia.com/

# Quick Start (non-interactive):
bash <(curl -sL https://raw.githubusercontent.com/EliasOulkadi/shokunin/master/install.sh) -y

# 3. Reload shell and start OpenCode
source ~/.bashrc
opencode

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 248 lines · 7 findings marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # 職人 · Shokunin
  2. [![CI](https://github.com/EliasOulkadi/shokunin/actions/workflows/ci.yml/badge.svg)](https://github.com/EliasOulkadi/shokunin/actions/workflows/ci.yml)
  3. [![Memory Tests](https://github.com/EliasOulkadi/shokunin/actions/workflows/memory-tests.yml/badge.svg)](https://github.com/EliasOulkadi/shokunin/actions/workflows/memory-tests.yml)
  4. [![Release](https://github.com/EliasOulkadi/shokunin/actions/workflows/release.yml/badge.svg)](https://github.com/EliasOulkadi/shokunin/actions/workflows/release.yml)
  5. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
  6. [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
  7. [![Windows](https://img.shields.io/badge/Windows-11-0078D6?logo=windows)](https://www.microsoft.com/windows)
  8. [![Linux](https://img.shields.io/badge/Linux-FCC624?logo=linux&logoColor=black)](https://github.com/EliasOulkadi/shokunin)
  9. [![OpenCode](https://img.shields.io/badge/OpenCode-6B46C1?logo=openai)](https://opencode.ai)
  10. [![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/EliasOulkadi/shokunin/graphs/commit-activity)
  11. [![Changelog](https://img.shields.io/badge/Changelog-CHANGELOG.md-blue)](CHANGELOG.md)
  12. [![Architecture](https://img.shields.io/badge/Architecture-docs/ARCHITECTURE.md-blue)](docs/ARCHITECTURE.md)
  13. **62 engineering skills + persistent AI memory. One command. Zero servers.**
  14. **v4.2.3** adds freshness decay (time-weighted memory), claim verification (verify_file_path MCP tool), 12 MCP tools (was 8), and 30+ bug fixes.
  15. > *職人 (shokunin) means artisan in Japanese. These skills aim for that standard: every detail crafted, every edge case handled, every workflow automated.*
  16. ```powershell
  17. # One-command install (Windows)
  18. irm https://raw.githubusercontent.com/EliasOulkadi/shokunin/master/install.ps1 | iex
  19. ```
  20. ```bash
  21. # One-command install (Linux)
  22. bash <(curl -sL https://raw.githubusercontent.com/EliasOulkadi/shokunin/master/install.sh)
    • Note: Runs a downloaded script through process substitution (bash <(curl …))
    • Line 29 on GitHub
  23. ```
  24. ```powershell
  25. # Skills-only install (Windows - no ChromaDB, no MCP)
  26. irm https://raw.githubusercontent.com/EliasOulkadi/shokunin/master/install-skills.ps1 | iex
  27. ```
  28. ```bash
  29. # Skills-only install (Linux)
  30. bash <(curl -sL https://raw.githubusercontent.com/EliasOulkadi/shokunin/master/install-skills.sh)
    • Note: Runs a downloaded script through process substitution (bash <(curl …))
    • Line 39 on GitHub
  31. ```
  32. ## Ecosystem
  33. ```
  34. OpenCode + VS Code + WezTerm
  35. 62 skills + superpowers plugin + 4 subagents
  36. MCP servers: filesystem, fetch, memory + ChromaDB
  37. AI: OpenCode Go (default) + Ollama (local fallback)
  38. Update system: declarative manifest with drift detection
  39. Windows (PowerShell) + Linux (bash)
  40. ```
  41. ## Skills
  42. 62 skills across 10 domains. Each skill teaches the agent how to handle a specific domain: with decision tables, error patterns, production checklists, anti-patterns, and cited sources. Not generic prompts. Real engineering guides.
  43. The Docker skill is 1,422 words with a multi-stage Node.js template, BuildKit cache optimization, distroless base images, and CVE scanning. The auth skill references OWASP directly. The database one has real EXPLAIN ANALYZE output. Frontend skills include Emil Kowalski patterns (Sonner, Vaul), Paul Bakaus principles (Impeccable), and Leon Lin variance engines (Taste). Skills are validated by CI on every push: frontmatter, workflow, error handling, sources. All mandatory.
  44. | Domain | Skills | Version |
  45. |--------|--------|---------|
  46. | **Infrastructure** | docker, kubernetes, terraform, ci-cd, db-admin | v4.0 |
  47. | **Backend** | auth-architect, api-forge, db-sculptor, error-handler | v4.0 |
  48. | **Frontend** | component-forge, responsive-engine, motion-craft, landing-craft, aesthetic-web, ui-ux-pro-max, emil-design-eng, impeccable, taste, taste-soft, taste-minimalist | v4.0 |
  49. | **Mobile** | flutter, react-native | v4.0 |
  50. | **Quality** | test-commander, performance-profiler, code-review, comprehensive-review, cross-review, zen-review, zen-comprehensive-review | v4.0 |
  51. | **Content & Business** | communication, content-marketing, business-proposals, seo-geo, translate-craft, documentation | v4.0 |
  52. | **Documents** | kami (PDF generator), portfolio-auto, kagen (AI images) | v4.0 |
  53. | **Productivity** | git-workflow, windows-powershell, strategy, brand-design, runbook-gen, finance, legal-counsel, whendone-plus | v4.0 |
  54. | **AI Agents** | agent-browser, agent-tools, find-skills, skill-creator, research, humanize | v4.0 |
  55. | **System** | memory, chromadb, shokunin-update, init, efficient-coding, senior-engineer, plan, playwright, neon-postgres, web-security | v4.2 |
  56. Each skill includes: trigger-optimized descriptions, procedural workflows, error handling, production checklists, anti-patterns, cited sources. Advanced skills also include executable scripts, reference files, and reusable templates.
  57. ## What You Get
  58. | Component | Purpose |
  59. |-----------|---------|
  60. | **62 SKILL.md files** | Domain expertise that auto-activates |
  61. | **OpenCode config** | MCP servers, subagents, superpowers plugin |
  62. | **ChromaDB memory** | Persistent context across sessions (v4.0, 3-layer capture, structured data) |
  63. | **CLAUDE.md + AGENTS.md** | Mandatory memory instructions: context search on every start |
  64. | **Auto-save wrapper** | Console buffer capture on exit, saves to ChromaDB + markdown |
  65. | **Memory test suite** | One-command validation of all memory components |
  66. | **PowerShell profile** | 20+ aliases, oh-my-posh, autocomplete |
  67. | **Windows scheduler** | Weekly cleanup and memory backup |
  68. | **Bookmarklet** | Send web pages to OpenCode |
  69. | **Dashboard** | Local ecosystem status viewer |
  70. | **WezTerm config** | GPU terminal with Catppuccin theme |
  71. | **ChromaDB (SQLite-backed)** | Zero-install local vector database |
  72. ## Requirements
  73. ### Minimum
  74. | Dependency | Version | Notes |
  75. |------------|---------|-------|
  76. | **OS** | Windows 10/11 or Linux | **Linux:** requires `bash` 4+, not `sh`. Run `bash --version` to verify. |
  77. | **Node.js** | ≥ 18 | Includes `npm`. Run `node --version` to verify. |
  78. | **Python** | ≥ 3.11 | Run `python3 --version` to verify. |
  79. | **Git** | ≥ 2.x | Run `git --version` to verify. |
  80. ### Linux: additional dependencies
  81. | Dependency | Why | Install |
  82. |------------|-----|---------|
  83. | `python3-pip` | Required for ChromaDB. Not included by default on Ubuntu/Debian. | `sudo apt-get install -y python3-pip` |
  84. | `build-essential` + `python3-dev` | Needed to compile ChromaDB native wheels on some systems. | `sudo apt-get install -y build-essential python3-dev` |
  85. | `cron` daemon | Required for automated weekly maintenance (optional). | `sudo systemctl enable --now cron` |
  86. > **Ubuntu 24.04+:** PEP 668 blocks global `pip install` by default. The installer handles this automatically with `--break-system-packages`. If you run into issues, see the Troubleshooting section below.
  87. ### Windows: additional notes
  88. - PowerShell 5.1+ required. Run `$PSVersionTable.PSVersion` to verify.
  89. - Execution policy must allow scripts: `Set-ExecutionPolicy RemoteSigned -Scope CurrentUser`
  90. ## Quick Start
  91. **Windows:**
  92. ```powershell
  93. # 1. Install
  94. irm https://raw.githubusercontent.com/EliasOulkadi/shokunin/master/install.ps1 | iex
  95. # 2. (Optional) Free NVIDIA API key, or skip, OpenCode Go works without it
  96. # https://build.nvidia.com/
  97. # 3. Start OpenCode (with memory capture)
  98. .\run-opencode.ps1
  99. # Or without memory capture (simple mode):
  100. opencode
  101. ```
  102. **Linux:**
  103. ```bash
  104. # 1. Install
  105. bash <(curl -sL https://raw.githubusercontent.com/EliasOulkadi/shokunin/master/install.sh)
    • Note: Runs a downloaded script through process substitution (bash <(curl …))
    • Line 134 on GitHub
  106. # 2. (Optional) Free NVIDIA API key, or skip, OpenCode Go works without it
  107. # https://build.nvidia.com/
  108. # Quick Start (non-interactive):
  109. bash <(curl -sL https://raw.githubusercontent.com/EliasOulkadi/shokunin/master/install.sh) -y
    • Note: Runs a downloaded script through process substitution (bash <(curl …))
    • Line 140 on GitHub
  110. # 3. Reload shell and start OpenCode
  111. source ~/.bashrc
  112. opencode
  113. ```
  114. ## Memory System v4.2.3
  115. Multi-strategy recall (vector + BM25 + temporal + reciprocal rank fusion). Session management with explicit continue (no guessing which session to resume).
  116. - **Freshness decay**: exponential recency blending, old memories fade over 30-day half-life so stale claims don't drown out recent context
  117. - **Claim verification**: `verify_file_path` MCP tool validates file paths from old memory before the agent acts on them, treating memory as claims from a frozen point in time, not facts
  118. - **12 MCP tools** (up from 8): store_context, search_context, get_session_summary, multi_search_context (vector+BM25+RRF+temporal), consolidate_memories, list_sessions, continue_session, save_message, verify_file_path, memory_index, memory_stats, memory_forget
  119. ```bash
  120. # List recent sessions
  121. python ~/.shokunin/scripts/chroma-helper.py session list 5
  122. # Continue a specific session (loads full context)
  123. python ~/.shokunin/scripts/chroma-helper.py session continue <session_id>
  124. # Search across all memory
  125. python ~/.shokunin/scripts/chroma-helper.py recall "topic"
  126. ```
  127. All data stored at `~/.shokunin/memory/`. No cloud, no telemetry, no subscriptions.
  128. ```powershell
  129. # Test the memory system
  130. .\test-memory.ps1
  131. # Validate all memory components
  132. .\memory-healthcheck.ps1
  133. ```
  134. - [Technical Overview v4.2.3](docs/Shokunin-Technical-Overview-v4.2.3.pdf) - Full ecosystem overview, multi-strategy recall, Hindsight comparison
  135. ## Troubleshooting
  136. | Problem | Cause | Solution |
  137. |---------|-------|----------|
  138. | Installer hangs on `Continue? (y/n)` | `read -p` blocks in non-interactive mode | Use `bash install.sh -y` or run directly in a terminal |
  139. | `pip3: command not found` | `python3-pip` not installed | `sudo apt-get install python3-pip` |
  140. | `externally-managed-environment` | PEP 668 on Ubuntu 24.04+ | The installer applies `--break-system-packages` automatically. If it fails, run manually: `python3 -m pip install chromadb --break-system-packages` |
  141. | `Cannot uninstall typing_extensions` | Debian-packaged package missing RECORD file | `python3 -m pip install chromadb --break-system-packages --ignore-installed typing-extensions` |
  142. | MCP fetch/filesystem: `Connection closed` | OpenCode runtime config issue | Verify `node` is in PATH and check `~/.config/opencode/opencode.json` |
  143. | `npm install -g opencode` fails | Missing npm or insufficient permissions | Install npm first, or run `sudo npm install -g opencode` |
  144. | ChromaDB fails to install | Missing build dependencies | `sudo apt-get install -y build-essential python3-dev` |
  145. ## Commands
  146. **OpenCode custom commands:** `/save` (save session to ChromaDB), `/load` (load previous session), `/status` (healthcheck).
  147. **Windows:**
  148. ```powershell
  149. .\run-opencode.ps1 # Start AI session (with memory capture)
  150. opencode # Start AI session (simple mode)
  151. .\memory-healthcheck.ps1 # Validate all memory components
  152. gst, ga, gc "msg", gp, gl # Git aliases
  153. ni, nrd, nrb, nt # npm aliases
  154. dps, dlog # Docker aliases
  155. mkcd, touch, which, admin # Utility aliases
  156. ```
  157. **Linux:**
  158. ```bash
  159. opencode # Start AI session (with memory capture)
  160. ./memory-healthcheck.sh # Validate all memory components
  161. gst, ga, gc "msg", gp, gl # Git aliases
  162. ni, nrd, nrb, nt # npm aliases
  163. dps, dlog # Docker aliases
  164. mkcd, which # Utility functions
  165. ```
  166. ## Compatibility
  167. The ecosystem works across multiple AI coding runtimes. The core (skills, memory, scripts) is runtime-agnostic. Only MCP server configuration and instruction files differ.
  168. | Runtime | Skills | Memory | MCP | Scripts | Config template |
  169. |---------|--------|--------|-----|---------|-----------------|
  170. | **OpenCode** | Native | Native | .pack/opencode.json | .ps1 + .sh | Built-in |
  171. | **Claude Code** | Reads SKILL.md | Via MCP | .pack/templates/claude-code.json | .ps1 + .sh | Copy template |
  172. | **Cline** (VS Code) | Reads SKILL.md | Via MCP | .pack/templates/cline-settings.json | .ps1 + .sh | Add to settings.json |
  173. | **Cursor** | Reads SKILL.md | Via rules | .pack/templates/cursor-mcp.json | .ps1 + .sh | Copy to .cursor/ |
  174. | **Continue.dev** | Reads SKILL.md | Via rules | .pack/templates/continue-config.yaml | .ps1 + .sh | Copy to .continue/ |
  175. | **Windsurf** | Reads SKILL.md | Via rules | .pack/templates/windsurf-mcp.json.tpl | .sh | Copy template |
  176. ### Setup per runtime
  177. **Claude Code:** Copy `.pack/templates/claude-code.json` to project root as `claude.json` or configure via CLAUDE.md.
  178. **Cline:** Add the `mcpServers` block from `.pack/templates/cline-settings.json` to VS Code's `settings.json`. Copy `.pack/rules/cline-memory.md` as `.clinerules`.
  179. **Cursor:** Configure MCP servers in Cursor Settings > MCP using `.pack/templates/cursor-mcp.json`. Copy `.pack/rules/cursor-memory.mdc` to `.cursor/rules/memory.mdc`.
  180. **Continue.dev:** Copy `.pack/templates/continue-config.yaml` to `.continue/config.yaml`. Add `.pack/rules/continue-memory.md` to `.continue/rules/`.
  181. **Windsurf:** Copy the MCP config from `.pack/templates/windsurf-mcp.json.tpl`. Copy `.pack/rules/windsurf-memory.md` to `.windsurf/rules/memory.md`.
  182. ## Links
  183. - **GitHub** github.com/EliasOulkadi/shokunin
  184. - **Website** eliasoulkadi.github.io/shokunin
  185. - [Shokunin Technical Overview](/docs/Shokunin-Technical-Overview-v4.2.3.pdf)
  186. ## License
  187. MIT free as in freedom, free as in zero cost.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.