go-skill-extractor

name: go-skill-extractor
description: "Dispatch when a Go codebase has accumulated repeated patterns (idiomatic or anti-) worth capturing as a new gophers skill. Walks the module, surfaces repeated structural shapes (3+ occurrences in 2+ packages), confirms each candidate is not already covered by an existing skill, and emits a draft SKILL.md proposal that follows the gophers template. Use periodically (monthly / per-quarter) on services that have grown new conventions, or after a large refactor that introduced new patterns."
tools: Read, Glob, Grep, Bash
model: opus
license: MIT
metadata:
  author: muratmirgun
  version: "0.1.0"
  homepage: https://github.com/muratmirgun/gophers
  emoji: "🔬"
  skill: (meta — references multiple skills)

go-skill-extractor

A meta-agent that finds repeated Go patterns in a codebase and proposes them as new gophers skills. It does **not** create the SKILL.md on disk — it returns a *draft* proposal markdown the maintainer can iterate on.

When to Dispatch

Dispatch when:

• A service has grown past 50 packages and the team notices "we always do X"
• A monthly / quarterly audit on a long-lived monorepo
• After a large refactor that introduced new internal conventions
• A reviewer keeps copy-pasting the same nit comment across PRs

**Do not dispatch when:**

• The codebase is < 10 packages (not enough signal)
• The repeated pattern is just a function helper (factor it into a Go helper, not a skill)
• The pattern is project-specific (e.g., one company's auth flow) — those are runbooks, not skills
• An existing gophers skill already covers it (check the [Skills Catalog](../README.md#-skills-catalog) first)

Input Contract

| Input | Format | Example | |---|---|---| | `module_root` | path | `./` | | `min_occurrences` (optional) | integer | `3` (default) | | `min_packages` (optional) | integer | `2` (default) | | `existing_skills_dir` (optional) | path | `../gophers/skills` (defaults to comparing against the [Skills Catalog](../README.md)) | | `domain` (optional) | comma-separated topic hints | `errors,logging,http` |

Process

1. **Enumerate packages.**

   go list -f '{{.ImportPath}} {{.Dir}}' ./...

2. **Detect candidate patterns.** Look for structurally repeated shapes (≥ `min_occurrences` across ≥ `min_packages` packages):

• **Error patterns** — repeated wrapping shapes, sentinel definitions, custom error types
• **HTTP patterns** — middleware ordering, response shapes, request-id propagation
• **Logging patterns** — repeated logger field sets, log-and-return mistakes
• **Concurrency patterns** — same worker-pool shape, same select-with-context skeleton
• **Init patterns** — repeated config loading, repeated DI wiring
• **Testing patterns** — repeated fake shapes, repeated `httptest` harnesses

3. **For each candidate, run negative coverage check.** For every existing skill in `existing_skills_dir`:

• `grep -i <candidate-keyword> skills/*/SKILL.md`
• If any hit, skip the candidate (already covered)

4. **Score candidates** by (occurrences × packages × novelty). Return the top 3. 5. **For each surviving candidate, draft a SKILL.md proposal** following the gophers template — see Output Contract below. 6. **Cite real `file:line` locations** for every claim (this is not a hypothetical proposal — it must reference actual code).

Output Contract

Return a markdown summary, then a fenced draft SKILL.md per candidate (up to 3):

## Skill-Extraction Report — <module_path>

**Module:** github.com/example/myapp
**Packages scanned:** 87
**Threshold:** ≥ 3 occurrences in ≥ 2 packages
**Existing-coverage check:** compared against 26 gophers skills

### Candidates Found

| Rank | Proposed Name | Occurrences | Packages | Existing Coverage | Verdict |
|---|---|---|---|---|---|
| 1 | go-otel-baggage | 14 | 7 | none | ✅ propose |
| 2 | go-http-middleware-order | 9 | 4 | partial (go-observability mentions it briefly) | ⚠️ extend existing |
| 3 | go-config-loading | 11 | 6 | none | ✅ propose |
| 4 | go-pagination-cursors | 5 | 2 | none | ⚠️ borderline (n=5) |

### Proposed Skill 1: go-otel-baggage

**Evidence (cited from the codebase):**
- `internal/middleware/trace.go:42` — adds `tenant_id` to baggage on inbound request
- `internal/clients/billing.go:88` — reads baggage on outbound HTTP call
- `internal/jobs/reindex.go:120` — propagates baggage through goroutine
- `internal/grpc/interceptor.go:67` — extracts baggage from incoming metadata
- (10 more occurrences across 3 packages)

**Why this is skill-worthy:**
- 14 occurrences across 7 packages — exceeds threshold
- Not covered by `go-observability` (which focuses on metrics/traces, not baggage specifically)
- Has a clear failure mode (baggage dropped at process boundary) that recurs in this codebase

**Draft SKILL.md:**

```markdown
---
name: go-otel-baggage
description: "Use when propagating OpenTelemetry baggage across Go services — adding tenant/user IDs at the edge, forwarding through HTTP/gRPC clients, surviving goroutine handoffs, and reading on the receiving side. Apply when a service handles multi-tenant requests, when traces are missing context fields, or when a downstream service cannot identify the originating caller."
user-invocable: false
license: MIT
metadata:
  author: <author>
  version: "0.1.0"
  openclaw:
    emoji: "🎒"
    requires: { bins: [go] }
allowed-tools: Read Edit Write Glob Grep Bash(go:*)
---

# Go OpenTelemetry Baggage

[1-2 sentence philosophy]

## Core Rules

1. Add baggage at the edge (middleware), never deeper.
2. Propagate explicitly across every process boundary (HTTP, gRPC, message queue).
3. ...

## Decision Table
...

## Anti-Patterns
| Anti-pattern | Do this instead |
| ... | ... |

## Verification Checklist
- [ ] ...

## References
- [references/edge-middleware.md](references/edge-middleware.md)

---

Proposed Skill 2: go-config-loading

...

---

Skipped Candidates

• **go-error-handling** — already cove