Get the FREE Ultimate OpenClaw Setup Guide →

Docs

Scanned
npx machina-cli add skill wrm3/ai_project_template/docs --openclaw
Files (1)
SKILL.md
9.5 KB

GitHub Integration Skill - Completion Documentation

Skill Name: github-integration Created: 2025-10-20 06:08:29 IDE: Claude Code (with Cursor compatibility) Type: Ad-hoc Skill (User Request) Status: ✅ Complete

Purpose

Complete GitHub integration skill for managing repositories, issues, pull requests, releases, and GitHub Actions using the GitHub CLI (gh).

Primary User Need: Update repository topics/tags to improve discoverability on GitHub.

Trigger

User requested ability to "edit those fields" (topics, description, homepage) on GitHub repository after being unable to access the GitHub web interface via WebFetch.

Files Created

Claude Code Files

  1. .claude/skills/github-integration/SKILL.md (12 KB)

    • Main skill definition with metadata and comprehensive usage guide
    • Covers repository management, issues, PRs, releases, Actions
    • Primary focus on repository topics/tags management

  2. .claude/skills/github-integration/rules.md (14 KB)

    • Detailed implementation rules and workflows
    • Step-by-step guides for all GitHub operations
    • Error handling strategies
    • Best practices and security considerations

  3. .claude/skills/github-integration/reference/github_cli_guide.md (Complete gh CLI reference)

    • Comprehensive GitHub CLI command reference
    • Installation instructions for Windows/macOS/Linux
    • Every major gh command with examples
    • Global options and useful combinations

  4. .claude/skills/github-integration/reference/topics_guide.md (GitHub topics best practices)

    • Complete guide for managing repository topics
    • Topic format rules and normalization
    • Topic categories (platform, language, framework, purpose, etc.)
    • Topic selection strategy (7-15 topics ideal)
    • Common mistakes to avoid
    • Examples by project type

  5. .claude/skills/github-integration/reference/github_api_guide.md (GitHub API reference)

    • Direct GitHub REST API usage guide
    • Authentication and rate limiting
    • Repository, issue, PR, release, workflow operations
    • Error handling
    • Python example implementation

  6. .claude/skills/github-integration/examples/repo_workflows.md (Practical workflow examples)

    • 17 complete workflow examples:
      • Repository metadata updates (topics, description, homepage)
      • Issue management (create, triage, close)
      • PR workflows (create, review, merge, draft)
      • Release management (production, pre-release, editing)
      • Batch operations across multiple repos
      • GitHub Actions (trigger, monitor, download artifacts)
      • Error handling examples

Cursor Compatibility

  1. .cursor/rules/github/github_integration.mdc (10 KB)
    • Condensed rules for Cursor IDE
    • Quick reference for all major operations
    • Common operation examples
    • Compatible with Cursor's rule system

Key Features

Repository Management

  • Topics/Tags: Add, remove, update repository topics with automatic normalization
  • Description: Update repository description (max 350 chars)
  • Homepage: Set repository homepage URL
  • Settings: Configure repository features (issues, wiki, projects)

Issue Management

  • Create issues with labels, assignees, milestones
  • List and filter issues (by state, label, assignee, author)
  • Update issue metadata
  • Close/reopen issues with comments
  • Bulk triage operations

Pull Request Operations

  • Create PRs with comprehensive descriptions
  • Review PRs (approve, request changes, comment)
  • Check PR status and CI/CD
  • Merge with multiple strategies (merge, squash, rebase)
  • Draft PRs for early feedback

Release Management

  • Create production releases with auto-generated notes
  • Create pre-releases (alpha, beta, RC)
  • Upload release assets
  • Edit release notes
  • Semantic versioning support

GitHub Actions

  • Trigger workflows with inputs
  • Monitor workflow runs
  • Download artifacts
  • Rerun failed workflows
  • Cancel running workflows

Topic Normalization System

Implemented intelligent topic normalization:

User Input → Normalized Topic:

  • "Claude Code" → "claude-code"
  • "AI Assistant" → "ai-assistant"
  • "Task Management" → "task-management"
  • "MCP Server" → "mcp-server"

Validation:

  • Lowercase conversion
  • Space → hyphen conversion
  • Max 50 characters per topic
  • Max 20 topics total
  • No special characters except hyphens

User's Immediate Use Case

Scenario: User wanted to add proper topics to this repository for discoverability.

Recommended Topics for this Project:

Primary: claude-code, claude-skills, cursor, cursor-ide, anthropic, ai-assistant
Project: project-template, boilerplate, starter-template
Tech: mcp, mcp-server, python, typescript
Features: task-management, automation, web-scraping, desktop-automation
Integrations: jira-integration, confluence, atlassian, github

Quick Command:

gh repo edit --add-topic claude-code,claude-skills,cursor,ai-assistant,anthropic,project-template,mcp,task-management,automation

Authentication

Uses GitHub CLI authentication:

  • Check status: gh auth status
  • Login: gh auth login
  • Stores credentials securely via GitHub CLI credential manager
  • No hardcoded tokens needed

Error Handling

Comprehensive error recovery:

  • 401 Unauthorized: Guide through authentication
  • 403 Forbidden: Check permissions and rate limits
  • 404 Not Found: Verify repository name and access
  • Validation Errors: Auto-correct topic format issues
  • Rate Limiting: Check limits and wait for reset

Best Practices Implemented

Topics

✅ Use 7-15 topics (not all 20) ✅ Research established topic names ✅ Include platform, language, purpose ✅ Use hyphens not underscores ✅ Lowercase only

Security

✅ Use gh auth login for authentication ✅ Never commit tokens ✅ Verify auth before operations ✅ Confirm destructive operations

User Experience

✅ Clear initial response explaining operation ✅ Progress updates for long operations ✅ Success report with URLs ✅ Detailed error messages with recovery steps

Cross-IDE Compatibility

Full dual-IDE support:

  • Claude Code: Progressive disclosure via SKILL.md → rules.md → references
  • Cursor: Condensed .mdc file with quick reference
  • Both IDEs can use this skill effectively

Documentation Quality

Total Documentation: ~60 KB across 7 files

Structure:

  • SKILL.md: Overview and quick start
  • rules.md: Detailed implementation
  • reference/: Complete technical references (3 files)
  • examples/: 17 practical workflow examples
  • Cursor .mdc: Condensed quick reference

Integration Points

GitHub CLI (gh):

  • Primary tool for all operations
  • Version-agnostic (uses current stable)
  • Cross-platform (Windows/macOS/Linux)

GitHub REST API:

  • Fallback for advanced operations
  • Direct API access when needed
  • Rate limit monitoring

Success Metrics

User Request Fulfilled: ✅ Can now update repository topics/tags programmatically ✅ Can update description and homepage ✅ Full GitHub integration beyond initial request ✅ Works in both Claude Code and Cursor

Quality Indicators: ✅ Comprehensive documentation (60+ KB) ✅ 17 practical examples ✅ Error handling for all common scenarios ✅ Security-conscious implementation ✅ Cross-IDE compatibility ✅ Production-ready

Usage Example

User says: "Add topics: Claude Code, Cursor, AI Assistant, Task Management"

Skill workflow:

  1. Normalize topics to lowercase with hyphens
  2. Get current topics: gh repo view --json repositoryTopics
  3. Add new topics: gh repo edit --add-topic claude-code,cursor,ai-assistant,task-management
  4. Verify: gh repo view --json repositoryTopics
  5. Report: "✓ Added 4 topics! View: https://github.com/owner/repo"

Next Steps for User

To use this skill immediately:

  1. Ensure GitHub CLI is authenticated:

    gh auth status

    If not authenticated:

    gh auth login

  2. Add topics to this repository: Simply ask Claude: "Add these topics to my repository: claude-code, cursor, ai-assistant, task-management, mcp"

  3. Update repository description: Ask: "Update my repository description to explain it's an AI assistant template project"

Files Summary

.claude/skills/github-integration/
├── SKILL.md (12 KB) - Main skill definition
├── rules.md (14 KB) - Implementation rules
├── reference/
│   ├── github_cli_guide.md - Complete gh CLI reference
│   ├── topics_guide.md - Topics best practices
│   └── github_api_guide.md - GitHub API reference
├── examples/
│   └── repo_workflows.md - 17 workflow examples
└── docs/
    └── 20251020_060829_CLAUDE_CODE_GITHUB_INTEGRATION_SKILL.md (this file)

.cursor/rules/github/
└── github_integration.mdc (10 KB) - Cursor compatibility

Related Skills

This skill complements:

  • fstrent-task-management: Can create GitHub issues from tasks
  • fstrent-planning: Can create releases from plans
  • computer-use-agent: Could automate GitHub web UI if needed
  • web-tools: Alternative web scraping approach for GitHub data

Maintenance Notes

Future enhancements:

  • Add GitHub Projects v2 integration
  • Add GitHub Discussions support
  • Add organization management
  • Add team management
  • Add repository transfer operations
  • Add GitHub Pages deployment

Version: 1.0.0 Last Updated: 2025-10-20 06:08:29 Status: Production Ready ✅

This skill was created ad-hoc based on user need and is fully functional for immediate use.

Source

git clone https://github.com/wrm3/ai_project_template/blob/main/.claude/skills/github-integration/docs/20251020_060829_CLAUDE_CODE_GITHUB_INTEGRATION_SKILL.mdView on GitHub

Overview

This skill enables complete GitHub management using the gh CLI, covering repositories, issues, PRs, releases, and Actions. Its primary aim is to update repository topics/tags to boost discoverability, especially when the web interface is unavailable.

How This Skill Works

The skill executes gh CLI commands across repository metadata, issues, PRs, releases, and Actions. It relies on curated references and rules to normalize topics, manage descriptions and homepages, and automate common workflows while handling errors securely.

When to Use It

  • When the GitHub web interface is inaccessible due to WebFetch restrictions and you still need to update repo metadata
  • When you must update topics/tags to improve repository discoverability and organization
  • When you need to batch-update metadata (topics, description, homepage) across multiple repositories
  • When you want to create, review, or merge PRs and manage issues from the command line
  • When you need to create production releases, pre-releases, or trigger and monitor GitHub Actions

Quick Start

  1. Step 1: Install and authenticate the gh CLI (gh auth login) and verify access
  2. Step 2: Update topics and metadata for a repository (gh repo edit and gh api calls)
  3. Step 3: Validate changes using gh repo view and the GitHub API as needed

Best Practices

  • Normalize and validate topics before applying changes to ensure consistency
  • Aim for 7-15 topics per repository to balance discoverability and relevance
  • Keep repository descriptions within the 350-character limit for clarity
  • Follow semantic versioning for releases and document notes clearly
  • Refer to the provided rules and reference guides for error handling and security

Example Use Cases

  • Update topics, description, and homepage for a target repository to improve visibility
  • Create and triage issues with labels, assignees, and milestones via gh CLI
  • Create, review, and merge PRs with appropriate status checks and comments
  • Publish a production release with autogenerated notes and assets
  • Trigger, monitor, and download artifacts from a GitHub Actions workflow

Frequently Asked Questions

Add this skill to your agents
Sponsor this space

Reach thousands of developers ↗