AI Agent Operational Guide: GitHub Issues Knowledge Base

Purpose: Comprehensive operational guide for AI coding agents (Claude, Copilot, etc.) to manage engineering knowledge stored in GitHub Issues.

What This Repository IS:

Complete operational guide for AI agents performing GitHub Issues operations
Empirically-tested workflows and decision trees (200+ test cases, 88% avg AI effectiveness)
Tool selection guidance (native gh CLI, extensions, AI models)

What This Repository IS NOT:

The knowledge base itself (that's in GitHub Issues - the actual issues you create)
Generic GitHub CLI documentation (see official docs for that)

Repository: https://github.com/terrylica/claude-code-skills-github-issues

Quick Links

📖 Documentation - Guides, research, and references
🔍 Search Guide - Native GitHub CLI search (quick start + complete reference)
🤖 AI Agent Guide - Operational guide for AI coding agents
🔌 Extensions - GitHub CLI extensions tested and recommended

Installation

Two installation methods available based on your needs:

1. Global User-Level (Recommended for Individual Use)

Available across ALL your Claude Code sessions.

/plugin marketplace add terrylica/claude-code-skills-github-issues
/plugin install github-issues-operations@terrylica/claude-code-skills-github-issues

Verification: Run /plugin to confirm github-issues-operations is installed.

2. Project-Local (Recommended for Teams)

Available only in THIS project. Committed to git for team access.

git submodule add https://github.com/terrylica/claude-code-skills-github-issues.git .claude/plugins/github-issues

📖 Complete Installation Guide: See INSTALLATION.md for:

Prerequisites and version requirements
Detailed installation steps (4 methods with comparison table)
Verification and testing procedures
Updates, uninstallation, and lifecycle management
Troubleshooting common issues
Team distribution and version pinning

🤖 For AI Agents:

This repository documents operations for managing knowledge in GitHub Issues. The actual knowledge base lives in Issues. This is your operational manual.

Quick Start: See AI_AGENT_OPERATIONAL_GUIDE.md for complete tool selection decision trees and workflows.

What This Repository Contains

AI Agent Operations Documented

This guide documents 5 categories of operations for AI agents managing knowledge in GitHub Issues:

AI-Powered Operations (gh-models) - Issue summarization, auto-labeling, Q&A, documentation generation
File Search Operations (gh-grep) - Regex-based file search, multi-repository search
Issue Search & Discovery (native gh CLI) - Content search, complex filtering, metadata queries
Issue Lifecycle Operations (native gh CLI) - CRUD operations, state management, comments, assignments
Label & Milestone Management (native gh CLI) - Label/milestone CRUD, cloning, batch operations

Complete Details: See AI_AGENT_OPERATIONAL_GUIDE.md for full operation reference, tool selection decision trees, and empirically-tested workflows.

Getting Started

Prerequisites

Install GitHub CLI extensions - See GITHUB_CLI_EXTENSIONS.md for installation instructions.

Search Your Knowledge Base

# Search issues with native GitHub CLI
gh search issues "authentication" --repo=terrylica/claude-code-skills-github-issues

# Search current repository
gh issue list --search "authentication"

# Filter by metadata
gh search issues --label=bug --state=open --assignee=@me

# Search files with regex (gh-grep extension)
gh grep "Bug.*critical" --owner terrylica --repo knowledgebase

AI-Powered Workflows

# List available AI models
gh models list

# Get AI assistance
gh models run "openai/gpt-4.1" "Summarize this: $(gh issue view 123 --json body --jq .body)"

Documentation Structure

docs/
├── guides/           Operational guides for AI agents and humans
│   └── AI_AGENT_OPERATIONAL_GUIDE.md       # Complete operational guide
├── research/         Platform analysis and capabilities
│   ├── GITHUB_CLI_EXTENSIONS.md            # Extension ecosystem (consolidated)
│   └── GITHUB_NATIVE_SEARCH_CAPABILITIES.md # Search guide (quick start + reference)
├── references/       Complete technical references
│   └── github-cli-issues-comprehensive-guide.md  # 200+ test cases
└── testing/          Test reports and POC results
    └── GH-MODELS-POC-RESULTS.md            # AI assistance POC (88% effectiveness)

Key Features

✅ Native GitHub CLI Capabilities

Powerful built-in features:

Search: Title, body, and comments
Filter: 30+ qualifiers (labels, dates, users, state, milestones)
Sort: Comments, reactions, dates
Output: JSON for scripting and automation
Labels: Full label management (create, edit, delete, clone)

✅ Community Extensions

Actively maintained extensions for AI agents (tested 2025-10-23):

gh-grep: File search with regex (updated yesterday, 211 stars)
gh-models: Official AI assistance (updated 9 days ago)

✅ Comprehensive Testing

200+ test cases covering:

CRUD operations (create, read, update, delete)
Search and filtering (60+ queries)
Metadata and labels (40+ tests)
State and lifecycle (30+ tests)
Comments and interactions (40+ tests)
Extension functionality verification
AI assistance workflows (5 POC tests, 88% effectiveness)