42 lines
1.6 KiB
Markdown
42 lines
1.6 KiB
Markdown
---
|
|
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
|