add code-reference skill for exploring external codebases

[Kabilan108]

Skill for referencing external repos while working on a project.
Resolves repos via gh CLI, pins to dependency version if applicable,
probes DeepWiki for orientation, then dispatches Explore sub-agents
for targeted source reading.

https://claude.ai/code/session_01NwsLV9kbwu2bVSZ7TUzrfS

---

Summary by CodeRabbit

• Documentation
  • Added comprehensive documentation for the Code Reference skill, detailing the workflow, input parsing process, multi-phase exploration strategy, and response structure.

[coderabbitai]

📝 Walkthrough

Walkthrough

A new documentation file was created at agents/skills/code-reference/SKILL.md detailing the Code Reference skill's workflow, including input parsing, a 5-step execution process, two-phase exploration strategy, repository resolution, version pinning, and response formatting guidelines.

Changes

Cohort / File(s)	Summary
Code Reference Skill Documentation agents/skills/code-reference/SKILL.md	New documentation file (114 lines) describing the Code Reference skill's workflow, input/output specifications, exploration phases, and response format requirements.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐰 A skill docs bloom, so shiny and new,
Code Reference guides what AI shall do,
From repos resolved to responses refined,
Five steps of wisdom, carefully lined.
DeepWiki probing, version pins true—
Documentation done, hooray for the crew! 📚✨

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'add code-reference skill for exploring external codebases' directly and clearly summarizes the main change: a new documentation file defining the Code Reference skill.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Merge Conflict Detection	✅ Passed	✅ No merge conflicts detected when merging into nixos

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch claude/code-reference-skill-clTtA

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 4 additional findings.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@agents/skills/code-reference/SKILL.md`:
- Around line 76-77: The git checkout command that currently silences errors
(git -C "$REF_DIR" checkout <tag> --quiet 2>/dev/null) should instead surface
and handle failures: run git -C "$REF_DIR" checkout <tag> --quiet without
redirecting stderr, check the command's exit status ($? or conditional), and if
it fails (non-zero) emit a clear error mentioning REF_DIR and the tag and exit
non‑zero to prevent continuing with the wrong version; also consider detecting
common failure modes (tag not found, merge/conflict/detached HEAD) and providing
actionable messages.

🧹 Nitpick comments (2)

agents/skills/code-reference/SKILL.md (2)

56-60: Consider clarifying version format handling.

The grep -i "<version>" approach works but could benefit from guidance on handling different tag formats (e.g., v1.0.0 vs 1.0.0, or pre-release tags). Consider noting that the version string should be normalized or that users should verify the matched tag.

📝 Example clarification

Add after line 60:

**Note:** Tag formats vary by project. Normalize the version (strip/add 'v' prefix as needed) and verify the matched tag is the correct one. Use `--jq '.[] | select(.ref | test("refs/tags/(v)?<version>$"))'` for more precise matching.

---

84-104: Consider clarifying two points for implementation.

The two-phase exploration strategy is sound, but two areas could be more specific:

1. Line 92: "broader initial pass" - what does this mean in practice? (e.g., "start with README, main entry points, and top-level directory structure"?)

2. Line 104: The $REF_DIR reference mixes shell script context with Task tool parameter documentation. Consider showing the actual parameter format, e.g., path: "/path/to/.cache/claude/references/owner/repo".

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Add error handling for tag checkout.

Suppressing stderr with 2>/dev/null hides important failures. If the tag doesn't exist or checkout fails (conflicts, detached HEAD), the script continues silently with the wrong version, potentially leading to incorrect advice.

🛡️ Proposed fix with explicit conditional and error handling

-# If version-pinned, checkout the tag
-git -C "$REF_DIR" checkout <tag> --quiet 2>/dev/null
+# If version-pinned, checkout the tag
+if [ -n "$TAG" ]; then
+  if ! git -C "$REF_DIR" checkout "$TAG" --quiet 2>&1 | grep -q "error:"; then
+    echo "✓ Checked out $TAG"
+  else
+    echo "⚠ Failed to checkout $TAG, using default branch" >&2
+  fi
+fi

Or for a simpler approach that still surfaces errors:

-# If version-pinned, checkout the tag
-git -C "$REF_DIR" checkout <tag> --quiet 2>/dev/null
+# If version-pinned, checkout the tag (fails gracefully if tag doesn't exist)
+if [ -n "$TAG" ]; then
+  git -C "$REF_DIR" checkout "$TAG" --quiet || echo "⚠ Tag $TAG not found, using default branch" >&2
+fi

🤖 Prompt for AI Agents

In `@agents/skills/code-reference/SKILL.md` around lines 76 - 77, The git checkout
command that currently silences errors (git -C "$REF_DIR" checkout <tag> --quiet
2>/dev/null) should instead surface and handle failures: run git -C "$REF_DIR"
checkout <tag> --quiet without redirecting stderr, check the command's exit
status ($? or conditional), and if it fails (non-zero) emit a clear error
mentioning REF_DIR and the tag and exit non‑zero to prevent continuing with the
wrong version; also consider detecting common failure modes (tag not found,
merge/conflict/detached HEAD) and providing actionable messages.