Setup Remote Repository Notes Directory

Overview

Facilitate studying and documenting remote GitHub repositories by creating a structured workspace with:

• A notes/ directory for committed markdown documentation
• A code/ directory for the gitignored cloned repository
• Automatic .gitignore configuration to keep code local while notes stay in version control

When to Use This Skill

Use this skill when the user:

• Wants to study or analyze an external GitHub repository
• Needs to take notes about a remote codebase
• Wants to document findings from exploring another project
• Requests to "set up notes for a repo" or similar phrasing
• Provides a GitHub URL and mentions research, study, or documentation

Example requests:

• "Help me set up notes for studying https://github.com/anthropics/claude-code"
• "I want to research this repo: https://github.com/facebook/react"
• "Create a workspace for analyzing https://github.com/rust-lang/rust"

Directory Structure

The skill creates the following structure:

reference/repo/<github-org-or-user>/<reponame>/
├── notes/          # Committed - contains markdown notes about the repo
│   └── README.md   # Initial note file with repo metadata
└── code/           # Gitignored - contains the cloned repository
    └── ...         # Contents of the cloned repo

Design rationale:

• notes/ stays in version control → persistent documentation
• code/ is gitignored → can be deleted/re-cloned without affecting notes
• Hierarchical organization → supports multiple repos from same org

Git Worktree Compatibility

New in v2: The skill is now worktree-aware and optimizes for git worktree workflows.

Behavior

When invoked from a git worktree (e.g., /workspace/wip/username-123-feature):

• ✅ Code cloned to root: /workspace/reference/repo/<org>/<repo>/code/ (shared)
• ✅ Notes in worktree: /workspace/wip/username-123-feature/reference/repo/<org>/<repo>/notes/ (local)

When invoked from root (/workspace):

• ✅ Both in root: /workspace/reference/repo/<org>/<repo>/ (current behavior)

Benefits

Shared code directory:

• Saves disk space (no duplicate clones per worktree)
• Reference repos persist after worktree deletion
• Single clone shared across all worktrees

Worktree-local notes:

• Notes can be committed with branch work
• Different branches can have different notes
• Follows git-worktrees best practice of keeping worktrees clean

Example

# From worktree
cd /workspace/wip/codekiln-173-fix-skill
.claude/skills/setup-remote-repo-notes-dir/scripts/setup_repo_notes.sh https://github.com/anthropics/claude-code

# Result:
# Code:  /workspace/reference/repo/anthropics/claude-code/code/ (shared)
# Notes: /workspace/wip/codekiln-173-fix-skill/reference/repo/anthropics/claude-code/notes/ (local)

# From another worktree
cd /workspace/wip/codekiln-180-another-feature
.claude/skills/setup-remote-repo-notes-dir/scripts/setup_repo_notes.sh https://github.com/anthropics/claude-code

# Result:
# Code:  /workspace/reference/repo/anthropics/claude-code/code/ (reused!)
# Notes: /workspace/wip/codekiln-180-another-feature/reference/repo/anthropics/claude-code/notes/ (new)

Usage

Quick Start

Use the bundled bash script to set up the structure automatically:

.claude/skills/setup-remote-repo-notes-dir/scripts/setup_repo_notes.sh <github-url>

Example:

.claude/skills/setup-remote-repo-notes-dir/scripts/setup_repo_notes.sh https://github.com/anthropics/claude-code

What the Script Does

1. Parses the GitHub URL to extract org/user and repository name
2. Creates directory structure under reference/repo/<org>/<repo>/
3. Clones the repository into the code/ subdirectory
4. Creates initial notes/README.md with:
   • Repository name and URL
   • Date created
   • Purpose/description placeholder
   • Sections for findings, architecture, and notes
5. Updates .gitignore to exclude reference/repo/**/code/ directories
6. Provides next steps for the user

Supported GitHub URL Formats

The script accepts multiple GitHub URL formats:

• https://github.com/owner/repo
• https://github.com/owner/repo.git
• git@github.com:owner/repo.git

Manual Setup (Alternative)

For custom setups or when the script cannot be used, manually perform these steps:

1. Parse the GitHub URL to extract <org> and <repo>
2. Create directories:

   mkdir -p reference/repo/<org>/<repo>/notes
   mkdir -p reference/repo/<org>/<repo>/code
   

3. Clone the repository:

   git clone <github-url> reference/repo/<org>/<repo>/code
   

4. Create initial notes/README.md with repository metadata
5. Update .gitignore to add reference/repo/**/code/

Workflow After Setup

After running the setup:

1. Explore the cloned code:

   cd reference/repo/<org>/<repo>/code
   # Read files, run the project, analyze structure
   

2. Document findings in notes:

   # Edit notes/README.md or create additional markdown files
   cd reference/repo/<org>/<repo>/notes
   

3. Commit notes to version control:

   git add reference/repo/<org>/<repo>/notes
   git commit -m "📚 docs: add notes for <org>/<repo>"
   

4. Code directory remains gitignored - can delete and re-clone anytime

Benefits

• Separation of concerns: Notes (committed) vs code (local)
• Consistent organization: Standard location for all remote repo research
• Version-controlled documentation: Notes persist across machines
• Flexibility: Code can be deleted/updated without affecting notes
• Multi-repo support: Easy to manage multiple repositories

Examples

Example 1: Studying Claude Code

.claude/skills/setup-remote-repo-notes-dir/scripts/setup_repo_notes.sh https://github.com/anthropics/claude-code

Result:

reference/repo/anthropics/claude-code/
├── notes/
│   └── README.md    # "# claude-code" with metadata
└── code/            # Full clone of anthropics/claude-code

Example 2: Researching React

.claude/skills/setup-remote-repo-notes-dir/scripts/setup_repo_notes.sh https://github.com/facebook/react

Result:

reference/repo/facebook/react/
├── notes/
│   └── README.md    # "# react" with metadata
└── code/            # Full clone of facebook/react

Script Reference

Location

scripts/setup_repo_notes.sh

Usage

./setup_repo_notes.sh <github-url>

Exit Codes

• 0 - Success
• 1 - Error (invalid URL, clone failure, etc.)

Output

• Colored status messages (info, success, warnings, errors)
• Summary of created structure
• Next steps for the user

Idempotency

• Safe to run multiple times on the same repository
• Existing files are preserved with warnings
• Git pull performed if repository already cloned

Troubleshooting

"Invalid GitHub URL format"

• Ensure URL is in format: https://github.com/owner/repo
• Check for typos in the URL

"Repository already cloned"

• Script will pull latest changes instead of re-cloning
• Existing notes are preserved

".gitignore already contains pattern"

• Pattern already exists, no action needed
• Setup continues normally

Clone fails with authentication error

• Ensure you have access to the repository
• For private repos, use SSH URL: git@github.com:owner/repo.git
• Check GitHub credentials and SSH keys

Integration with Other Skills

This skill complements:

• example-skills:skill-creator - For creating skills based on studied repos
• example-skills:mcp-builder - When studying MCP servers for reference

Notes

• The code/ directory is fully gitignored and can be safely deleted
• Notes directory can contain multiple markdown files, not just README.md
• Subdirectories can be created within notes/ for organization
• Consider committing notes after each research session
• The script is idempotent - safe to run multiple times