Project References
This skill manages a local mirror of your own GitHub repositories under
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
and
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
to locate a file by name, then
or
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
→
line 4
Step 5: Sync only when explicitly requested
Run
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:
- Run
ls ~/projects/referenzen/
- Ask: "Which sibling project should I use as reference?" — user says
- Run
find ~/projects/referenzen/your-service -name "Chart.yaml"
- Read the file, note the structure (apiVersion, dependencies, version pattern)
- 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:
- Run
bash scripts/clone-or-update.sh owner/other-service
- Stream output so user sees CLONE/PULL/SKIP progress
- 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:
ls ~/projects/referenzen/
grep -rn "database.pool" ~/projects/referenzen/your-service/src/main/resources/
- Read the relevant config section
- Cite: "pattern from
your-service/src/main/resources/application.yaml
Result: Exact config from a proven sibling project, not guessed.
Repository source
Two sources are supported — prefer the manual list when it exists:
- Manual list (
~/claude-shared/projekte.txt
- Automatic discovery:
gh repo list --limit 200 --json nameWithOwner
Scripts
Two ready-made scripts live in
— use them instead of writing
inline Bash. Both accept
as an env override (default:
).
scripts/clone-or-update.sh <owner/repo>
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:
= ok,
= skipped (local changes),
= clone/pull failed.
scripts/sync-all.sh [--list <file>] [--limit <n>]
Iterates over all repositories and calls the clone-or-update logic for each.
Prefers
~/claude-shared/projekte.txt
as source; falls back to
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
.
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 .
- If 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 (, credential
files) in the response — read and cite structure only.