← reference library / diagrams / repo-structure

Project vs Workspace Repo Structure

How to organise your AI workspace (gilesparnell/Claude) vs individual client project repos — what lives where and why.

structure workflow
client-acme/  ·  project repo
📁src/
├app.js
└api/
📁docs/
├proposals/
├sow/
└technical/
📁scripts/
📁.claude/ Claude context
├project.md
└skills/ (project-specific)
📄README.md
Source code — nothing AI-specific, just your normal project structure.
All project artefacts: proposals, SOWs, technical specs. Committed alongside the code.
project.md tells Claude the domain, stack, conventions, and decisions for this engagement. Skills here are project-specific runtime versions — generic skills live in ~/.claude/skills/ and are available in every session automatically.
Click a folder to learn more
gilesparnell/Claude  ·  your AI OS
📁skills/ reusable
├code-review/ (global)
├git-conventions/ (global)
└saas-patterns/ (repo-scoped)
📁project-templates/
📁global/ CLAUDE.md
📁docs/ add this GitHub Pages
├index.html
└diagrams/
└repo-structure.html
📄README.md
Portal stubs for all skills — both global and repo-scoped. These are the display layer rendered on the GitHub Pages portal. Runtime versions that Claude actually reads live in ~/.claude/skills/ (global, every session) or the client repo's .claude/skills/ (project-specific).
Starter templates for new client repos. Copy project.md into each new engagement and fill it in.
Your top-level CLAUDE.md — working style, preferred tools, naming conventions that apply across all projects.
GitHub Pages root. Everything here is served as a public website at gilesparnell.github.io/Claude/ — your bookmarkable visual reference library.
Click a folder to learn more
📎   This diagram: https://gilesparnell.github.io/Claude/diagrams/repo-structure.html
reusable shared across all clients Claude context Claude reads this add this new folders to create GitHub Pages served as public website
Two repos, different lifecycles

Your workspace repo (gilesparnell/Claude) is your methodology — it improves over time and makes every project faster. Client repos are just normal project repos with a thin .claude/ folder for context.

The project.md trick

Drop a .claude/project.md in every client repo. It tells Claude the domain, stack, decisions made, and where things live. No re-briefing at the start of every session.

Skills have three locations

~/.claude/skills/ — global runtime skills, loaded in every session. [client-repo]/.claude/skills/ — project-specific runtime skills. gilesparnell/Claude/skills/ — portal stubs only (display layer, not read by Claude Code at runtime).