cal/claude-memory
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity
2c4914bcde
claude-memory/graph/code-patterns/skill-architecture-skillmd-only-app-code-lives-separately-e0a851.md

1.5 KiB
Raw Blame History

id type title tags importance confidence created updated
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:30.126096+00:00

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