52 lines
1.9 KiB
Markdown
52 lines
1.9 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:50.361659+00:00"
|
|
relations:
|
|
- target: 6cc417e2-8b8a-4629-a611-b2b379ad39b4
|
|
type: CAUSES
|
|
direction: incoming
|
|
strength: 0.9
|
|
edge_id: 08489f38-78fc-4153-bad9-5d41e8c3164c
|
|
- target: 002fc433-6969-4f1d-b400-50b8324bb82d
|
|
type: CAUSES
|
|
direction: outgoing
|
|
strength: 0.9
|
|
edge_id: f8920f75-7809-4b4a-ae30-77bd85c28ef1
|
|
- target: a41644f1-2dd1-4706-8fc8-e2242c1702cb
|
|
type: RELATED_TO
|
|
direction: outgoing
|
|
strength: 0.95
|
|
edge_id: 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
|