---
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:42.810088+00:00"
relations:
  - target: 6cc417e2-8b8a-4629-a611-b2b379ad39b4
    type: CAUSES
    direction: incoming
    strength: 0.9
    edge_id: 08489f38-78fc-4153-bad9-5d41e8c3164c
---

# 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