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:42.810088+00:00	target type direction strength edge_id 6cc417e2-8b8a-4629-a611-b2b379ad39b4 CAUSES incoming 0.9 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