Gen Github Dir

---
name: gen-github-dir
description: Generate complete .github directory with workflows, dependabot, and funding configs for Go projects
argument-hint: "[--force] [--minimal] [--dry-run]"
user-invocable: true
disable-model-invocation: true
allowed-tools: Read, Write, Bash(git:*), Bash(test:*), AskUserQuestion
---

# Generate .github Directory

Instantly create a complete `.github` directory structure for Go projects with production-ready, **mise-based** GitHub Actions workflows, Dependabot configuration, and sponsorship setup.

## Why This Skill Exists

**Problem**: Setting up CI/CD for Go projects requires manually creating multiple workflow files, understanding GitHub Actions syntax, and keeping tool versions in sync between local development and CI - a 30-60 minute process.

**Solution**: One-command generation that:
- Creates a complete `.github` directory (6 files): FUNDING, dependabot, and the linter/coverage/snapshot/release workflows
- Workflows are **mise-based**: each installs tools via `jdx/mise-action@v3` then runs a `task …`, so CI uses the exact versions pinned in `mise.toml`
- Ensures a `mise.toml` exists at the repo root (creates one with detected versions if missing) — the single source of truth shared with local dev
- Configures Dependabot for Go modules, Docker, and GitHub Actions
- Sets up GitHub Sponsors integration
- Preserves all customization comments for user control

## Content Generation Rules

**CRITICAL**: When generating any content (workflow files, commit messages, or any other output):
- **NEVER** add Claude Code attribution or co-authorship
- **NEVER** include phrases like "Generated by Claude", "Created with Claude Code", or similar
- **NEVER** add "Co-Authored-By: Claude" in commit messages or documentation
- All generated content should appear as if written by a human developer
- Focus on technical accuracy and providing working templates

## Process (6 Phases)

### Phase 1: Prerequisites Validation

**Critical checks before proceeding:**

1. **Validate Git repository:**
   ```bash
   git rev-parse --git-dir
   ```
   - If fails: Exit with error "Not a git repository. Run 'git init' first."

2. **Validate Go project:**
   ```bash
   test -f go.mod
   ```
   - If fails: Exit with error "go.mod not found. This skill is for Go projects only."

3. **Check existing .github directory:**
   ```bash
   test -d .github
   ```
   - If exists: Store `existingGithubDir = true`
   - If not exists: Store `existingGithubDir = false`

4. **Verify skill assets directory:**
   - Use Read tool to verify `${CLAUDE_PLUGIN_ROOT}/assets/github-workflows/FUNDING.yml` exists
   - Use Read tool to verify `${CLAUDE_PLUGIN_ROOT}/assets/mise/mise.toml` exists
   - If either fails: Exit with error "Skill assets directory not found at ${CLAUDE_PLUGIN_ROOT}/assets/. Plugin may be corrupted. Reinstall the go-specialist plugin."

5. **Check existing mise.toml:**
   ```bash
   test -f mise.toml
   ```
   - Store `existingMise = true|false`. The workflows depend on `mise.toml`; if it
     is missing this skill will create one (Phase 3.5). An existing `mise.toml`
     is always preserved.

### Phase 2: Argument Parsing

Parse skill arguments from `$argument` string:

**Supported flags:**
- `--force`: Skip confirmation for existing .github directory
- `--minimal`: Generate only essential files (3 files: linter.yml, release.yml, dependabot.yml)
- `--dry-run`: Show preview without writing files

**Parsing logic:**
```
arguments = split($argument by space)
for each arg in arguments:
  if arg == "--force": set forceMode = true
  if arg == "--minimal": set minimalMode = true
  if arg == "--dry-run": set dryRunMode = true
```

**File Selection:**
- **Standard mode** (default): All 6 files
  - FUNDING.yml
  - dependabot.yml
  - workflows/linter.yml
  - workflows/coverage.yml
  - workflows/snapshot.yml
  - workflows/release.yml

- **Minimal mode** (`--minimal`): 3 essential files
  - dependabot.yml
  - workflows/linter.yml
  - workflows/release.yml

### Phase 3: Template Reading

**Read all template files** from skill assets directory:

**Files to read:**

1. **FUNDING.yml**
   - Path: `${CLAUDE_PLUGIN_ROOT}/assets/github-workflows/FUNDING.yml`
   - Target: `.github/FUNDING.yml`

2. **dependabot.yml**
   - Path: `${CLAUDE_PLUGIN_ROOT}/assets/github-workflows/dependabot.yml`
   - Target: `.github/dependabot.yml`

3. **workflows/linter.yml**
   - Path: `${CLAUDE_PLUGIN_ROOT}/assets/github-workflows/workflows/linter.yml`
   - Target: `.github/workflows/linter.yml`

4. **workflows/coverage.yml** [Skip if minimal mode]
   - Path: `${CLAUDE_PLUGIN_ROOT}/assets/github-workflows/workflows/coverage.yml`
   - Target: `.github/workflows/coverage.yml`

5. **workflows/snapshot.yml** [Skip if minimal mode]
   - Path: `${CLAUDE_PLUGIN_ROOT}/assets/github-workflows/workflows/snapshot.yml`
   - Target: `.github/workflows/snapshot.yml`

6. **workflows/release.yml**
   - Path: `${CLAUDE_PLUGIN_ROOT}/assets/github-workflows/workflows/release.yml`
   - Target: `.github/workflows/release.yml`

7. **mise.toml** [Only if `existingMise == false`]
   - Path: `${CLAUDE_PLUGIN_ROOT}/assets/mise/mise.toml`
   - Target: `mise.toml` (repo root)

**Template handling:**
- Store content in memory for Phase 3.5 substitution
- The workflow templates are **static** (no placeholders) — they reference
  `jdx/mise-action@v3` and run `task …`. No per-project substitution is needed.
- Preserve all `# CUSTOMIZE:` comments

**Error handling:**
- If any Read fails: Exit with error "Failed to read template file: {filename}. Plugin may be corrupted."

### Phase 3.5: Auto-Detection & Substitution

**Detection Function Library:** Use the shared detection functions from `${CLAUDE_PLUGIN_ROOT}/assets/detection-functions.md`. Read that file to get the bash detection functions (`detect_git_owner`, `detect_go_version`, `detect_golangci_lint_version`, `detect_goreleaser_version`, `strip_leading_v`, `substitute_version_placeholders`).

**Detection Workflow:**

1. **Detect GitHub username:**
   ```bash
   GITHUB_USERNAME=$(detect_git_owner)
   ```

2. **Substitute in FUNDING.yml template (only if not in minimal mode):**
   ```bash
   if [[ "$minimalMode" != "true" ]]; then
       funding_template=$(echo "$funding_template" | sed "s|\[GITHUB_USERNAME\]|${GITHUB_USERNAME}|g")
   fi
   ```
   - If `GITHUB_USERNAME` is empty: Preserve `[GITHUB_USERNAME]` placeholder with warning (non-blocking)

3. **Workflow templates need no substitution.** They are static and reference
   `jdx/mise-action@v3` + `task …`. All tool versioning lives in `mise.toml`.

4. **Ensure `mise.toml` exists (create if missing):**
   - The generated workflows install tools from `mise.toml`. If the repo has no
     `mise.toml`, create one from the asset with detected versions:
   ```bash
   if [[ "$existingMise" != "true" ]]; then
       GO_VERSION=$(detect_go_version)
       GOLANGCI_LINT_VERSION=$(detect_golangci_lint_version)
       GORELEASER_VERSION=$(detect_goreleaser_version)
       GOLANGCI_LINT_VERSION_BARE=$(strip_leading_v "${GOLANGCI_LINT_VERSION:-v2.2.2}")

       mise_template=$(substitute_version_placeholders "$mise_template" \
           "GO_VERSION=${GO_VERSION:-1.25}" \
           "GOLANGCI_LINT_VERSION_BARE=${GOLANGCI_LINT_VERSION_BARE:-2.2.2}" \
           "GORELEASER_VERSION=${GORELEASER_VERSION:-v2.12.0}")
       # Written in Phase 5.
   fi
   ```
   - If `existingMise == true`: do NOT modify the existing `mise.toml`; note it in
     the report. (Prefer `/gen-taskfiles` to manage tool versions.)

### Phase 4: User Confirmation

**Build preview summary:**

```
Files to be created:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[If standard mode:]
✅ .github/FUNDING.yml
✅ .github/dependabot.yml
✅ .github/workflows/linter.yml
✅ .github/workflows/coverage.yml
✅ .github/workflows/snapshot.yml
✅ .github/workflows/release.yml

Total: 6 files

[If minimal mode:]
✅ .github/dependabot.yml
✅ .github/workflows/linter.yml
✅ .github/workflows/release.yml

Total: 3 files

[If existingMise == false:]
✅ mise.toml (created — pins go/task/golangci-lint/goreleaser for dev + CI)
[If existingMise == true:]
ℹ️  mise.toml already exists — preserved (workflows will use it as-is)

[If standard mode and GITHUB_USERNAME detected:]
✅ Auto-detected Configuration
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

GitHub Settings:
  • GitHub username: <GITHUB_USERNAME> (from git remote)
  • Tool versions (mise.toml): Go <GO_VERSION>, golangci-lint <GOLANGCI_LINT_VERSION_BARE>, goreleaser <GORELEASER_VERSION>

[If existingGithubDir == true:]
⚠️  WARNING: .github directory already exists
[List existing files that will be overwritten:]
- .github/workflows/linter.yml (will be overwritten)
- .github/workflows/release.yml (will be overwritten)
```

**Dry run mode:**
If `dryRunMode == true`:
- Show preview summary above
- Show first 20 lines of each workflow file
- Display next steps guide
- Exit without creating files

**Confirmation logic:**

1. **If `--force` flag provided:** Skip confirmation, proceed to Phase 5

2. **If existing .github without `--force`:**
   ```
   Use AskUserQuestion:
   Question: ".github directory already exists. Overwrite existing workflow files?"
   Options:
   1. "Yes, overwrite files" [Recommended if upgrading workflows]
   2. "Show full preview first"
   3. "Cancel"

   If option 2: Display full content preview, then re-ask confirmation
   If option 3: Exit gracefully
   ```

3. **If new .github directory:**
   ```
   Use AskUserQuestion:
   Question: "Create .github directory with [N] files?"
   Options:
   1. "Yes, create files"
   2. "Show preview first"
   3. "Cancel"
   ```

### Phase 5: File Creation

**Directory creation:**

1. Create `.github/` directory:
   ```bash
   mkdir -p .github
   ```

2. Create `.github/workflows/` subdirectory:
   ```bash
   mkdir -p .github/workflows
   ```

**File writing sequence:**

Write files in order (mise.toml first, then root files, then workflows):

1. `mise.toml` [Only if `existingMise == false`] — repo root, version-substituted
2. `.github/FUNDING.yml` [Skip if minimal mode]
3. `.github/dependabot.yml`
4. `.github/workflows/linter.yml`
5. `.github/workflows/coverage.yml` [Skip if minimal mode]
6. `.github/workflows/snapshot.yml` [Skip if minimal mode]
7. `.github/workflows/release.yml`

**For each file:**
- Use Write tool with full file path
- Write content from Phase 3.5 templates (with substitutions applied)
- Track success/failure status
- Continue with remaining files if one fails (partial success acceptable)

**Error handling:**
- If directory creation fails: Exit with error
- If individual file write fails: Log error, continue with next file
- If all writes fail: Report failure with details
- If partial success: Report which files succeeded/failed

**Track results:**
```
successfulFiles = []
failedFiles = []

for each file:
  try write:
    if success: add to successfulFiles
    if failure: add to failedFiles
```

### Phase 6: Validation & Success Report

**Post-creation validation:** for each file in `successfulFiles`, confirm it exists
(e.g. `test -f .github/workflows/linter.yml`) and is non-zero; move any failure to
`failedFiles`.

**Report to the user** — cover these facts; no fixed layout required:

- **Files written:** each path with a total count — `.github/dependabot.yml`,
  `.github/workflows/linter.yml`, `.github/workflows/release.yml`, plus
  `.github/FUNDING.yml`, `.github/workflows/coverage.yml` and
  `.github/workflows/snapshot.yml` in standard mode. Mark `mise.toml` as created vs.
  preserved.
- **Detected values:** if `GITHUB_USERNAME` was found from the git remote, report it and
  that `FUNDING.yml` needs no editing. If `mise.toml` was created, report the pinned Go,
  golangci-lint and goreleaser versions.
- **Required customizations:** tool versions live in `mise.toml`, not the workflow files —
  editing it changes both local (`mise install`) and CI versions. If `GITHUB_USERNAME` was
  *not* detected, `.github/FUNDING.yml` still contains `[GITHUB_USERNAME]` and must be
  replaced by hand. GitHub Actions permissions must be set under Settings → Actions →
  General: "Workflow permissions" to "Read and write permissions", and
  "Allow GitHub Actions to create and approve pull requests" checked.
- **Optional customizations:** to publish Docker images, uncomment the docker tools
  (buildx, docker-cli) in `mise.toml` and the QEMU + registry-login steps in `snapshot.yml`
  and `release.yml`. The coverage threshold is `limit-coverage: 70` in
  `.github/workflows/coverage.yml`. Dependabot update intervals
  (daily/weekly/monthly) are in `.github/dependabot.yml`.
- **Next steps:** review the workflow files, then `git add .github/ mise.toml` and
  `git commit -m "ci: add mise-based GitHub Actions workflows"`, `git push origin main`,
  and confirm the workflows appear and run under the repository's Actions tab.
- **Docs:** `${CLAUDE_PLUGIN_ROOT}/docs/github-workflows-reference.md` ·
  `${CLAUDE_PLUGIN_ROOT}/docs/github-workflows-troubleshooting.md` · `/gen-goreleaser` for
  `.goreleaser.yml` · `/gen-taskfiles` for `Taskfile.yml` (the lint/snapshot/release tasks
  these workflows call) and `mise.toml` · https://mise.jdx.dev

**On failure:** report which files were written, which failed and why, and that `--force`
retries. Partial success is a warning, total failure an error — for a total failure also
name the likely causes (permissions, disk space, filesystem restrictions).

## Arguments

Arguments are parsed from the `argument` string parameter:

- **`--force`**: Skip confirmation prompt and overwrite existing files
  - Use when: Upgrading existing workflows to latest templates
  - Behavior: Creates backups? No (files are overwritten directly)

- **`--minimal`**: Generate only 3 essential files
  - Includes: dependabot.yml, linter.yml, release.yml
  - Excludes: FUNDING.yml, coverage.yml, snapshot.yml
  - Use when: Quick CI/CD setup without advanced features

- **`--dry-run`**: Preview files without writing to disk
  - Shows: File list, line counts, preview of content
  - Writes: Nothing
  - Use when: Reviewing what will be created before committing

**Parsing example:**
```
argument = "--force --minimal"
Split by space, check for each flag:
- forceMode = true
- minimalMode = true
- dryRunMode = false
```

## Error Handling

### Critical Errors (Exit Immediately)

**Not a Git repository:**
```
❌ Error: Not a git repository

This skill requires a Git repository. Initialize one:
  git init
  git add .
  git commit -m "Initial commit"
```

**Not a Go project:**
```
❌ Error: go.mod not found

This skill is for Go projects only. Initialize a Go module:
  go mod init github.com/username/project
```

**Skill assets missing:**
```
❌ Error: Skill assets directory not found

The go-specialist plugin may be corrupted. Try:
1. Reinstalling the plugin
2. Updating Claude Code to latest version
3. Reporting issue at: https://github.com/sgaunet/claude-plugins/issues
```

### Warning Errors (Continue with Others)

**Existing .github directory:**
- Without `--force`: Request user confirmation
- With `--force`: Overwrite silently

**Individual file write failure:**
- Log error message
- Continue with remaining files
- Report partial success at end

**Missing optional asset (e.g., FUNDING.yml):**
- Skip file with warning
- Continue with other files
- Note in final report

### Recovery Actions

**If mkdir fails:**
```
❌ Error: Failed to create .github directory

Check:
1. Current directory is writable
2. Sufficient disk space
3. No existing .github file (not directory) blocking creation

Current permissions: [show with ls -ld .]
```

**If all writes fail:**
```
❌ Error: Failed to write any workflow files

This may indicate:
1. Permission issues in .github directory
2. Disk full
3. File system mounted read-only

Check disk space: df -h .
Check permissions: ls -la .github/
```

## File Mapping

Complete mapping from skill assets to target locations:

| Source Path | Target (Relative to CWD) | Mode |
|-------------|--------------------------|------|
| `${CLAUDE_PLUGIN_ROOT}/assets/mise/mise.toml` | `mise.toml` | Create-if-missing |
| `${CLAUDE_PLUGIN_ROOT}/assets/github-workflows/FUNDING.yml` | `.github/FUNDING.yml` | Standard |
| `${CLAUDE_PLUGIN_ROOT}/assets/github-workflows/dependabot.yml` | `.github/dependabot.yml` | All |
| `${CLAUDE_PLUGIN_ROOT}/assets/github-workflows/workflows/linter.yml` | `.github/workflows/linter.yml` | All |
| `${CLAUDE_PLUGIN_ROOT}/assets/github-workflows/workflows/coverage.yml` | `.github/workflows/coverage.yml` | Standard |
| `${CLAUDE_PLUGIN_ROOT}/assets/github-workflows/workflows/snapshot.yml` | `.github/workflows/snapshot.yml` | Standard |
| `${CLAUDE_PLUGIN_ROOT}/assets/github-workflows/workflows/release.yml` | `.github/workflows/release.yml` | All |

**Mode Legend:**
- **All**: Created in both standard and minimal modes
- **Standard**: Only created in standard mode (skipped in minimal)
- **Create-if-missing**: Written only when the repo has no `mise.toml`; an existing one is preserved

## Integration with Other Skills

**Works with:**
- `/commit`: Commit generated .github directory
- `/gen-goreleaser`: Generate .goreleaser.yml config (required for release/snapshot workflows)
- `/gen-linter`: Generate .golangci.yml config (required for linter workflow)
- `/create-issue`: Create issue to track customization tasks

**Typical Workflow:**
```bash
# 1. Generate dev tooling first (Taskfile.yml + mise.toml)
/gen-taskfiles

# 2. Generate .github directory (reuses mise.toml; creates it if you skipped step 1)
/gen-github-dir

# 3. Generate supporting configs
/gen-linter          # Creates .golangci.yml
/gen-goreleaser      # Creates .goreleaser.yml

# 4. Commit everything
git add .github/ mise.toml Taskfile*.yml .golangci.yml .goreleaser.yml
git commit -m "ci: add mise-based GitHub Actions workflows and supporting configs"

# 5. Push and verify
git push origin main
# Check: https://github.com/username/repo/actions
```

## Prerequisites for Workflows

**Required for workflows to function:**

1. **mise.toml** (auto-created by this skill if missing):
   - Pins the tool versions installed by `jdx/mise-action@v3` in every workflow
   - Generated/managed canonically by `/gen-taskfiles`
   - The single source of truth shared between local dev and CI

2. **Taskfile.yml** with required tasks (`lint`, `snapshot`, `release`):
   ```yaml
   version: '3'
   tasks:
     lint:
       cmds: [golangci-lint run ./...]
     snapshot:
       cmds: [goreleaser release --snapshot --clean]
     release:
       cmds: [goreleaser release --clean]
   ```
   - Generate with `/gen-taskfiles` (also emits mise.toml)

3. **.golangci.yml** configuration:
   - Generate with `/gen-linter` (golangci-lint itself comes from mise.toml)

4. **.goreleaser.yml** configuration:
   - Generate with `/gen-goreleaser` (required for snapshot.yml and release.yml)

5. **GitHub repository settings:**
   - Settings → Actions → General
   - Workflow permissions: "Read and write permissions"
   - Allow GitHub Actions to create and approve pull requests

**Optional enhancements:**

1. **Coverage badge in README.md:**
   ```markdown
   ![Coverage](https://raw.githubusercontent.com/username/repo/main/coverage-badge.svg)
   ```

2. **GitHub Sponsors setup:**
   - Edit .github/FUNDING.yml
   - Enable GitHub Sponsors for your account
   - Configure funding platforms

3. **Dependabot auto-merge:**
   - Settings → Branches → Branch protection
   - Enable "Allow auto-merge"
   - Configure required checks

## Template Customization Points

All template files include `# CUSTOMIZE:` comments marking required changes:

**FUNDING.yml:**
- `github: [YOUR_GITHUB_USERNAME]` → Replace with your username

**mise.toml:**
- Tool versions (`go`, `golangci-lint`, `goreleaser`) → adjust as needed (used by dev + CI)
- Docker tools (`buildx`, `docker-cli`) → uncomment if publishing images

**workflows/*.yml:**
- Tag patterns in release.yml → Adjust semver format if needed
- Optional docker block in snapshot.yml / release.yml → uncomment for image publishing

**dependabot.yml:**
- `interval: monthly` → Change to daily/weekly for active projects
- `open-pull-requests-limit: 10` → Adjust PR concurrency

**coverage.yml:**
- `limit-coverage: "70"` → Adjust coverage threshold
- Badge repository reference → Update if using fork
- `sed -i '/cmd/d'` → Remove if including cmd package in coverage

## Best Practices

**Before running this skill:**
1. Ensure git repository initialized
2. Have go.mod configured
3. Review skill documentation: `${CLAUDE_PLUGIN_ROOT}/docs/`

**After generation:**
1. Review all `# CUSTOMIZE:` comments in workflow files
2. Test workflows locally if possible (act, nektos/act)
3. Create required supporting files (Taskfile.yml, .goreleaser.yml)
4. Commit with meaningful message
5. Monitor first workflow runs for errors

**Ongoing maintenance:**
1. Keep dependencies updated via Dependabot PRs
2. Review GitHub Actions version updates monthly
3. Adjust coverage thresholds as codebase matures
4. Add custom workflow jobs as project needs evolve

## Limitations

**This skill does NOT:**
- Generate Taskfile.yml (use `/gen-taskfiles`, which also manages mise.toml)
- Generate .goreleaser.yml (use `/gen-goreleaser` skill)
- Generate .golangci.yml (use `/gen-linter` skill)
- Modify an existing mise.toml (it is preserved; only created when missing)
- Modify existing workflow files intelligently (use `--force` to overwrite)
- Validate that workflows will work (requires proper setup)
- Configure GitHub repository settings (must be done via UI)

**Scope boundaries:**
- Only handles `.github/` directory structure
- Templates are opinionated (aligned with gitlab-backup project patterns)
- Assumes standard Go project structure
- Requires manual customization post-generation

## Examples

```bash
# Standard generation (6 files)
/gen-github-dir

# Minimal setup (3 essential files)
/gen-github-dir --minimal

# Preview before creating
/gen-github-dir --dry-run

# Overwrite existing workflows
/gen-github-dir --force

# Minimal with force (quick upgrade)
/gen-github-dir --minimal --force

# Preview minimal mode
/gen-github-dir --minimal --dry-run
```

## Output Summary

**Standard mode (default):**
- 6 `.github` files + mise.toml (if missing)
- Comprehensive, mise-based CI/CD pipeline

**Minimal mode (`--minimal`):**
- 3 `.github` files + mise.toml (if missing)
- Essential linting + releases

**Dry run mode (`--dry-run`):**
- 0 files created
- Preview shown
- Safe exploration