# Project References > Look up conventions, patterns, and concrete implementations from your own GitHub repositories checked out locally under ~/projects/referenzen/. Use this skill whenever there is uncertainty about how something is done in your codebase family — e.g. Helm chart structure, Kubernetes manifests, framework configuration patterns, Docker Compose conventions, CI/CD pipeline setup, or any other recurring architectural decision. Invoke it proactively before guessing at a convention; always cite the source project and path when a pattern is adopted. Also use when the user asks to check out, update, or search reference repositories. - Skill: `dboeckli/project-references` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add dboeckli/project-references` - Raw SKILL.md: https://api.skillmd.com/api/skills/dboeckli/project-references/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: dboeckli (https://skillmd.com/u/dboeckli) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/dboeckli/project-references --- --- # Project References This skill manages a local mirror of your own GitHub repositories under `~/projects/referenzen/` and lets you look up conventions and implementation patterns without guessing or reading all repos blindly. All operations are **read-only** on the reference projects themselves. Only `git clone` and `git pull` write into that directory — never edits. --- ## Instructions ### Step 1: Check whether the relevant repo is already cloned ```bash ls ~/projects/referenzen/ ``` If the needed repo is missing, run `scripts/clone-or-update.sh owner/repo` to clone it first. ### Step 2: Ask the user which reference project is most relevant Do not scan all repos blindly — that fills context. Ask: "Which of your sibling projects uses this pattern?" or list the available repos and let the user pick. ### Step 3: Search targeted — file first, then grep Use `find` to locate a file by name, then `cat` or `grep` to read only the relevant section. For search commands and patterns, consult `references/search-patterns.md`. ### Step 4: Cite the source when adopting a pattern Always state which project and file path a pattern came from before applying it: > Pattern adopted from `your-service` → `helm-charts/Chart.yaml` line 4 ### Step 5: Sync only when explicitly requested Run `scripts/sync-all.sh` only when the user says "sync all" or "update all references". For a single repo, prefer `scripts/clone-or-update.sh`. --- ## Examples ### Example 1: Looking up a Helm chart convention User says: "How should I structure the Helm chart for this project?" Actions: 1. Run `ls ~/projects/referenzen/` to see available repos 2. Ask: "Which sibling project should I use as reference?" — user says `your-service` 3. Run `find ~/projects/referenzen/your-service -name "Chart.yaml"` to locate it 4. Read the file, note the structure (apiVersion, dependencies, version pattern) 5. Apply the same structure; cite: "adopted from `your-service/helm-charts/Chart.yaml`" Result: Helm chart consistent with sibling projects, traceable source cited. ### Example 2: Checking out a new reference repo User says: "Clone my other-service project as a reference" Actions: 1. Run `bash scripts/clone-or-update.sh owner/other-service` 2. Stream output so user sees CLONE/PULL/SKIP progress 3. Confirm with `ls ~/projects/referenzen/other-service/` Result: Repo available locally for pattern lookups; no edits made. ### Example 3: Finding a configuration pattern User says: "How do I configure the database pool like in the other projects?" Actions: 1. `ls ~/projects/referenzen/` — pick a relevant sibling project 2. `grep -rn "database.pool" ~/projects/referenzen/your-service/src/main/resources/` 3. Read the relevant config section 4. Cite: "pattern from `your-service/src/main/resources/application.yaml` line 42" Result: Exact config from a proven sibling project, not guessed. --- ## Repository source Two sources are supported — prefer the manual list when it exists: 1. **Manual list** (`~/claude-shared/projekte.txt`): one GitHub repo URL or `owner/name` slug per line, blank lines and `#` comments ignored. 2. **Automatic discovery**: `gh repo list --limit 200 --json nameWithOwner` when the file is absent or the user explicitly asks for a full sync. --- ## Scripts Two ready-made scripts live in `scripts/` — use them instead of writing inline Bash. Both accept `REFERENZEN_DIR` as an env override (default: `~/projects/referenzen`). ### `scripts/clone-or-update.sh ` Clones a single repository or pulls if it already exists locally. Refuses to pull when local changes are present (exit code 2) — never stashes or resets. ```bash bash scripts/clone-or-update.sh owner/your-repo ``` Exit codes: `0` = ok, `2` = skipped (local changes), `3` = clone/pull failed. ### `scripts/sync-all.sh [--list ] [--limit ]` Iterates over all repositories and calls the clone-or-update logic for each. Prefers `~/claude-shared/projekte.txt` as source; falls back to `gh repo list` when the file is absent. Prints a summary line at the end. ```bash # Sync everything (auto-detect source) bash scripts/sync-all.sh # Use a specific list file bash scripts/sync-all.sh --list ~/claude-shared/projekte.txt # Limit gh repo list to 50 repos bash scripts/sync-all.sh --limit 50 ``` **Do not** run sync-all blindly — use it only when the user explicitly says "sync all" or "update all references". For a single repo prefer `clone-or-update.sh`. --- ## Workflows ### 1. Check out or update repositories Run the appropriate script and stream output so the user sees every CLONE / PULL / SKIP action as it happens. ### 2. Search within reference projects Scope the search to what the user actually needs. Prefer targeted lookups over broad recursive greps. For ready-made search commands and citing patterns, consult `references/search-patterns.md`. ### 3. Discover available reference projects ```bash ls ~/projects/referenzen/ ``` If `~/claude-shared/projekte.txt` exists, show its contents alongside to explain which repos are tracked vs. which are locally present. --- ## When to suggest this skill proactively Suggest looking up a reference project when: - The user asks how something is structured and the answer may vary by project convention (Helm chart layout, Flyway migration naming, Dockerfile patterns, Maven plugin ordering, etc.) - There is more than one reasonable approach and consistency with sibling projects matters - The user says "like the other projects" or "same as before" without specifying which project Ask the user which reference project is most relevant rather than scanning all of them — scanning is expensive in context. --- ## Safety rules - Never edit, stage, commit, or delete files inside `~/projects/referenzen/`. - If `git pull` would fail due to local changes, report the conflict clearly and stop — do not stash, reset, or force. - Do not expose repository contents that contain secrets (`.env`, credential files) in the response — read and cite structure only.