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

id	type	title	tags	importance	confidence	created	updated	relations
e0a851a7-1dc5-4191-b220-aa90112a1171	code_pattern	Skill architecture: SKILL.md only, app code lives separately	claude-code skills architecture best-practices python uv claude-code-config	0.75	0.8	2026-03-01T05:48:30.126096+00:00	2026-03-01T05:48:50.361659+00:00	target type direction strength edge_id 6cc417e2-8b8a-4629-a611-b2b379ad39b4 CAUSES incoming 0.9 08489f38-78fc-4153-bad9-5d41e8c3164c target type direction strength edge_id 002fc433-6969-4f1d-b400-50b8324bb82d CAUSES outgoing 0.9 f8920f75-7809-4b4a-ae30-77bd85c28ef1 target type direction strength edge_id a41644f1-2dd1-4706-8fc8-e2242c1702cb RELATED_TO outgoing 0.95 ff317a0a-fe1b-4e35-b924-762b087fd134

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