gh-code-search（gh 代码搜索）

Step 6: Save Results to File

After generating comprehensive summary, persist for future reference:

1. Generate timestamp:

- Invoke timestamp skill to get deterministic YYYYMMDDHHMMSS format - Example: 20250110143052

1. Sanitize query for filename:

- Convert user's original query to kebab-case slug - Rules: lowercase, spaces → hyphens, remove special chars, max 50 chars - Example: "React hooks useState" → "react-hooks-usestate"

1. Construct file path:

- Directory: docs/research/github/ - Format: <timestamp>-<sanitized-query>.md - Full path: docs/research/github/20250110143052-react-hooks-usestate.md

1. Save using Write tool:

- Content: Full comprehensive summary from Step 5 - Ensures persistence across sessions - User can reference past research

1. Log saved location:

- Inform user where file was saved - Example: "Research saved to docs/research/github/20250110143052-react-hooks-usestate.md"

Why save:

• Comprehensive summaries represent significant analysis work (30-150s of API calls)
• Users may want to reference patterns/trade-offs later
• Builds searchable knowledge base of GitHub research
• Avoids re-running expensive queries for same topics

Error Handling

Common issues:

• Auth errors: Prompt user to run gh auth login --web
• Rate limits: Show remaining quota, reset time. If hit during multi-search, stop gracefully with partial results
• Network failures: Continue with partial results, note which queries failed
• No results for query: Note in summary, adjust subsequent queries to be broader
• All queries return same files: Note low diversity, recommend broader initial queries

Graceful degradation: Partial results are acceptable. Complete summary based on available data.

Limitations

• GitHub API rate limit: 5,000 req/hr authenticated (multi-search uses more quota)
• Each tool invocation fetches top 10 results only
• Skips files >100KB
• Sequential execution takes longer than single query (10-30s per query)
• Provides factual data, not conclusions (Claude interprets patterns)
• Deduplication assumes exact path matches (renamed files treated as unique)

Typical Execution Time

Per query: 10-30 seconds depending on:

• Number of results (100 max)
• File sizes
• Network latency
• API rate limits

Full workflow (3-5 queries): 30-150 seconds

Optimization: If first queries yield sufficient results, skip remaining queries

Integration Notes

Example: User asks "find Claude Code skills doing github search"

// 1. Claude analyzes: Skills use SKILL.md with frontmatter, likely in .claude/skills/
// 2. Claude generates queries:
//    - "filename:SKILL.md github search" (matches SKILL.md files with "github search" text)
//    - "octokit.rest.search language:typescript" (matches actual Octokit API usage)
//    - "gh api language:typescript path:skills" (matches gh CLI usage in skills)
// 3. Claude executes sequentially:
cd plugins/knowledge-work/skills/gh-code-search
pnpm search "filename:SKILL.md github search"
// [analyze results]
pnpm search "octokit.rest.search language:typescript"
// [analyze results]
pnpm search "gh api language:typescript path:skills"
// 4. Claude aggregates, deduplicates, analyzes patterns
// 5. Claude generates comprehensive summary with trade-offs and recommendations

• * *

Testing

Validate workflow with diverse queries:

• Simple: "React hooks" (should generate 3+ queries, combine results)
• Complex: "GitHub Actions TypeScript project setup" (requires config + implementation queries)
• Ambiguous: "state management" (should generate queries for Redux, Zustand, XState, Context)

Check quality:

• Deduplication works (no repeated files in summary)
• Diverse repositories (not all from one repo)
• Summary includes trade-offs and recommendations
• Code snippets are relevant (not arbitrary truncations)