invoking-github
Enables GitHub repository operations (read/write/commit/PR) for Claude.ai chat environments. Use when users request GitHub commits, repository updates, DEVLOG persistence, or cross-session state management via GitHub branches. Not needed in Claude Code (has native git access).
Install
npx skills add https://github.com/oaustegard/claude-skills/tree/main/plugins/github-and-git/skills/invoking-github
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install oaustegard-claude-skills@llmmart
git clone https://github.com/oaustegard/claude-skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole oaustegard/claude-skills collection as a plugin from our marketplace. Git is the plain clone.
README
invoking-github
Enables GitHub repository operations (read/write/commit/PR) for Claude.ai chat environments. Use when users request GitHub commits, repository updates, DEVLOG persistence, or cross-session state management via GitHub branches. Not needed in Claude Code (has native git access).
Skill manifest
Invoking GitHub
Programmatically interact with GitHub repositories from Claude.ai chat: read files, commit changes, create PRs, and persist state across sessions.
When to Use This Skill
Not needed for:
- Claude Code environments (use native git commands)
- Read-only repository access (use GitHub UI or API directly)
Quick Start
Prerequisites
Create a GitHub Personal Access Token and add to Project Knowledge:
- Go to https://github.com/settings/tokens
- Create new token (classic or fine-grained)
- Required scopes:
repo(orpublic_repofor public repos only) - In Claude.ai, add to Project Knowledge:
- Title:
GITHUB_API_KEY - Content: Your token (e.g.,
ghp_abc123...)
- Title:
Single File Commit
from invoking_github import commit_file
result = commit_file(
repo="username/repo-name",
path="README.md",
content="# Updated README\n\nNew content here...",
branch="main",
message="Update README with new instructions"
)
print(f"Committed: {result['commit_sha']}")
Read File
from invoking_github import read_file
content = read_file(
repo="username/repo-name",
path="config.json",
branch="main"
)
print(content)
Batch Commit (Multiple Files)
from invoking_github import commit_files
files = [
{"path": "src/main.py", "content": "# Python code..."},
{"path": "README.md", "content": "# Updated docs..."},
{"path": "tests/test.py", "content": "# Tests..."}
]
result = commit_files(
repo="username/repo-name",
files=files,
branch="feature-branch",
message="Add new feature implementation",
create_branch_from="main" # Create branch if it doesn't exist
)
print(f"Committed {len(files)} files: {result['commit_sha']}")
Create Pull Request
from invoking_github import create_pull_request
pr = create_pull_request(
repo="username/repo-name",
head="feature-branch",
base="main",
title="Add new feature",
body="## Changes\n- Implemented feature X\n- Updated docs\n- Added tests"
)
print(f"PR created: {pr['html_url']}")
Core Functions
read_file()
Read a file from repository:
read_file(
repo: str, # "owner/name"
path: str, # "path/to/file.py"
branch: str = "main" # Branch name
) -> str
Returns: File content as string
Raises: GitHubAPIError if file not found or access denied
commit_file()
Commit a single file (create or update):
commit_file(
repo: str, # "owner/name"
path: str, # "path/to/file.py"
content: str, # New file content
branch: str, # Target branch
message: str, # Commit message
create_branch_from: str = None # Create branch from this if doesn't exist
) -> dict
Returns: Dict with commit_sha, branch, file_path
Raises: GitHubAPIError on conflicts or auth failures
commit_files()
Commit multiple files in a single commit:
commit_files(
repo: str, # "owner/name"
files: list[dict], # [{"path": "...", "content": "..."}]
branch: str, # Target branch
message: str, # Commit message
create_branch_from: str = None # Create branch from this if doesn't exist
) -> dict
Returns: Dict with commit_sha, branch, files_committed
Raises: GitHubAPIError on failures
Note: Uses Git Trees API for efficiency - atomic commit of all files.
create_pull_request()
Create a pull request:
create_pull_request(
repo: str, # "owner/name"
head: str, # Source branch (your changes)
base: str, # Target branch (where to merge)
title: str, # PR title
body: str = "" # PR description (supports markdown)
) -> dict
Returns: Dict with number, html_url, state
Raises: GitHubAPIError if branches invalid or PR exists
Credential Configuration
This skill requires a GitHub Personal Access Token. Two configuration methods:
Method 1: Project Knowledge (Recommended)
Best for Claude.ai chat users (mobile/web):
- Create token at https://github.com/settings/tokens
- In Claude.ai Project settings → Add to Project Knowledge
- Create document titled
GITHUB_API_KEY - Paste your token as content
Permissions required:
- Classic token:
reposcope - Fine-grained token: Repository permissions → Contents (read/write) and Pull requests (read/write)
Method 2: API Credentials Skill (Fallback)
Alternatively, use combined credentials file:
- Create
API_CREDENTIALS.jsonin project knowledge - Add:
{"github_api_key": "ghp_your-token-here"}
Integration with Iterating Skill
Auto-persist DEVLOG.md to GitHub for cross-session continuity:
# In your DEVLOG update function
from invoking_github import commit_file
from pathlib import Path
def update_devlog_with_sync(data, repo="user/project", branch="devlog"):
"""Update DEVLOG.md locally and sync to GitHub"""
# Update local DEVLOG
update_devlog(data) # Your existing function
# Auto-sync to GitHub
try:
devlog_content = Path("DEVLOG.md").read_text()
result = commit_file(
repo=repo,
path="DEVLOG.md",
content=devlog_content,
branch=branch,
message=f"DEVLOG: {data['title']}",
create_branch_from="main"
)
print(f"✓ DEVLOG synced to GitHub ({repo}:{branch})")
return result
except Exception as e:
print(f"⚠ DEVLOG sync failed: {e}")
# Continue anyway - local DEVLOG.md still updated
return None
Benefits:
- Automatic backup of session progress
- Cross-device access to development logs
- Git history of decisions and progress
- No manual copy/paste to Project Knowledge
See references/iterating-integration.md for complete patterns.
Error Handling
All functions raise GitHubAPIError with descriptive messages:
from invoking_github import commit_file, GitHubAPIError
try:
result = commit_file(
repo="user/repo",
path="file.py",
content="...",
branch="main",
message="Update"
)
except GitHubAPIError as e:
if e.status_code == 404:
print("Repository or branch not found")
elif e.status_code == 401:
print("Authentication failed - check your token")
elif e.status_code == 403:
print("Access denied - check token permissions")
elif e.status_code == 409:
print("Conflict - file was modified since last read")
else:
print(f"GitHub API error: {e}")
Common errors:
- 404: Repository, branch, or file not found
- 401/403: Invalid token or insufficient permissions
- 409: Merge conflict (file changed concurrently)
- 422: Validation error (invalid branch name, etc.)
- Rate limit: Too many requests (wait before retrying)
Best Practices
Use descriptive commit messages
- Bad: "Update files"
- Good: "Add authentication middleware and update user routes"
Batch commits when possible
- Use
commit_files()for related changes - Single atomic commit = cleaner git history
- Use
Create feature branches
- Don't commit directly to main
- Use
create_branch_from="main"parameter - Create PR for review
Secure token management
- Use fine-grained tokens with minimal scopes
- Set expiration dates
- Rotate regularly
- Never commit tokens to repositories
Advanced Usage
Conditional Commits
Only commit if file content changed:
from invoking_github import read_file, commit_file, GitHubAPIError
try:
current_content = read_file(repo, path, branch)
if current_content != new_content:
commit_file(repo, path, new_content, branch, "Update file")
else:
print("No changes detected, skipping commit")
except GitHubAPIError as e:
if e.status_code == 404:
# File doesn't exist, create it
commit_file(repo, path, new_content, branch, "Create file")
else:
raise
Session-Specific Branches
Avoid conflicts with unique branch names:
import datetime
session_id = datetime.datetime.now().strftime("%Y%m%d-%H%M%S")
branch_name = f"devlog-{session_id}"
commit_file(
repo="user/project",
path="DEVLOG.md",
content=devlog_content,
branch=branch_name,
message="Session progress",
create_branch_from="main"
)
Multi-Repository Workflows
Work across multiple repos:
repos = ["user/frontend", "user/backend", "user/docs"]
for repo in repos:
commit_file(
repo=repo,
path="VERSION",
content="2.0.0\n",
branch="release-2.0",
message="Bump version to 2.0.0"
)
Limitations
- Target environment: Claude.ai chat only (not Claude Code)
- No OAuth: Must use Personal Access Tokens manually
- No git operations: Pure REST API (no clone, pull, rebase, etc.)
- File size: GitHub API limits ~100MB per file
- Rate limits: 5000 requests/hour for authenticated users
- Network required: All operations require internet access
See Also
- references/credential-setup.md - Step-by-step credential guide
- references/iterating-integration.md - DEVLOG auto-sync patterns
- references/troubleshooting.md - Common issues and solutions
- GitHub REST API Docs - Official GitHub API reference
Token Efficiency
This skill uses ~800 tokens when loaded but provides essential GitHub operations for claude.ai chat environments where native git access isn't available. Enables persistent state management and cross-session workflows.
Files (claude-skills)
-
references
-
credential-setup.md 6.6 KB
Loading… -
iterating-integration.md 12.6 KB
Loading… -
troubleshooting.md 10.3 KB
Loading…
-
-
scripts
-
github_client.py 16.1 KB
Loading… -
__init__.py 498 B
Loading…
-
-
CHANGELOG.md 369 B
Loading… -
README.md 297 B
# invoking-github Enables GitHub repository operations (read/write/commit/PR) for Claude.ai chat environments. Use when users request GitHub commits, repository updates, DEVLOG persistence, or cross-session state management via GitHub branches. Not needed in Claude Code (has native git access). -
SKILL.md 10.1 KB
--- name: invoking-github description: Enables GitHub repository operations (read/write/commit/PR) for Claude.ai chat environments. Use when users request GitHub commits, repository updates, DEVLOG persistence, or cross-session state management via GitHub branches. Not needed in Claude Code (has native git access). metadata: version: 0.1.0 --- # Invoking GitHub Programmatically interact with GitHub repositories from Claude.ai chat: read files, commit changes, create PRs, and persist state across sessions. ## When to Use This Skill **Not needed for:** - Claude Code environments (use native git commands) - Read-only repository access (use GitHub UI or API directly) ## Quick Start ### Prerequisites Create a GitHub Personal Access Token and add to Project Knowledge: 1. Go to https://github.com/settings/tokens 2. Create new token (classic or fine-grained) 3. Required scopes: `repo` (or `public_repo` for public repos only) 4. In Claude.ai, add to Project Knowledge: - Title: `GITHUB_API_KEY` - Content: Your token (e.g., `ghp_abc123...`) ### Single File Commit ```python from invoking_github import commit_file result = commit_file( repo="username/repo-name", path="README.md", content="# Updated README\n\nNew content here...", branch="main", message="Update README with new instructions" ) print(f"Committed: {result['commit_sha']}") ``` ### Read File ```python from invoking_github import read_file content = read_file( repo="username/repo-name", path="config.json", branch="main" ) print(content) ``` ### Batch Commit (Multiple Files) ```python from invoking_github import commit_files files = [ {"path": "src/main.py", "content": "# Python code..."}, {"path": "README.md", "content": "# Updated docs..."}, {"path": "tests/test.py", "content": "# Tests..."} ] result = commit_files( repo="username/repo-name", files=files, branch="feature-branch", message="Add new feature implementation", create_branch_from="main" # Create branch if it doesn't exist ) print(f"Committed {len(files)} files: {result['commit_sha']}") ``` ### Create Pull Request ```python from invoking_github import create_pull_request pr = create_pull_request( repo="username/repo-name", head="feature-branch", base="main", title="Add new feature", body="## Changes\n- Implemented feature X\n- Updated docs\n- Added tests" ) print(f"PR created: {pr['html_url']}") ``` ## Core Functions ### `read_file()` Read a file from repository: ```python read_file( repo: str, # "owner/name" path: str, # "path/to/file.py" branch: str = "main" # Branch name ) -> str ``` **Returns**: File content as string **Raises**: `GitHubAPIError` if file not found or access denied ### `commit_file()` Commit a single file (create or update): ```python commit_file( repo: str, # "owner/name" path: str, # "path/to/file.py" content: str, # New file content branch: str, # Target branch message: str, # Commit message create_branch_from: str = None # Create branch from this if doesn't exist ) -> dict ``` **Returns**: Dict with `commit_sha`, `branch`, `file_path` **Raises**: `GitHubAPIError` on conflicts or auth failures ### `commit_files()` Commit multiple files in a single commit: ```python commit_files( repo: str, # "owner/name" files: list[dict], # [{"path": "...", "content": "..."}] branch: str, # Target branch message: str, # Commit message create_branch_from: str = None # Create branch from this if doesn't exist ) -> dict ``` **Returns**: Dict with `commit_sha`, `branch`, `files_committed` **Raises**: `GitHubAPIError` on failures **Note**: Uses Git Trees API for efficiency - atomic commit of all files. ### `create_pull_request()` Create a pull request: ```python create_pull_request( repo: str, # "owner/name" head: str, # Source branch (your changes) base: str, # Target branch (where to merge) title: str, # PR title body: str = "" # PR description (supports markdown) ) -> dict ``` **Returns**: Dict with `number`, `html_url`, `state` **Raises**: `GitHubAPIError` if branches invalid or PR exists ## Credential Configuration This skill requires a GitHub Personal Access Token. Two configuration methods: ### Method 1: Project Knowledge (Recommended) Best for Claude.ai chat users (mobile/web): 1. Create token at https://github.com/settings/tokens 2. In Claude.ai Project settings → Add to Project Knowledge 3. Create document titled `GITHUB_API_KEY` 4. Paste your token as content **Permissions required**: - Classic token: `repo` scope - Fine-grained token: Repository permissions → Contents (read/write) and Pull requests (read/write) ### Method 2: API Credentials Skill (Fallback) Alternatively, use combined credentials file: 1. Create `API_CREDENTIALS.json` in project knowledge 2. Add: `{"github_api_key": "ghp_your-token-here"}` ## Integration with Iterating Skill Auto-persist DEVLOG.md to GitHub for cross-session continuity: ```python # In your DEVLOG update function from invoking_github import commit_file from pathlib import Path def update_devlog_with_sync(data, repo="user/project", branch="devlog"): """Update DEVLOG.md locally and sync to GitHub""" # Update local DEVLOG update_devlog(data) # Your existing function # Auto-sync to GitHub try: devlog_content = Path("DEVLOG.md").read_text() result = commit_file( repo=repo, path="DEVLOG.md", content=devlog_content, branch=branch, message=f"DEVLOG: {data['title']}", create_branch_from="main" ) print(f"✓ DEVLOG synced to GitHub ({repo}:{branch})") return result except Exception as e: print(f"⚠ DEVLOG sync failed: {e}") # Continue anyway - local DEVLOG.md still updated return None ``` **Benefits:** - Automatic backup of session progress - Cross-device access to development logs - Git history of decisions and progress - No manual copy/paste to Project Knowledge See [references/iterating-integration.md](references/iterating-integration.md) for complete patterns. ## Error Handling All functions raise `GitHubAPIError` with descriptive messages: ```python from invoking_github import commit_file, GitHubAPIError try: result = commit_file( repo="user/repo", path="file.py", content="...", branch="main", message="Update" ) except GitHubAPIError as e: if e.status_code == 404: print("Repository or branch not found") elif e.status_code == 401: print("Authentication failed - check your token") elif e.status_code == 403: print("Access denied - check token permissions") elif e.status_code == 409: print("Conflict - file was modified since last read") else: print(f"GitHub API error: {e}") ``` **Common errors:** - **404**: Repository, branch, or file not found - **401/403**: Invalid token or insufficient permissions - **409**: Merge conflict (file changed concurrently) - **422**: Validation error (invalid branch name, etc.) - **Rate limit**: Too many requests (wait before retrying) ## Best Practices 1. **Use descriptive commit messages** - Bad: "Update files" - Good: "Add authentication middleware and update user routes" 2. **Batch commits when possible** - Use `commit_files()` for related changes - Single atomic commit = cleaner git history 3. **Create feature branches** - Don't commit directly to main - Use `create_branch_from="main"` parameter - Create PR for review 4. **Secure token management** - Use fine-grained tokens with minimal scopes - Set expiration dates - Rotate regularly - Never commit tokens to repositories ## Advanced Usage ### Conditional Commits Only commit if file content changed: ```python from invoking_github import read_file, commit_file, GitHubAPIError try: current_content = read_file(repo, path, branch) if current_content != new_content: commit_file(repo, path, new_content, branch, "Update file") else: print("No changes detected, skipping commit") except GitHubAPIError as e: if e.status_code == 404: # File doesn't exist, create it commit_file(repo, path, new_content, branch, "Create file") else: raise ``` ### Session-Specific Branches Avoid conflicts with unique branch names: ```python import datetime session_id = datetime.datetime.now().strftime("%Y%m%d-%H%M%S") branch_name = f"devlog-{session_id}" commit_file( repo="user/project", path="DEVLOG.md", content=devlog_content, branch=branch_name, message="Session progress", create_branch_from="main" ) ``` ### Multi-Repository Workflows Work across multiple repos: ```python repos = ["user/frontend", "user/backend", "user/docs"] for repo in repos: commit_file( repo=repo, path="VERSION", content="2.0.0\n", branch="release-2.0", message="Bump version to 2.0.0" ) ``` ## Limitations - **Target environment**: Claude.ai chat only (not Claude Code) - **No OAuth**: Must use Personal Access Tokens manually - **No git operations**: Pure REST API (no clone, pull, rebase, etc.) - **File size**: GitHub API limits ~100MB per file - **Rate limits**: 5000 requests/hour for authenticated users - **Network required**: All operations require internet access ## See Also - [references/credential-setup.md](references/credential-setup.md) - Step-by-step credential guide - [references/iterating-integration.md](references/iterating-integration.md) - DEVLOG auto-sync patterns - [references/troubleshooting.md](references/troubleshooting.md) - Common issues and solutions - [GitHub REST API Docs](https://docs.github.com/rest) - Official GitHub API reference ## Token Efficiency This skill uses ~800 tokens when loaded but provides essential GitHub operations for claude.ai chat environments where native git access isn't available. Enables persistent state management and cross-session workflows.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.