store: Skill architecture: SKILL.md only, app code lives separately

graph/code-patterns/skill-architecture-skillmd-only-app-code-lives-separately-e0a851.md

@@ -0,0 +1,35 @@
+---
+id: e0a851a7-1dc5-4191-b220-aa90112a1171
+type: code_pattern
+title: "Skill architecture: SKILL.md only, app code lives separately"
+tags: [claude-code, skills, architecture, best-practices, python, uv, claude-code-config]
+importance: 0.75
+confidence: 0.8
+created: "2026-03-01T05:48:30.126096+00:00"
+updated: "2026-03-01T05:48:30.126096+00:00"
+---
+
+# Skill Architecture Pattern: Separate App Code from Skill Instructions
+
+## Pattern
+Skills in `~/.claude/skills/` should contain **only `SKILL.md`** — instructions for Claude on how to use the tool.
+
+The actual application/tool lives in a proper location:
+- Development tools: `/mnt/NV2/Development/<tool-name>/`
+- Installed via: `uv tool install -e .` or `pip install`
+- Referenced in SKILL.md by: CLI command name only, not path to source files
+
+## Examples Following This Pattern
+- **z-image**: app at `/mnt/NV2/Development/z-image/`, installed as `z-image` CLI
+- **youtube-transcriber**: app at `/mnt/NV2/Development/youtube-transcriber/`, skill just documents CLI usage
+
+## Anti-Pattern (Avoid)
+- Putting `generate.py`, venvs, or other code inside `~/.claude/skills/<skill-name>/`
+- Bash wrapper scripts that `source` a venv inside the skills directory
+
+## Benefits
+- Clean separation of concerns
+- Skills directory stays small and readable
+- App code can be versioned/developed independently in its own repo
+- `uv tool install -e .` allows development without reinstalling
+- Console scripts entry point provides a clean binary name