Claude Skill

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).

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download oaustegard-claude-skills-plugins_github-and-git_skills_invoking-github-e39c726.zip · 19 KB

Install

skills CLI npx skills add https://github.com/oaustegard/claude-skills/tree/main/plugins/github-and-git/skills/invoking-github
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install oaustegard-claude-skills@llmmart
Git 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:

  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

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):

  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:

# 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

  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:

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

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.

No comments yet.

Reviews (0)

No reviews yet.