5uck1ess · 5uck1ess · Apr 11, 2026 · Apr 11, 2026 · Apr 11, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -2,27 +2,30 @@
 
 ## Adding a Workflow
 
-Most command logic lives in YAML workflows executed by the Go engine. Only 6 slash commands remain as tab-completable entry points — everything else is context-activated via skills.
+Most command logic lives in YAML workflows executed by the Go engine. In current Claude Code all skills are tab-completable slash commands — new entry points go in `skills/`, not `commands/` (which is legacy).
 
 1. Create `workflows/my-workflow.yml` with steps, model assignments, and loop/gate definitions
 2. Test with `devkit_start` MCP tool or `devkit workflow my-workflow "input"` from terminal
 3. Optionally add a context-activated skill in `skills/` to auto-trigger it
 
 See `skills/creating-workflows/SKILL.md` for YAML schema reference.
 
-### Adding a Slash Command (rare — only for top-level entry points)
+### Adding a User-Only Entry Point
 
-Only add a command if it needs tab-completion. Most workflows are invoked via MCP tools (`devkit_start`/`devkit_advance`) or context-activated skills.
+For side-effecting actions (install / deploy / setup) that should only run when the user explicitly invokes them, create a skill with `disable-model-invocation: true`:
 
-1. Create `commands/my-command.md` with YAML frontmatter:
+1. Create `skills/my-skill/SKILL.md` with YAML frontmatter:
    ```markdown
    ---
-   description: What this command does.
+   name: my-skill
+   description: What this skill does and when to use it.
+   disable-model-invocation: true
    ---
-   Use `devkit_start` MCP tool with workflow name to execute.
+   # Skill Title
+   Instructions...
    ```
 
-The command name is derived from the filename: `commands/my-command.md` becomes `/devkit:my-command`.
+This makes `/devkit:my-skill` tab-completable but prevents Claude from auto-triggering it — useful for installers (`setup-rules`) and other side-effecting operations. The `commands/` directory is legacy; don't add new files there.
 
 ## Adding a Context-Activated Skill
 
@@ -49,7 +52,7 @@ The skill will be auto-discovered as `devkit:my-skill`.
 
 1. Create a YAML file in `workflows/`
 2. See the `creating-workflows` skill for schema reference
-3. Run with `/devkit:workflow my-workflow`
+3. Run with `/my-workflow` — every workflow has its own tab-completable skill
 
 ## Guidelines
 

diff --git a/README.md b/README.md
@@ -125,18 +125,17 @@ Enforcement (runs automatically):
 
 ## Commands
 
-6 tab-completable slash commands. All other workflows are context-activated via skills (auto-triggered by natural language) or invoked via MCP tools.
+All skills are tab-completable slash commands in current Claude Code. The primary user-facing entry points:
 
 | Command | What it does |
 |---|---|
-| `/tri:review` | Code review from 1-3 agents, consolidated report |
-| `/tri:debug` | Independent root-cause analysis from each agent |
-| `/tri:security` | Security audit with severity-ranked consensus |
-| `/devkit:workflow` | Run any YAML workflow by name |
+| `/tri-review` | Code review from 1-3 agents, consolidated report |
+| `/tri-debug` | Independent root-cause analysis from each agent |
+| `/tri-security` | Security audit with severity-ranked consensus |
 | `/devkit:status` | Health check |
-| `/devkit:setup-rules` | Install language-specific coding rules to `~/.claude/rules/` |
+| `/devkit:setup-rules` | Install language-specific coding rules to `~/.claude/rules/` (user-only — `disable-model-invocation` prevents auto-trigger) |
 
-Tasks like "ship this PR" or "submit a PR" auto-activate the `pr-ready` skill — no slash command needed.
+Every workflow also has a dedicated slash command: `/feature`, `/bugfix`, `/audit`, `/refactor`, `/pr-ready`, `/self-*`, etc. Tasks like "ship this PR" or "submit a PR" also auto-activate the `pr-ready` skill via natural language.
 
 ### Workflows
 
@@ -305,8 +304,8 @@ Terminal usage (devkit workflow <name> "<description>"):
 
 ```
 devkit/
-├── commands/          # 6 slash commands (tab-completable entry points)
-├── skills/            # 36 context-activated skills + _principles.yml
+├── commands/          # Legacy (references/ only); new entry points go in skills/
+├── skills/            # 38 skills (workflow triggers, principles, tools, utilities) + _principles.yml
 ├── agents/            # 6 agents (reviewer, researcher, improver, ...)
 ├── hooks/             # 12 hooks (safety, security, quality gates, workflow enforcement)
 ├── workflows/         # 21 YAML workflow definitions

diff --git a/ROADMAP.md b/ROADMAP.md
@@ -3,9 +3,9 @@
 ## Implemented
 
 - **MCP engine** — Go server exposes `devkit_start`, `devkit_advance`, `devkit_status`, `devkit_list` tools inside Claude Code. Step ordering enforced via MCP tool scoping + PreToolUse hook exit 2. Session state in session.json (hot path, <50ms hook reads) + SQLite (cold history). ~65% token reduction vs old monolithic prompts.
-- **6 slash commands** — Tab-completable entry points for things that need explicit invocation (tri-review, tri-debug, tri-security, status, setup-rules, workflow); 18 former commands now context-activated via skills or invoked via MCP tools (pr-monitor folded into pr-ready workflow; pr-ready is now a natural-language skill)
+- **Skills-first architecture** — All entry points are skills in `skills/` (tab-completable slash commands in current Claude Code). Primary user-facing commands: `/tri-review`, `/tri-debug`, `/tri-security`, `/devkit:status`, `/devkit:setup-rules` (user-only via `disable-model-invocation`). Every workflow also has a dedicated skill for natural-language dispatch. The `commands/` directory is retained for backward compat but empty of new entries — redundant tri-* command files were removed (skills take precedence per Claude Code docs) and the generic `/devkit:workflow <name>` runner was removed since every workflow now has its own slash command (`/feature`, `/bugfix`, etc.).
 - **Deterministic workflow conversion** — All command logic moved from LLM-interpreted markdown to Go-engine-driven YAML workflows; ~3,600 lines of inline logic removed
-- **36 context-activated skills** — 21 workflow trigger skills (feature, bugfix, refactor, audit, research, deep-research, pr-ready, autoloop, test-gen, doc-gen, onboard, tri-review, tri-debug, tri-security, tri-dispatch, self-audit, self-improve, self-lint, self-migrate, self-perf, self-test) + 7 coding principles (executing, clean-code, DRY, YAGNI, dont-reinvent, stuck, scratchpad) + 4 tools (gcli, scrape, screenshot, browser) + 1 meta-orchestration (mega-pr) + 2 content (changelog, adr) + 1 reference (creating-workflows)
+- **38 skills** — 21 workflow trigger skills (feature, bugfix, refactor, audit, research, deep-research, pr-ready, autoloop, test-gen, doc-gen, onboard, tri-review, tri-debug, tri-security, tri-dispatch, self-audit, self-improve, self-lint, self-migrate, self-perf, self-test) + 7 coding principles (executing, clean-code, DRY, YAGNI, dont-reinvent, stuck, scratchpad) + 4 tools (gcli, scrape, screenshot, browser) + 1 meta-orchestration (mega-pr) + 2 content (changelog, adr) + 1 reference (creating-workflows)
 - **Deterministic skill dispatch for every workflow** — Every one of the 21 workflows has a natural-language trigger skill with keyword-rich description. Saying "build a feature", "tri review", "deep research X", etc. deterministically invokes the matching skill, which calls `devkit_start` and the engine enforces every step from there. Closes the entry-gate non-determinism where 11/18 workflows previously had no natural-language path. Skill tool added to the guard allowlist so nested mid-workflow skill dispatch works.
 - **6 agents** — Scoped tool access, worktree isolation, model assignment
 - **12 hooks** — Safety (destructive command blocking, edit-time security patterns, PR gate), observability (audit trail, slop detection, post-validation, subagent verification, language-aware code review), optimization (RTK token compression), workflow enforcement (devkit-guard, devkit-stop-guard)

diff --git a/commands/tri-debug.md b/commands/tri-debug.md
diff --git a/commands/tri-review.md b/commands/tri-review.md
diff --git a/commands/tri-security.md b/commands/tri-security.md
diff --git a/commands/workflow.md b/commands/workflow.md
diff --git a/commands/setup-rules.md → skills/setup-rules/SKILL.md b/commands/setup-rules.md → skills/setup-rules/SKILL.md
@@ -1,5 +1,7 @@
 ---
-description: Install devkit coding rules to ~/.claude/rules/ for language-specific auto-activation
+name: setup-rules
+description: Install devkit coding rules to ~/.claude/rules/ for language-specific auto-activation. Use when the user explicitly asks to set up devkit rules, install language rules, or run /devkit:setup-rules. One-shot installer with side effects (writes to ~/.claude/rules/) — user-only invocation, never auto-triggered.
+disable-model-invocation: true
 ---
 
 # Setup Coding Rules

diff --git a/commands/status.md → skills/status/SKILL.md b/commands/status.md → skills/status/SKILL.md
@@ -1,5 +1,6 @@
 ---
-description: Check devkit health — which external CLIs are installed, which agents are available, and which commands are ready to use.
+name: status
+description: Check devkit health — which external CLIs (codex, gemini, gh, rtk, sg, gcli) are installed, which agents are available, which skills are ready to use. Use when asked about devkit status, "is devkit working?", "what's installed?", "what devkit capabilities do I have?", diagnosing devkit setup issues, or running /devkit:status. Read-only diagnostic, safe to auto-invoke.
 ---
 
 # Devkit Status
@@ -46,35 +47,34 @@ fi
 
 List all agents from `agents/` directory with their model and isolation settings.
 
-### Command Availability
+### Skill Availability
 
-List all commands, marking which ones need external CLIs:
+List all skills from `skills/` directory, marking which ones need external CLIs:
 
 ```
 ## Devkit Status
 
 ### Plugins
-| Plugin | Status | Commands |
+| Plugin | Status | Skills |
 |--------|--------|----------|
 | codex | ✓ installed | /codex:rescue, /codex:review, /codex:result |
 | gemini | ✗ not installed | /gemini:rescue, /gemini:review, /gemini:result |
 
 ### External CLIs (fallback if plugins not installed)
 | CLI | Status | Required by |
 |-----|--------|------------|
-| codex | ✓ installed (v1.2.0) | tri:* commands (fallback) |
-| gemini | ✗ not installed | tri:* commands (fallback) |
+| codex | ✓ installed (v1.2.0) | tri:* skills (fallback) |
+| gemini | ✗ not installed | tri:* skills (fallback) |
 | gh | ✓ installed (v2.40.0) | pr-ready skill |
 | rtk | ✓ installed (v0.34.2) | token optimization (optional) |
 
-### Commands
-| Command | Status | Notes |
-|---------|--------|-------|
-| /tri:review | ⚠ partial | 2/3 agents available (no gemini) |
-| /tri:debug | ⚠ partial | 2/3 agents available |
-| /tri:security | ⚠ partial | 2/3 agents available |
-| /devkit:workflow | ✓ ready | Runs YAML workflows via Go engine |
-| /devkit:status | ✓ ready | This command |
+### Skills
+| Skill | Status | Notes |
+|-------|--------|-------|
+| /tri-review | ⚠ partial | 2/3 agents available (no gemini) |
+| /tri-debug | ⚠ partial | 2/3 agents available |
+| /tri-security | ⚠ partial | 2/3 agents available |
+| /devkit:status | ✓ ready | This skill |
 | /devkit:setup-rules | ✓ ready | One-time setup |
 
 ### Agents