職人 · Shokunin

62 engineering skills + persistent AI memory. One command. Zero servers.

v4.2.3 adds freshness decay (time-weighted memory), claim verification (verify_file_path MCP tool), 9 MCP tools (was 8), and 30+ bug fixes.

職人 (shokunin) means artisan in Japanese. These skills aim for that standard: every detail crafted, every edge case handled, every workflow automated.

# One-command install (Windows)
irm https://raw.githubusercontent.com/EliasOulkadi/shokunin/master/install.ps1 | iex

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

# Skills-only install (Windows — no ChromaDB, no MCP)
irm https://raw.githubusercontent.com/EliasOulkadi/shokunin/master/install-skills.ps1 | iex

# Skills-only install (Linux)
bash <(curl -sL https://raw.githubusercontent.com/EliasOulkadi/shokunin/master/install-skills.sh)

Ecosystem

OpenCode + VS Code + WezTerm
  62 skills + superpowers plugin + 4 subagents
  MCP servers: filesystem, fetch, memory + ChromaDB
  AI: OpenCode Go (default) + Ollama (local fallback)
  Update system: declarative manifest with drift detection
  Windows (PowerShell) + Linux (bash)

Skills

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.

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.

Domain	Skills	Version
Infrastructure	docker, kubernetes, terraform, ci-cd, db-admin	v4.0
Backend	auth-architect, api-forge, db-sculptor, error-handler	v4.0
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
Mobile	flutter, react-native	v4.0
Quality	test-commander, performance-profiler, code-review, comprehensive-review, cross-review, zen-review, zen-comprehensive-review	v4.0
Content & Business	communication, content-marketing, business-proposals, seo-geo, translate-craft, documentation	v4.0
Documents	kami (PDF generator), portfolio-auto, kagen (AI images)	v4.0
Productivity	git-workflow, windows-powershell, strategy, brand-design, runbook-gen, finance, legal-counsel, whendone-plus	v4.0
AI Agents	agent-browser, agent-tools, find-skills, skill-creator, research, humanize	v4.0
System	memory, chromadb, shokunin-update, init, efficient-coding, senior-engineer, plan, playwright, neon-postgres, web-security	v4.2

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.

What You Get

Component	Purpose
62 SKILL.md files	Domain expertise that auto-activates
OpenCode config	MCP servers, subagents, superpowers plugin
ChromaDB memory	Persistent context across sessions (v4.0, 3-layer capture, structured data)
CLAUDE.md + AGENTS.md	Mandatory memory instructions: context search on every start
Auto-save wrapper	Console buffer capture on exit, saves to ChromaDB + markdown
Memory test suite	One-command validation of all memory components
PowerShell profile	20+ aliases, oh-my-posh, autocomplete
Windows scheduler	Weekly cleanup and memory backup
Bookmarklet	Send web pages to OpenCode
Dashboard	Local ecosystem status viewer
WezTerm config	GPU terminal with Catppuccin theme
ChromaDB (SQLite-backed)	Zero-install local vector database

Requirements

Minimum

Dependency	Version	Notes
OS	Windows 10/11 or Linux	Linux: requires `bash` 4+, not `sh`. Run `bash --version` to verify.
Node.js	≥ 18	Includes `npm`. Run `node --version` to verify.
Python	≥ 3.11	Run `python3 --version` to verify.
Git	≥ 2.x	Run `git --version` to verify.

Linux: additional dependencies

Dependency	Why	Install
`python3-pip`	Required for ChromaDB. Not included by default on Ubuntu/Debian.	`sudo apt-get install -y python3-pip`
`build-essential` + `python3-dev`	Needed to compile ChromaDB native wheels on some systems.	`sudo apt-get install -y build-essential python3-dev`
`cron` daemon	Required for automated weekly maintenance (optional).	`sudo systemctl enable --now cron`

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.

Windows: additional notes

PowerShell 5.1+ required. Run $PSVersionTable.PSVersion to verify.
Execution policy must allow scripts: Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

Quick Start

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

Memory System v4.2.3

Multi-strategy recall (vector + BM25 + temporal + reciprocal rank fusion). Session management with explicit continue (no guessing which session to resume).

Freshness decay: exponential recency blending — old memories fade over 30-day half-life so stale claims don't drown out recent context
Claim verification: verify_file_path MCP tool validates file paths from old memory before the agent acts on them — treats memory as claims from a frozen point in time, not facts
9 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

# List recent sessions
python ~/.shokunin/scripts/chroma-helper.py session list 5

# Continue a specific session (loads full context)
python ~/.shokunin/scripts/chroma-helper.py session continue <session_id>

# Search across all memory
python ~/.shokunin/scripts/chroma-helper.py recall "topic"

All data stored at ~/.shokunin/memory/. No cloud, no telemetry, no subscriptions.

# Test the memory system
.\test-memory.ps1

# Validate all memory components
.\memory-healthcheck.ps1

Technical Overview v4.2.3 - Full ecosystem overview, multi-strategy recall, Hindsight comparison

Troubleshooting

Problem	Cause	Solution
Installer hangs on `Continue? (y/n)`	`read -p` blocks in non-interactive mode	Use `bash install.sh -y` or run directly in a terminal
`pip3: command not found`	`python3-pip` not installed	`sudo apt-get install python3-pip`
`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`
`Cannot uninstall typing_extensions`	Debian-packaged package missing RECORD file	`python3 -m pip install chromadb --break-system-packages --ignore-installed typing-extensions`
MCP fetch/filesystem: `Connection closed`	OpenCode runtime config issue	Verify `node` is in PATH and check `~/.config/opencode/opencode.json`
`npm install -g opencode` fails	Missing npm or insufficient permissions	Install npm first, or run `sudo npm install -g opencode`
ChromaDB fails to install	Missing build dependencies	`sudo apt-get install -y build-essential python3-dev`

Commands

OpenCode custom commands: /save (save session to ChromaDB), /load (load previous session), /status (healthcheck).

Windows:

.\run-opencode.ps1                    # Start AI session (with memory capture)
opencode                              # Start AI session (simple mode)
.\memory-healthcheck.ps1              # Validate all memory components
gst, ga, gc "msg", gp, gl            # Git aliases
ni, nrd, nrb, nt                       # npm aliases
dps, dlog                               # Docker aliases
mkcd, touch, which, admin             # Utility aliases

Linux:

opencode                              # Start AI session (with memory capture)
./memory-healthcheck.sh               # Validate all memory components
gst, ga, gc "msg", gp, gl            # Git aliases
ni, nrd, nrb, nt                       # npm aliases
dps, dlog                               # Docker aliases
mkcd, which                           # Utility functions

Compatibility

The ecosystem works across multiple AI coding runtimes. The core (skills, memory, scripts) is runtime-agnostic. Only MCP server configuration and instruction files differ.

Runtime	Skills	Memory	MCP	Scripts	Config template
OpenCode	✅ Native	✅ Native	✅ .pack/opencode.json	✅ .ps1 + .sh	Built-in
Claude Code	✅ Reads SKILL.md	✅ Via MCP	✅ .pack/templates/claude-code.json	✅ .ps1 + .sh	Copy template
Cline (VS Code)	✅ Reads SKILL.md	✅ Via MCP	✅ .pack/templates/cline-settings.json	✅ .ps1 + .sh	Add to settings.json
Cursor	✅ Reads SKILL.md	✅ Via rules	✅ .pack/templates/cursor-mcp.json	✅ .ps1 + .sh	Copy to .cursor/
Continue.dev	✅ Reads SKILL.md	✅ Via rules	✅ .pack/templates/continue-config.yaml	✅ .ps1 + .sh	Copy to .continue/
Windsurf	✅ Reads SKILL.md	✅ Via rules	✅ .pack/templates/windsurf-mcp.json	✅ .sh	Copy template

Setup per runtime

Claude Code: Copy .pack/templates/claude-code.json to project root as claude.json or configure via CLAUDE.md.

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.

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.

Continue.dev: Copy .pack/templates/continue-config.yaml to .continue/config.yaml. Add .pack/rules/continue-memory.md to .continue/rules/.

Windsurf: Copy .pack/templates/windsurf-mcp.json MCP config. Copy .pack/rules/windsurf-memory.md to .windsurf/rules/memory.md.

Links

GitHub github.com/EliasOulkadi/shokunin
Website eliasoulkadi.github.io/shokunin
Shokunin Technical Overview

License

MIT free as in freedom, free as in zero cost.

Name		Name	Last commit message	Last commit date
Latest commit History 174 Commits
.github		.github
.pack		.pack
benchmarks		benchmarks
docs		docs
tests		tests
.editorconfig		.editorconfig
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODEOWNERS		CODEOWNERS
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
index.html		index.html
install-skills.ps1		install-skills.ps1
install-skills.sh		install-skills.sh
install.ps1		install.ps1
install.sh		install.sh
llms.txt		llms.txt
og.png		og.png
pyproject.toml		pyproject.toml
requirements-test.txt		requirements-test.txt
robots.txt		robots.txt
sitemap.xml		sitemap.xml
skills.html		skills.html

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

職人 · Shokunin

Ecosystem

Skills

What You Get

Requirements

Minimum

Linux: additional dependencies

Windows: additional notes

Quick Start

Memory System v4.2.3

Troubleshooting

Commands

Compatibility

Setup per runtime

Links

License

About

Uh oh!

Releases 1

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

職人 · Shokunin

Ecosystem

Skills

What You Get

Requirements

Minimum

Linux: additional dependencies

Windows: additional notes

Quick Start

Memory System v4.2.3

Troubleshooting

Commands

Compatibility

Setup per runtime

Links

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages