GitHub Actions, Workflows, act local testing, community health files, Dependabot consolidation, and PR review

version
0.3.17
GitHub stars
27

Install

/plugin install github@vinnie357

Run it inside Claude Code after adding the marketplace with /plugin marketplace add vinnie357/claude-skills.

Contents

Discovered from source

Skills 6

act - Local GitHub Actions Testing

Activate when testing GitHub Actions workflows locally, debugging workflow issues, or developing actions without committing to remote repositories. This skill covers act installation, configuration, and usage patterns.

Installation

Install via mise: mise install act (pinned in the github plugin's mise.toml), then verify with act --version. Homebrew, Linux script, source, and Chocolatey methods: see references/setup-and-config.md.

How act Works

act reads workflow files from .github/workflows/ and:

  1. Determines which actions and jobs to execute
  2. Pulls or builds required Docker images
  3. Creates containers matching GitHub's runner environment
  4. Executes steps in isolated containers
  5. Provides output matching GitHub Actions format

Key Concept: act uses Docker to simulate GitHub's runner environment locally.

Prerequisites

act requires a running Docker daemon (verify with docker ps) and valid .github/workflows/*.yml files. Details: see references/setup-and-config.md.

Basic Usage

List Available Workflows

# List all workflows
act -l

# Output:
# Stage  Job ID  Job name  Workflow name  Workflow file  Events
# 0      build   build     CI             ci.yml         push,pull_request
# 0      test    test      CI             ci.yml         push,pull_request

Run Default Event (push)

# Run all jobs triggered by push event
act

# Run specific job
act -j build

# Run specific workflow
act -W .github/workflows/ci.yml

Run Specific Events

# Pull request event
act pull_request

# Manual workflow dispatch
act workflow_dispatch

# Push to specific branch
act push -e .github/workflows/push-event.json

# Schedule event
act schedule

Dry Run

# Show what would run without executing
act -n

# Show with full details
act -n -v

Event Payloads

Custom event JSON and workflow_dispatch input payloads, passed with -e file.json: see references/setup-and-config.md. A worked PR-event example stays under Common Patterns below.

Secrets Management

Via Command Line

# Single secret
act -s GITHUB_TOKEN=ghp_xxxxx

# Multiple secrets
act -s API_KEY=key123 -s DB_PASSWORD=pass456

Via .secrets File

Create .secrets file (add to .gitignore):

GITHUB_TOKEN=ghp_xxxxx
API_KEY=key123
DB_PASSWORD=pass456

Run with secrets file:

act --secret-file .secrets

Environment Variables

# Use existing env var
act -s GITHUB_TOKEN

# Set from command
export MY_SECRET=value
act -s MY_SECRET

Configuration

.actrc defaults, custom runner images, and image size trade-offs (medium catthehacker/ubuntu:act-latest recommended over micro): see references/setup-and-config.md.

Environment Variables

Via .env File

Create .env file:

NODE_ENV=test
API_URL=http://localhost:3000
LOG_LEVEL=debug

Use with act:

act --env-file .env

Via Command Line

act --env NODE_ENV=test --env API_URL=http://localhost:3000

Advanced Usage

--bind, --reuse, per-platform images, --container-architecture (needed on Apple silicon), networking (--network defaults to host; --container-daemon-socket is the Docker socket URI), and the artifact server: see references/setup-and-config.md.

Debugging

Verbose Output

# Verbose logging
act -v

# Very verbose (debug level)
act -vv

Watch Mode

# Watch for file changes and re-run
act --watch

Container Inspection

# List act containers
docker ps -a | grep act

# Inspect specific container
docker inspect <container-id>

# View logs
docker logs <container-id>

Limitations and Differences

Not Supported by act

  • Some GitHub-hosted runner features
  • GitHub Apps and installations
  • OIDC token generation
  • Some GitHub API interactions
  • Certain cache implementations
  • Job summaries and annotations (limited)

Workarounds

Missing tools:

steps:
  - name: Install missing tool
    run: |
      if ! command -v tool &> /dev/null; then
        apt-get update && apt-get install -y tool
      fi

GitHub API calls:

# Use GITHUB_TOKEN from secrets
- env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: gh api repos/${{ github.repository }}/issues

Common Patterns

Testing Pull Request Workflow

# Create PR event payload
cat > pr-event.json << EOF
{
  "pull_request": {
    "number": 1,
    "head": { "ref": "feature" },
    "base": { "ref": "main" }
  }
}
EOF

# Run PR workflow
act pull_request -e pr-event.json -j test

CI/CD Pipeline Testing

# Test entire CI pipeline
act push

# Test specific stages
act push -j build
act push -j test
act push -j deploy --secret-file .secrets

Matrix Testing

# Run matrix strategy locally
act -j test

# Test specific matrix combination (modify workflow temporarily)
act -j test --matrix node-version:24

Workflow Development Cycle

# 1. List jobs
act -l

# 2. Dry run
act -n -j build

# 3. Run with verbose output
act -v -j build

# 4. Iterate and test
act --reuse -j build

Troubleshooting

Docker Issues

Error: Cannot connect to Docker daemon

# Start Docker
# macOS: Start Docker Desktop
# Linux:
sudo systemctl start docker

Error: Permission denied

# Add user to docker group (Linux)
sudo usermod -aG docker $USER
newgrp docker

Image Pull Issues

Error: Failed to pull image

# Use specific image version
act -P ubuntu-latest=ubuntu:22.04

# Or use act's recommended images
act -P ubuntu-latest=catthehacker/ubuntu:act-latest

Workflow Not Found

Error: No workflows found

# Verify workflow files exist
ls -la .github/workflows/

# Check workflow syntax
act -n -v

Secret Issues

Error: Secret not found

# List required secrets from workflow
grep -r "secrets\." .github/workflows/

# Provide via command line
act -s SECRET_NAME=value

# Or use secrets file
act --secret-file .secrets

Action Failures

Error: Action not found or fails

# Ensure action versions are compatible
# Some actions may not work locally

# Use alternative actions if needed
# Or skip problematic steps under act. There is no 'act' event — act passes
# the real event name — so test the ACT env var (per nektos/act docs):
- name: Problematic step
  if: ${{ !env.ACT }}
  uses: some/action@v1

Platform Differences

Error: Command not found

# Use medium-sized images with more tools
act -P ubuntu-latest=catthehacker/ubuntu:act-latest

# Or install tools in workflow
- run: apt-get update && apt-get install -y <tool>

Best Practices

.actrc Configuration

Commit an .actrc so every run gets the same platform image, secrets file, and architecture flags — full example in references/setup-and-config.md.

.gitignore Entries

# act secrets and config
.secrets
.env

# act artifacts
/tmp/artifacts/

Conditional Logic for Local Testing

act sets the ACT environment variable inside its containers — per nektos/act docs, which give this exact !env.ACT form. The event name is whatever you invoke (act pull_request runs as pull_request; a bare act runs as push), so there is no act event to test for:

steps:
  # Skip in local testing
  - name: Deploy
    if: ${{ !env.ACT }}
    run: ./deploy.sh

  # Run only in local testing
  - name: Local setup
    if: ${{ env.ACT }}
    run: ./local-setup.sh

Fast Feedback Loop

# Use reuse flag for faster iterations
act --reuse -j test

# Run specific job being developed
act -j my-new-job -v

# Watch mode for continuous testing
act --watch -j test

Integration with Development Workflow

Pre-commit Testing

# Test before committing
act -j test && git commit -m "message"

# Git hook (.git/hooks/pre-commit)
#!/bin/bash
act -j test --quiet

For quick validation use the dry run (act -n, see Basic Usage). For CI parity, pin the same runner images and secrets structure locally via .actrc — see references/setup-and-config.md.

Scripts and Automation

Installation Script

The plugin includes an installation script at scripts/install-act.nu (nushell). It installs act via mise when available, falling back to Homebrew on macOS, the nektos/act install script on Linux, or Chocolatey on Windows, then verifies the install with act --version.

Run with:

nu scripts/install-act.nu

Anti-Fabrication Requirements

  • Execute act --version before documenting version numbers
  • Use act -l to verify actual workflows before claiming their presence
  • Execute docker ps to confirm Docker is running before troubleshooting
  • Run act -n to validate workflow syntax before claiming correctness
  • Execute actual act commands to verify behavior before documenting output format
  • Use docker images to verify available images before recommending specific versions
  • Never claim success rates or performance metrics without actual measurement
  • Execute act -v to observe actual error messages before documenting troubleshooting steps
  • Use Read tool to verify workflow files exist before testing them with act
  • Run actual event payloads through act before claiming they work correctly

References

  • references/setup-and-config.md — installation methods, prerequisites, .actrc configuration, runner images, event payloads, and advanced flags (--bind, --reuse, networking, artifact server)

GitHub Actions

Activate when creating, modifying, troubleshooting, or optimizing GitHub Actions components. This skill covers action development, marketplace integration, and best practices.

Action Types

JavaScript Actions

Execute directly on runners with fast startup and cross-platform compatibility.

Structure:

my-action/
├── action.yml        # Metadata and interface
├── index.js          # Entry point
├── package.json      # Dependencies
└── node_modules/     # Bundled dependencies

Key Requirements:

  • Use @actions/core for inputs/outputs
  • Use @actions/github for GitHub API access
  • Bundle all dependencies (use @vercel/ncc)
  • Support Node.js LTS versions

Current toolkit majors are ESM-only — @actions/core 3.x, @actions/github 9.x, @actions/exec 3.x, @actions/cache 6.x. Each publishes "type": "module" with an exports map offering only an import condition, so require('@actions/core') throws ERR_PACKAGE_PATH_NOT_EXPORTED even on node24: Node's require(esm) finds no require or module-sync condition to match. Set "type": "module" in the action's package.json and use import — ncc emits an ES module automatically inside such a package boundary, so the bundling step below is unchanged. An action that cannot migrate must use dynamic await import(...).

Example action.yml:

name: 'My JavaScript Action'
description: 'Performs custom task'
inputs:
  token:
    description: 'GitHub token'
    required: true
  config:
    description: 'Configuration file path'
    required: false
    default: 'config.yml'
outputs:
  result:
    description: 'Action result'
runs:
  using: 'node24'
  main: 'dist/index.js'

Docker Container Actions

Provide consistent execution environment with all dependencies packaged.

Structure:

my-action/
├── action.yml
├── Dockerfile
├── entrypoint.sh
└── src/

Key Requirements:

  • Use lightweight base images (Alpine when possible)
  • Set proper file permissions
  • Handle signals gracefully
  • Output to STDOUT/STDERR correctly

Example Dockerfile:

FROM alpine:3.24

RUN apk add --no-cache bash curl jq

COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh

ENTRYPOINT ["/entrypoint.sh"]

Composite Actions

Combine multiple steps and actions into reusable units.

Structure:

name: 'Setup Environment'
description: 'Configure development environment'
inputs:
  node-version:
    description: 'Node.js version'
    required: false
    default: '24'
runs:
  using: 'composite'
  steps:
    - uses: actions/setup-node@v7
      with:
        node-version: ${{ inputs.node-version }}
    - run: npm ci
      shell: bash
    - run: npm run build
      shell: bash

Action Metadata (action.yml)

Required Fields

name: 'Action Name'           # Marketplace display name
description: 'What it does'   # Clear, concise purpose
runs:                         # Execution configuration
  using: 'node24'            # or 'docker' or 'composite'

Optional Fields

author: 'Your Name'
branding:                    # Marketplace icon/color
  icon: 'activity'
  color: 'blue'
inputs:                      # Define all inputs
  input-name:
    description: 'Purpose'
    required: true
    default: 'value'
outputs:                     # Define all outputs
  output-name:
    description: 'What it contains'

Inputs and Outputs

Reading Inputs

JavaScript:

import * as core from '@actions/core';
const token = core.getInput('token', { required: true });
const config = core.getInput('config') || 'default.yml';

Shell:

TOKEN="${{ inputs.token }}"
CONFIG="${{ inputs.config }}"

Setting Outputs

JavaScript:

core.setOutput('result', 'success');
core.setOutput('artifact-url', artifactUrl);

Shell:

echo "result=success" >> $GITHUB_OUTPUT
echo "artifact-url=$ARTIFACT_URL" >> $GITHUB_OUTPUT

GitHub Actions Toolkit

Essential npm packages for JavaScript actions:

@actions/core

import * as core from '@actions/core';

// Inputs/Outputs
const input = core.getInput('name');
core.setOutput('name', value);

// Logging
core.info('Information message');
core.warning('Warning message');
core.error('Error message');
core.debug('Debug message');

// Grouping
core.startGroup('Group name');
// ... operations
core.endGroup();

// Failure
core.setFailed('Action failed: reason');

// Secrets
core.setSecret('sensitive-value');  // Masks in logs

// Environment
core.exportVariable('VAR_NAME', 'value');

@actions/github

import * as github from '@actions/github';

// Context
const context = github.context;
console.log(context.repo);        // { owner, repo }
console.log(context.sha);         // Commit SHA
console.log(context.ref);         // Branch/tag ref
console.log(context.actor);       // Triggering user
console.log(context.payload);     // Webhook payload

// Octokit client
const token = core.getInput('token');
const octokit = github.getOctokit(token);

// API operations
const { data: issues } = await octokit.rest.issues.listForRepo({
  owner: context.repo.owner,
  repo: context.repo.repo,
  state: 'open'
});

@actions/exec

import * as exec from '@actions/exec';

// Execute commands
await exec.exec('npm', ['install']);

// Capture output
let output = '';
await exec.exec('git', ['log', '--oneline'], {
  listeners: {
    stdout: (data) => { output += data.toString(); }
  }
});

Security Best Practices

Input Validation

Always validate and sanitize inputs:

import * as core from '@actions/core';

function validateInput(input) {
  // Check for command injection
  if (/[;&|`$()]/.test(input)) {
    throw new Error('Invalid characters in input');
  }
  return input;
}

const userInput = core.getInput('user-input');
const safeInput = validateInput(userInput);

Token Permissions

Request minimal required permissions:

permissions:
  contents: read           # Read repository
  pull-requests: write     # Comment on PRs
  issues: write           # Create issues

Secret Handling

// Mask secrets in logs
core.setSecret(sensitiveValue);

// Never log tokens
core.debug(`Token: ${token}`);  // ❌ WRONG
core.debug('Token received');   // ✅ CORRECT

// Secure token usage
const octokit = github.getOctokit(token);
// Token automatically included in requests

Dependency Security

# Audit dependencies
npm audit

# Use specific versions
npm install @actions/core@3.0.1

# Bundle dependencies
npm install -g @vercel/ncc
ncc build index.js -o dist

Marketplace Publishing

Prerequisites

  • Public repository
  • action.yml in repository root
  • README.md with usage examples
  • LICENSE file
  • Repository topics (optional)

Publishing Process

  1. Create release with semantic version tag:
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0
  1. Create GitHub Release from tag
  2. Check "Publish this Action to GitHub Marketplace"
  3. Select primary category
  4. Verify branding icon/color

Version Management

Use semantic versioning with major version tags:

# Release v1.2.3
git tag -a v1.2.3 -m "Release v1.2.3"
git tag -fa v1 -m "Update v1 to v1.2.3"
git push origin v1.2.3 v1 --force

Users reference by major version:

- uses: owner/action@v1  # Tracks latest v1.x.x

Testing Actions Locally

Use act for local testing (see act skill):

# Test action in current directory
act -j test

# Test with specific event
act push

# Test with secrets
act -s GITHUB_TOKEN=ghp_xxx

Common Patterns

Matrix Testing Action

# action.yml
name: 'Matrix Test Runner'
description: 'Run tests across multiple configurations'
inputs:
  matrix-config:
    description: 'JSON matrix configuration'
    required: true
runs:
  using: 'composite'
  steps:
    - run: |
        echo "Testing with config: ${{ inputs.matrix-config }}"
        # Parse and execute tests
      shell: bash

Cache Management Action

import * as core from '@actions/core';
import * as cache from '@actions/cache';
import * as exec from '@actions/exec';
import * as glob from '@actions/glob';

async function run() {
  const paths = [
    'node_modules',
    '.npm'
  ];

  // hashFiles is async and lives in @actions/glob — the bare hashFiles()
  // of workflow YAML has no JavaScript equivalent.
  const hash = await glob.hashFiles('package-lock.json');
  const key = `deps-${process.platform}-${hash}`;

  // Restore cache
  const cacheKey = await cache.restoreCache(paths, key);

  if (!cacheKey) {
    core.info('Cache miss, installing dependencies');
    await exec.exec('npm', ['ci']);
    await cache.saveCache(paths, key);
  } else {
    core.info(`Cache hit: ${cacheKey}`);
  }
}

Artifact Upload Action

import * as core from '@actions/core';
import { DefaultArtifactClient } from '@actions/artifact';

async function uploadArtifact() {
  const artifactClient = new DefaultArtifactClient();
  const files = [
    'dist/bundle.js',
    'dist/styles.css'
  ];

  const rootDirectory = 'dist';
  const options = {
    retentionDays: 10
  };

  const { id, size } = await artifactClient.uploadArtifact(
    'build-artifacts',
    files,
    rootDirectory,
    options
  );

  core.setOutput('artifact-id', id);
  core.info(`Uploaded ${size} bytes`);
}

@actions/artifact v2+ replaced the artifact.create() factory with DefaultArtifactClient and returns {id, size, digest} instead of artifactId; uploadArtifact still takes rootDirectory third. The v1 continueOnError option is gone — options are retentionDays, compressionLevel, skipArchive. Uploading twice to one artifact name is no longer possible; use distinct names.

Troubleshooting

Action Not Found

  • Verify repository is public or accessible
  • Check action.yml exists in repository root
  • Confirm version tag exists

Permission Denied

# Add required permissions to workflow
permissions:
  contents: write
  pull-requests: write

Node Modules Missing

  • Bundle dependencies with ncc
  • Check dist/ folder is committed
  • Verify node_modules excluded from .gitignore for dist/

Docker Action Fails

  • Check Dockerfile syntax
  • Verify entrypoint has execute permissions
  • Test container locally: docker build -t test . && docker run test

Anti-Fabrication Requirements

  • Execute Read or Glob tools to verify action files exist before claiming structure
  • Use Bash to test commands before documenting syntax
  • Validate action.yml schema against actual files using tool analysis
  • Execute actual API calls with @actions/github before documenting responses
  • Test permission configurations in real workflows before recommending settings
  • Never claim action capabilities without reading actual implementation code
  • Report actual npm audit results when discussing security, not fabricated vulnerability counts

GitHub Community Health

Activate when setting up or auditing community health files for GitHub repositories. This skill covers the files GitHub checks in its Community Standards profile, plus related repo configuration.

Community Profile Checklist

GitHub checks these 6 items on the /community tab:

  1. README — project overview, usage, and getting started
  2. LICENSE — open-source license file in repo root
  3. CODE_OF_CONDUCT.md — community behavior standards
  4. CONTRIBUTING.md — how to contribute
  5. Issue templates — structured bug/feature reporting
  6. SECURITY.md — vulnerability disclosure policy

Check current status:

# View community profile metrics via API
gh api repos/{owner}/{repo}/community/profile

GitHub Template APIs

GitHub provides APIs to fetch common templates at runtime. Always fetch rather than hardcode — templates get updated.

# List available license templates (13 licenses)
gh api licenses --jq '.[].key'

# Fetch a specific license body
gh api licenses/mit --jq '.body'

# Fetch Code of Conduct (note: API serves v2.0, not latest v3.0)
gh api codes_of_conduct/contributor_covenant --jq '.body'

# List available gitignore templates
gh api gitignore/templates

# Fetch a specific gitignore template
gh api gitignore/templates/Node --jq '.source'

LICENSE

Use the GitHub API to list and fetch license templates:

# List all available licenses
gh api licenses --jq '.[] | "\(.key): \(.name)"'

# Fetch license text (has [year] and [fullname] placeholders)
gh api licenses/mit --jq '.body'
gh api licenses/apache-2.0 --jq '.body'
gh api licenses/gpl-3.0 --jq '.body'

After fetching, replace placeholders:

  • [year] — current year (or year range)
  • [fullname] — copyright holder name

Place the file as LICENSE (no extension) in the repository root.

CODE_OF_CONDUCT.md

The GitHub API serves Contributor Covenant v2.0, but the latest version is v3.0 (available at contributor-covenant.org).

Preferred approach — fetch latest from the source:

# Fetch Contributor Covenant v3.0 (latest)
curl -sL https://www.contributor-covenant.org/version/3/0/code_of_conduct.md

Fallback — use the GitHub API (v2.0):

gh api codes_of_conduct/contributor_covenant --jq '.body'

Customize these fields:

  • Contact method — email, issue tracker, or reporting form
  • Project name — replace placeholder with actual project name
  • Scope — define where the CoC applies (repo, events, social media)

Place as CODE_OF_CONDUCT.md in the repo root or .github/ directory.

CONTRIBUTING.md

Structure the guide with these sections:

# Contributing to {project}

## Getting Started
- Fork and clone the repo
- Install dependencies
- Run the test suite

## Development Setup
- Required tools and versions
- Environment configuration
- Build commands

## How to Contribute

### Bug Reports
- Use the bug report issue template
- Include reproduction steps
- Attach logs or screenshots

### Feature Requests
- Use the feature request issue template
- Describe the use case
- Explain expected behavior

### Pull Requests
- Branch from `main`
- Follow the code style guide
- Write/update tests
- Update documentation
- Reference related issues

## Style Guide
- Language-specific conventions
- Linting and formatting tools
- Commit message format

## Code of Conduct
This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md).

Place as CONTRIBUTING.md in the repo root or .github/ directory.

Issue Templates

GitHub supports YAML-based issue forms. Place templates in .github/ISSUE_TEMPLATE/.

Configuration

.github/ISSUE_TEMPLATE/config.yml — controls the template chooser:

blank_issues_enabled: false
contact_links:
  - name: Questions & Discussions
    url: https://github.com/{owner}/{repo}/discussions
    about: Ask questions in Discussions instead of opening issues

Bug Report Template

.github/ISSUE_TEMPLATE/bug_report.yml:

name: Bug Report
description: Report a bug or unexpected behavior
title: "[Bug]: "
labels: ["bug", "triage"]
body:
  - type: markdown
    attributes:
      value: Thanks for reporting a bug!
  - type: textarea
    id: description
    attributes:
      label: Description
      description: What happened? What did you expect?
    validations:
      required: true
  - type: textarea
    id: reproduction
    attributes:
      label: Steps to Reproduce
      description: Minimal steps to reproduce the issue
      placeholder: |
        1. Run '...'
        2. See error
    validations:
      required: true
  - type: input
    id: version
    attributes:
      label: Version
      description: Which version are you using?
    validations:
      required: true
  - type: dropdown
    id: os
    attributes:
      label: Operating System
      options:
        - macOS
        - Linux
        - Windows
    validations:
      required: true
  - type: textarea
    id: logs
    attributes:
      label: Relevant Logs
      description: Paste any error output or logs
      render: shell

Feature Request Template

.github/ISSUE_TEMPLATE/feature_request.yml:

name: Feature Request
description: Suggest a new feature or improvement
title: "[Feature]: "
labels: ["enhancement"]
body:
  - type: textarea
    id: problem
    attributes:
      label: Problem
      description: What problem does this solve?
    validations:
      required: true
  - type: textarea
    id: solution
    attributes:
      label: Proposed Solution
      description: How should this work?
    validations:
      required: true
  - type: textarea
    id: alternatives
    attributes:
      label: Alternatives Considered
      description: What other approaches did you consider?
  - type: textarea
    id: context
    attributes:
      label: Additional Context
      description: Any other relevant information

Pull Request Template

.github/PULL_REQUEST_TEMPLATE.md:

## Summary
<!-- Brief description of changes -->

## Changes
-

## Testing
- [ ] Tests pass locally
- [ ] New tests added for new functionality

## Checklist
- [ ] Code follows project style guide
- [ ] Documentation updated
- [ ] No breaking changes (or documented in summary)

## Related Issues
<!-- Closes #123 -->

SECURITY.md

Define a vulnerability disclosure policy:

# Security Policy

## Supported Versions

| Version | Supported          |
| ------- | ------------------ |
| x.x.x   | :white_check_mark: |
| < x.x.x | :x:                |

## Reporting a Vulnerability

**Do not open a public issue for security vulnerabilities.**

To report a vulnerability:
1. Use [GitHub Security Advisories](https://github.com/{owner}/{repo}/security/advisories/new)
2. Or email: security@example.com

Include:
- Description of the vulnerability
- Steps to reproduce
- Potential impact
- Suggested fix (if any)

## Response Timeline

- **Acknowledgment**: within 48 hours
- **Initial assessment**: within 1 week
- **Fix timeline**: depends on severity

## Disclosure Policy

We follow coordinated disclosure. We ask reporters to:
- Allow reasonable time for a fix before public disclosure
- Avoid exploiting the vulnerability beyond what is needed to demonstrate it

Place as SECURITY.md in the repo root or .github/ directory. GitHub detects it automatically and shows a "Security policy" link on the Security tab.

.gitignore

Use the GitHub API to fetch language-specific templates:

# List all available templates
gh api gitignore/templates --jq '.[]'

# Fetch a single template
gh api gitignore/templates/Node --jq '.source'

# Combine multiple templates
{
  echo "# Node"
  gh api gitignore/templates/Node --jq '.source'
  echo ""
  echo "# macOS"
  gh api gitignore/templates/macOS --jq '.source'
} > .gitignore

Always fetch from the API rather than writing from memory — templates evolve with tooling changes.

CODEOWNERS

Define code ownership for automatic PR review assignment. Place as CODEOWNERS in the repo root, docs/, or .github/ directory.

Syntax:

# Default owners for everything
*       @org/team-leads

# Specific paths
/src/auth/       @security-team
/docs/           @docs-team
*.tf             @infra-team

# Multiple owners (all are requested)
/src/api/        @backend-team @api-reviewers

# Override for specific files
/src/api/README.md  @docs-team

Key behaviors:

  • Later rules override earlier ones for the same file
  • Owners are requested as reviewers automatically on PRs
  • Pair with branch protection's "Require review from Code Owners" for enforcement
# Enable required reviews from CODEOWNERS via branch protection
gh api repos/{owner}/{repo}/branches/main/protection -X PUT \
  -f 'required_pull_request_reviews[dismiss_stale_reviews]=true' \
  -f 'required_pull_request_reviews[require_code_owner_reviews]=true' \
  -F 'required_pull_request_reviews[required_approving_review_count]=1' \
  -F 'enforce_admins=true'

FUNDING.yml

Configure the GitHub Sponsors button. Place as .github/FUNDING.yml:

# GitHub Sponsors
github: [username]

# Other platforms
patreon: username
open_collective: project-name
ko_fi: username
custom: ["https://example.com/donate"]

Supported platforms: github, patreon, open_collective, ko_fi, tidelift, community_bridge, liberapay, issuehunt, lfx_crowdfunding, polar, buy_me_a_coffee, thanks_dev, custom.

Repo Settings via gh

Configure repository settings using the GitHub CLI:

# Set repo description and topics
gh repo edit --description "Project description here"
gh repo edit --add-topic "topic1" --add-topic "topic2"

# Configure merge settings
gh repo edit --enable-squash-merge --enable-merge-commit=false --enable-rebase-merge=false
gh repo edit --delete-branch-on-merge

# Enable features
gh repo edit --enable-discussions
gh repo edit --enable-wiki=false

# Set default branch
gh api repos/{owner}/{repo} -X PATCH -f default_branch=main

# Branch protection
gh api repos/{owner}/{repo}/branches/main/protection -X PUT \
  -f 'required_status_checks[strict]=true' \
  -f 'required_status_checks[contexts][]=ci' \
  -F 'required_pull_request_reviews[required_approving_review_count]=1' \
  -f 'required_pull_request_reviews[dismiss_stale_reviews]=true' \
  -F 'enforce_admins=false' \
  --input /dev/null

Anti-Fabrication Requirements

  • Use gh api repos/{owner}/{repo}/community/profile to check which community files exist before claiming status
  • Fetch license and CoC templates from the GitHub API rather than generating from memory
  • Use gh api repos/{owner}/{repo} to verify repo settings before reporting them
  • Read existing files with the Read tool before suggesting modifications
  • Verify .github/ISSUE_TEMPLATE/ contents with Glob before claiming template status
  • Run gh repo view to confirm repository visibility and features
  • Never fabricate template content — always fetch from API or reference actual file contents

Dependabot Consolidator

Codifies the recipe proven on kina PR #36: collect open Dependabot PRs, consolidate into one tested branch and PR, verify with baseline-diff gates, and close out on operator approval. Single-repo, operator-supervised scope.

Scope: Dependabot only

List open Dependabot PRs with:

gh pr list --author "app/dependabot" --state open \
  --json number,title,headRefName,files

Warning: never touch human-authored PRs in the same pass. The --author app/dependabot filter is the guard; verify it returns only bot-authored entries before proceeding.

Decide grouping: ecosystem and risk

Classify each PR as config-only Actions or code/package bump before creating the branch. Decision: consolidate-all vs split-actions-from-code.

  • Config-only Actions bumps (.github/workflows/*.yml only): validated authoritatively by real GitHub CI running on the pushed branch. Low risk; consolidate freely.
  • Language/package bumps (Cargo.toml, package.json, go.mod, etc.): breaking MAJORs may need local compile, test, and code changes. Higher risk; consider splitting from Actions bumps if any contain MAJOR version changes.

See references/group-by-risk.md for the full ecosystem × risk taxonomy.

Consolidation procedure

Create branch and cherry-pick each Dependabot PR head in order:

git fetch origin
git checkout -b chore/consolidate-dependabot origin/main

For each PR (ordered low-risk first, MAJOR bumps last):

git cherry-pick <pr-head-sha>

Conflict rule — keep every bump: Dependabot PRs each target a distinct dependency. When cherry-pick conflicts arise, keep both sides (each bump targets a different line/package). Do not drop either side.

Pin-style preservation: Dependabot updates pins in two styles — @v4 major tag and full commit SHA with a # vX.Y.Z trailing comment. Read the file before cherry-picking to know which style applies; preserve that style after merge.

Lockfile handling: Before assuming a lockfile needs a manual update, run git check-ignore <lockfile>. If the lockfile is tracked, commit the updated version. For Cargo: cargo update -p <dep> for the specific crate only — do not run a global cargo update.

See references/consolidation-algorithm.md for full cherry-pick mechanics and edge cases.

Verify with baseline-diff gates

THE key insight: run each gate on the merge-base (main) FIRST, then on the branch. Only a NEW failure — one that does not appear on main — is a regression worth blocking on.

Gate discipline:

  1. Identify the gates: cargo test, npm test, lint, type-check, build, integration scripts.
  2. Run each gate on main / merge-base. Capture output. Record pass/fail per gate.
  3. Checkout the consolidated branch. Run the same gates. Capture output.
  4. Diff: classify only gates that were PASSING on main and are now FAILING on branch as blocking.
  5. Gates that fail identically on both sides are pre-existing failures — not regressions.

Local integration gates: some gates cannot run in GitHub CI (Apple Container cluster spawn, hardware-dependent tests). Run these on the operator machine under the same baseline-diff discipline. See references/local-integration-gates.md and /core:container for container-spawn patterns.

See references/baseline-diff-verification.md for worked kina examples and the full gate enumeration workflow.

Use /github:act to replay GitHub CI gates locally before pushing. See /github:workflows for workflow file interpretation.

Merge and close out

Gate before merging:

  1. Green on local gates (baseline-diff verified)
  2. Green on remote CI (gh pr checks — all checks passing)
  3. Explicit operator go-ahead

After operator approval:

gh pr merge <consolidated-pr-number> --squash --match-head-commit <headRefOid>

Fetch <headRefOid> with gh pr view <consolidated-pr-number> --json headRefOid -q .headRefOid immediately before merging — a bare gh pr merge --squash with no --match-head-commit is blocked by the claude-skills-340 merge-write gate and can silently merge a commit that landed after review. No attribution in the squash commit message.

For each superseded Dependabot PR, comment then verify closure:

gh pr comment <n> -b "Addressed by #<consolidated> (consolidated dependency update)"
gh pr view <n> --json state

Verify the state field is MERGED or CLOSED. Do not assume Dependabot auto-closes — confirm with gh pr view for each one.

See references/merge-and-closeout.md for the full close-out checklist.

Delegation

Hand mechanical cherry-picking to agents/dependabot-consolidator-worker.md. Read-only PR collection goes to agents/dependabot-collector.md.

Stop-and-report gates (worker must halt, not thrash):

  • Conflict that cannot be resolved with keep-both (same line, competing values) → STOP, report the conflicting PRs and the specific file/line
  • Non-trivial dependency API break requiring code changes → STOP, report the bump and the compilation error
  • A baseline-diff gate that was green on main but fails on branch → STOP, report the gate name and diff of outputs

Hard constraint: agents never merge unilaterally. Merge is operator-approved and executed by the skill's close-out step.

Registration

See references/registration.md for the build checklist covering marketplace.json, plugin.json, sources.toml, and sources.md edits, plus the two validators to run before committing.

Related skills

  • /core:anti-fabrication — never claim a gate passed without showing command output
  • /core:container — local integration gates using Apple Container
  • /github:act — replay CI gates locally before push
  • /github:workflows — read and interpret workflow files
  • /github:actions — understand action versions and pin styles

Anti-Fabrication

  • Never claim a gate passed without showing the command and its output verbatim.
  • Always run the baseline gate on main before blaming a bump for a failure.
  • Confirm PR closure with gh pr view <n> --json state — do not assert "Dependabot closed it."
  • Verify pin style by reading the file with the Read tool before asserting @v4 vs full-SHA style.
  • When reporting cherry-pick conflicts, show the exact git status output, not a paraphrase.

See /core:anti-fabrication for the full discipline.

PR Review

Reviews open, human-authored pull requests with the care of the Forge operating model (/core:agent-loop): a read-only collector classifies the queue, one stack-aware reviewer runs per PR, each branch is built and tested locally under baseline-diff discipline, and the operator owns every merge. Repo-agnostic — stack and gates are discovered, never hardcoded.

Scope: human-authored PRs only

List open PRs and exclude bots:

gh pr list --state open \
  --json number,title,author,headRefName,headRefOid,files

Drop every PR whose author.is_bot is true or whose login is app/dependabot. Bot dependency PRs belong to /github:dependabot-consolidator, not this skill. Verify the filtered list contains only human authors before dispatching reviewers.

Classify each PR: stack and gates

Classify before reviewing. Two inputs drive the classification:

  1. Stack — read the PR's changed file extensions and the repo's manifests (Cargo.toml, mix.exs, build.zig, package.json, go.mod). Map to the reviewer's language skills. See references/stack-detection.md for the full table.
  2. Gates — discover the repo's own gate tasks with /core:mise: run mise tasks and pick the PR-gating tasks (ci, pre-commit, test, lint, fmt:check, audit, gitleaks). Run the discovered tasks — never assume cargo/mix/npm directly.

Hand this read-only classification to the pr-collector agent.

Per-PR review: one agent per PR

Dispatch one pr-gate-runner then one pr-review-worker per PR, sequentially. Fan-out width equals the open-PR count, the Forge slice model. Run each PR's pair sequentially when the gates need exclusive hardware (integration tests, container or cluster spawns). The gate-runner clones the repo into its own scratchpad — no working-tree check is needed before dispatch, and no worker touches the shared working tree (see agents/pr-gate-runner.md). The collector's headRefOid and main oid go to pr-gate-runner, whose Artifacts block goes to pr-review-worker. Pass the gate-runner's Artifacts block (diff path plus both source snapshot paths) to the pr-review-worker — its only route to the diff and source, since it carries no Bash tool.

Every gate-runner loads, at minimum:

/core:git
/core:mise
/core:security
/core:anti-fabrication
/core:agent-loop

Every reviewer loads, at minimum:

/core:git
/core:security
/core:anti-fabrication
/core:restraint
/core:agent-loop

plus the stack-specific skills from the classification (for example /rust:rust, /rust:testing, /rust:error-handling for Rust; /core:documentation for docs; /github:workflows, /github:actions for Actions changes).

Verify with baseline-diff gates

THE key insight: run each gate on main FIRST, then on the PR branch. Only a gate that was PASSING on main and is now FAILING on the branch is a regression worth blocking on. The pr-gate-runner runs this discipline in its own scratchpad clones — see references/baseline-diff-verification.md for the full procedure, including local-only integration gates and the worked kina example. Use /github:act to replay hosted CI gates locally when useful.

Review the diff

The pr-review-worker reads the gate-runner's diff and source-snapshot artifacts (never git itself — it carries no Bash tool) against references/review-rubric.md — correctness, security, test coverage, no leaked secrets, and match to the PR's stated intent — and judges the gate-runner's evidence per /core:agent-loop references/reviewer.md. It emits a structured verdict: approve, request-changes with file:line findings and cited gate evidence, or wait with an evidenceRequests list when needed evidence is missing. On wait, the orchestrator dispatches the pr-gate-runner (or targeted execution hands) for the named requests and re-invokes the reviewer once with the results. The orchestrator keeps both scratchpad clones and the diff file until the verdict lands, then discards them. The reviewer never runs gates, never edits code, and never merges.

Merge and close out

Gate before merging:

  1. Green on local gates (baseline-diff verified)
  2. Green on remote CI (gh pr checks — all checks passing)
  3. Explicit operator go-ahead, per PR

After operator approval:

gh pr merge <n> --squash --match-head-commit <headRefOid>

Pin to the headRefOid collected above — a merge without --match-head-commit is blocked by the claude-skills-340 merge-write gate and is unsafe in any case, since it can silently merge a commit that arrived after review. No attribution in the squash commit message. Confirm closure:

gh pr view <n> --json state

Verify state is MERGED. A request-changes PR gets a review comment instead and stays open. See references/merge-and-closeout.md.

Delegation

  • Read-only PR collection and classification → agents/pr-collector.md.
  • Per-PR baseline-diff gate execution → agents/pr-gate-runner.md.
  • Per-PR diff review and verdict → agents/pr-review-worker.md.

Stop-and-report gates (workers halt, do not thrash):

  • A gate green on main but failing on the branch, or an ambiguous gate result → the gate-runner STOPS and reports the gate name and output diff.
  • A diff that needs code changes to pass, or an ambiguous or contradictory PR intent → the reviewer STOPS and reports request-changes or what is unclear.

Hard constraint: agents never merge unilaterally. Merge is operator-approved and executed by this skill's close-out step.

Registration

See references/registration.md for the marketplace.json, plugin.json, sources.toml, and sources.md edits, plus the two validators to run before committing.

Related skills

  • /core:agent-loop — the Forge operating model this skill mirrors (collector hands, per-slice principals, operator-owned merge)
  • /core:anti-fabrication — never claim a gate passed without showing command output
  • /core:mise — discover the repo's gate tasks instead of assuming a toolchain
  • /core:container — local integration gates using Apple Container
  • /github:act — replay hosted CI gates locally before merge
  • /github:dependabot-consolidator — the bot-PR counterpart this skill defers to

Anti-Fabrication

  • Never claim a gate passed without showing the command and its verbatim output.
  • Always run the baseline gate on main before blaming a PR for a failure.
  • Confirm PR closure with gh pr view <n> --json state — do not assert "it merged."
  • Classify stack from the changed files and manifests, not the PR title alone.
  • When reporting a blocking gate, show the diff of main-vs-branch output, not a paraphrase.

See /core:anti-fabrication for the full discipline.

GitHub Workflows

Activate when creating, modifying, debugging, or optimizing GitHub Actions workflow files. This skill covers workflow structure, best practices, and common CI/CD patterns; full YAML syntax detail lives in references/.

Workflow File Structure

File anatomy (name:, on:, env:, jobs:) and the .github/workflows/ location requirement: see references/workflow-syntax.md.

Trigger Events (on:)

Push/PR branch, tag, and path filters, cron schedules, workflow_dispatch inputs, and multi-event triggers: see references/workflow-syntax.md.

Jobs

Runner selection, matrix strategy, needs: dependencies, and conditional job execution: see references/jobs-and-steps.md.

Steps

Using actions, run: commands, conditional steps, and continue-on-error: see references/jobs-and-steps.md.

Environment Variables and Secrets

Global/job/step-level env, secrets.* usage, and inter-step outputs: see references/jobs-and-steps.md.

Gotcha: pass values between steps with echo "key=value" >> $GITHUB_OUTPUT — the deprecated set-output command no longer works.

Contexts

github, env, job, steps, runner, and matrix context fields: see references/contexts-and-expressions.md.

Expressions

Operators, status functions (success(), failure(), always()), and string/JSON/hash functions: see references/contexts-and-expressions.md.

Gotcha: quote expression negations — if: "!cancelled()" — because a bare leading ! is a YAML tag and breaks parsing.

Artifacts

upload-artifact / download-artifact usage, retention, and cross-job handoff: see references/workflow-syntax.md.

Caching

setup-node built-in caching and manual actions/cache key construction: see references/workflow-syntax.md.

Permissions

Workflow- and job-level GITHUB_TOKEN permission scopes: see references/workflow-syntax.md.

Grant least privilege: declare an explicit permissions: block (e.g. contents: read) rather than inheriting the default token scope.

Concurrency

Workflow- and job-level concurrency groups and cancel-in-progress: see references/workflow-syntax.md.

Reusable Workflows

workflow_call inputs/outputs/secrets and calling syntax: see references/workflow-syntax.md.

Common CI/CD Patterns

Complete Docker build-and-push and deploy-on-release workflow artifacts: see references/workflow-syntax.md. The two patterns below stay here because agents adapt them in-conversation.

Node.js CI

name: Node.js CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [22, 24]

    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'
      - run: npm ci
      - run: npm run lint
      - run: npm test
      - run: npm run build

Monorepo with Path Filtering

name: Monorepo CI

on:
  pull_request:
    paths:
      - 'packages/**'

jobs:
  detect-changes:
    runs-on: ubuntu-latest
    outputs:
      frontend: ${{ steps.filter.outputs.frontend }}
      backend: ${{ steps.filter.outputs.backend }}
    steps:
      - uses: actions/checkout@v7
      - uses: dorny/paths-filter@v4
        id: filter
        with:
          filters: |
            frontend:
              - 'packages/frontend/**'
            backend:
              - 'packages/backend/**'

  test-frontend:
    needs: detect-changes
    if: needs.detect-changes.outputs.frontend == 'true'
    runs-on: ubuntu-latest
    steps:
      - run: npm test --workspace=frontend

  test-backend:
    needs: detect-changes
    if: needs.detect-changes.outputs.backend == 'true'
    runs-on: ubuntu-latest
    steps:
      - run: npm test --workspace=backend

Debugging Workflows

Replay a workflow locally with act before pushing — see /github:act for local run configuration and troubleshooting.

Enable Debug Logging

Set repository secrets:

  • ACTIONS_RUNNER_DEBUG: true
  • ACTIONS_STEP_DEBUG: true

Debug Steps

steps:
  - name: Debug context
    run: |
      echo "Event: ${{ github.event_name }}"
      echo "Ref: ${{ github.ref }}"
      echo "SHA: ${{ github.sha }}"
      echo "Actor: ${{ github.actor }}"

  - name: Dump GitHub context
    run: echo '${{ toJSON(github) }}'

  - name: Dump runner context
    run: echo '${{ toJSON(runner) }}'

Tmate Debugging

steps:
  - name: Setup tmate session
    if: failure()
    uses: mxschmitt/action-tmate@v3
    timeout-minutes: 30

Performance Optimization

Dependency caching, shallow/sparse checkout, and parallel job graphs: see references/workflow-syntax.md.

Anti-Fabrication Requirements

  • Execute Read tool to verify workflow files exist before claiming structure
  • Use Bash with gh workflow list to confirm actual workflow names before referencing them
  • Execute gh workflow view <workflow> to verify trigger configuration before documenting it
  • Use Glob to find actual workflow files before claiming their presence
  • Execute gh run list to verify actual workflow runs before discussing execution patterns
  • Never claim workflow success rates without actual run history analysis
  • Validate YAML syntax using yamllint or similar tools via Bash before claiming correctness
  • Report actual permission errors from workflow runs, not fabricated authorization issues
  • Execute actual cache operations before claiming cache hit/miss percentages
  • Use Read tool on action.yml files to verify action inputs/outputs before documenting usage

References

  • references/workflow-syntax.md — file structure, triggers, artifacts, caching, permissions, concurrency, reusable workflows, performance optimization, complete Docker/deploy examples
  • references/jobs-and-steps.md — job configuration, runners, matrix strategy, dependencies, step mechanics, environment variables and secrets
  • references/contexts-and-expressions.md — context objects, operators, and built-in expression functions

Agents 5

You are the dependabot-collector. Your role is to list and classify all open Dependabot PRs in a repository and emit a structured report. You make no git mutations.

Load skills

Invoke each with the Skill tool and quote one sentence from each as proof:

  • /core:anti-fabrication
  • /core:restraint

Workflow

  1. List open Dependabot PRs:

    gh pr list --author "app/dependabot" --state open \
      --json number,title,headRefName,headRefOid,files
    

    Confirm output contains only app/dependabot-authored entries.

  2. Classify each PR by reading its changed files:

    • All paths under .github/workflows/ → config-only Actions
    • Paths include a language manifest → code/package bump
    • Note version change from PR title: extract old and new semver, flag MAJOR bumps (new_major > old_major)
  3. Emit structured report with one row per PR:

    PR #<n>: <title>
      headRefOid: <sha>
      ecosystem: actions | cargo | npm | go | python | other
      risk: low | medium | high
      major_bump: yes | no
      files: <comma-separated list>
    

Constraints

  • Do not run git commands that mutate the working tree.
  • Do not call gh pr merge, gh pr close, or any write operation.
  • Do not cherry-pick, checkout, or create branches.
  • If gh is not authenticated or returns an error, report the error verbatim and stop.

Anti-fabrication

  • Show the raw gh pr list output before the classified report so the caller can verify.
  • Do not infer ecosystem from PR title alone; read the files field.
  • Do not guess whether a version change is major — parse the semver numerically.

You are the dependabot-consolidator-worker. Your role is to create the consolidated branch, cherry-pick each Dependabot PR in order, resolve conflicts with keep-both logic, run baseline-diff gates, push, and draft the PR body. You never merge.

Load skills

Invoke each with the Skill tool and quote one sentence from each as proof:

  • /core:anti-fabrication
  • /core:restraint

Inputs expected from the caller

  • Ordered list of PR head SHAs (from the collector report)
  • Classification: ecosystem and risk per PR
  • Main branch name (default: main)

Execution order

1. Capture baseline gates on main

git checkout main && git pull origin main
cargo test 2>&1 | tee /tmp/gate-main-tests.txt
cargo clippy 2>&1 | tee /tmp/gate-main-clippy.txt

Adapt gate commands to the repo's language (npm, go, etc.). Record PASS/FAIL for each.

2. Create branch and cherry-pick

git fetch origin
git checkout -b chore/consolidate-dependabot origin/main

For each SHA in order (low-risk first):

git cherry-pick <sha>

On conflict:

  • Inspect git status and the conflicted file.
  • If conflict is keep-both resolvable (different lines): apply both bumps, git add <file>, git cherry-pick --continue.
  • If conflict requires choosing between two versions of the SAME dependency: STOP. Report the two SHAs, the file, and the conflicting values. Do not guess.
  • If a bump causes a compile error requiring code changes: STOP. Report the SHA, the error output verbatim, and the dependency that caused it.

3. Handle lockfiles

After all cherry-picks complete:

  • Run git check-ignore Cargo.lock (or equivalent). If tracked, update: cargo update -p <crate> per bumped crate.
  • Commit lockfile changes: git commit -m "chore: update Cargo.lock for consolidated dependabot bumps"

4. Run baseline-diff gates on branch

cargo test 2>&1 | tee /tmp/gate-branch-tests.txt
cargo clippy 2>&1 | tee /tmp/gate-branch-clippy.txt
diff /tmp/gate-main-tests.txt /tmp/gate-branch-tests.txt

Classify each gate:

  • Was PASS on main, is FAIL on branch → STOP. Report gate name and diff output.
  • Was FAIL on main, is FAIL on branch → pre-existing; continue.
  • Was PASS on main, is PASS on branch → not a regression; continue.

5. Push and draft PR

git push -u origin chore/consolidate-dependabot
gh pr create --draft --title "chore(deps): consolidated dependabot updates" \
  --body "$(cat <<'EOF'
## Supersedes

<list each superseded PR with number and title>

## Baseline-diff verification

<paste gate comparison table>
EOF
)"

Do NOT hardcode a Closes #N / Closes <tracker>-N line in the body. Add a closing reference ONLY if the CALLER gave you an issue in THIS repo to close — never carry a tracker ID from another repo (e.g. a claude-skills-NN bee) into the target repo's PR.

Hard constraints

  • Never run gh pr merge or gh pr close.
  • Never modify test files.
  • Never run a global cargo update or npm update — only update specific packages bumped by Dependabot.
  • Stop and report on any conflict or gate failure that is not pre-existing. Do not thrash.

Report format

CONSOLIDATION WORKER REPORT
- Branch: chore/consolidate-dependabot
- PRs cherry-picked: <list of numbers>
- Conflicts resolved (keep-both): <list or "none">
- Stop conditions hit: <list or "none">
- Baseline gates (main vs branch):
  <table>
- PR URL: <url or "not created — stop condition hit">

You are the pr-collector. Your role is to list and classify a repository's open, human-authored pull requests and discover the repo's gate tasks, then emit a structured report. You make no git mutations.

Load skills

Invoke each with the Skill tool and quote one sentence from each as proof:

  • /core:mise
  • /core:anti-fabrication
  • /core:restraint

Workflow

  1. Working-tree guard: run git status --short and report it verbatim. The caller needs to know whether the tree is clean before later branch checkouts.

  2. List open PRs:

    gh pr list --state open \
      --json number,title,author,headRefName,headRefOid,files,additions,deletions,changedFiles
    

    Drop every entry where author.is_bot is true or login is app/dependabot. Confirm the kept list contains only human authors. Bot PRs are out of scope.

  3. Classify each PR by stack from its changed file paths and the repo's manifests. Read the file list (gh pr view <n> --json files) — do not infer stack from the title:

    • .rs or Cargo.toml → rust
    • .ex / .exs or mix.exs → elixir
    • .zig or build.zig → zig
    • .ts / .js or package.json → js
    • .md or docs/ only → documentation
    • .github/workflows/ or action/digest pins → gh-actions/security See ../references/stack-detection.md for the full skill-set mapping.
  4. Get the main branch oid (once per repo, not per PR) — the gate-runner needs it as the baseline commit:

    gh api repos/<owner>/<repo>/branches/<main> --jq .commit.sha
    
  5. Discover gate tasks with /core:mise: run mise tasks and report the PR-gating tasks that exist (ci, pre-commit, test, lint, fmt:check, audit, gitleaks). Paste the verbatim relevant lines.

  6. Emit structured report, one block per PR:

    PR #<n>: <title>
      author: <login>
      headRefName: <branch>
      headRefOid: <40-hex-sha>
      mainOid: <40-hex-sha>
      stack: rust | elixir | zig | js | documentation | gh-actions/security
      reviewer skills: /core:git, /core:mise, /core:security, /core:anti-fabrication, <stack skills>
      size: +<additions>/-<deletions>, <changedFiles> files
      risk: low | medium | high — <one-line reason>
    

    Then a Gate tasks section and the git status --short output.

Constraints

  • Do not run git commands that mutate the working tree (no checkout, no branch, no commit).
  • Do not call gh pr merge, gh pr close, or any write operation.
  • If gh is not authenticated or returns an error, report the error verbatim and stop.

Anti-fabrication

  • Show the raw gh pr list output before the classified report so the caller can verify.
  • Read the files field to classify stack; never guess from the title alone.
  • Report mise tasks output verbatim; do not invent task names.

You are the pr-gate-runner. Your role is execution hands for a PR review: run the repo's gate tasks on main and on the PR's head commit, each in its own scratchpad clone, and report the baseline-diff classification with one execution evidence record per gate. You never read the diff for correctness, never edit code, never commit, never push, never merge.

Load skills

Invoke each with the Skill tool and quote one sentence from each as proof. Always:

  • /core:git
  • /core:mise
  • /core:security
  • /core:anti-fabrication
  • /core:agent-loop

Inputs expected from the caller

  • Repo URL
  • Main branch commit oid
  • PR headRefOid
  • PR number (to fetch pull/<pr-number>/head)
  • Gate task list (from the collector's mise tasks discovery)

Execution order

Follow this skill's references/baseline-diff-verification.md "Procedure" exactly — it owns the clone, run, and classification steps. Never check out the shared working tree.

Output

  • The baseline-diff table (gate, main, branch, verdict) per references/baseline-diff-verification.md.
  • One Execution evidence record per /extras-claude-code:claude-output-styles assets/ci-evidence-format.md "Execution evidence" for every gate run, on both sides — REVISION is the main oid for the baseline runs and headRefOid for the branch runs.
  • Artifacts — produced per references/baseline-diff-verification.md:
    • DIFF: <path> (<main-oid>...<headRefOid>)
    • SOURCE main: <path> @ <main-oid>
    • SOURCE branch: <path> @ <headRefOid>

Hard constraints

  • Never run gh pr merge, gh pr close, gh pr comment, git commit, or git push.
  • Never check out or write to the shared working tree — scratchpad clones only.
  • Never edit code or test files.
  • Never judge the diff, propose a verdict, or comment on correctness — that is the reviewer's job, not yours. Report evidence only.

You are the pr-review-worker. Your role is to review ONE pull request's diff against the rubric, judging the gate evidence a pr-gate-runner already collected, and emit a structured verdict. You never run gates, never edit code, never commit, never merge.

Load skills

Invoke each with the Skill tool and quote one sentence from each as proof. Always:

  • /core:git
  • /core:security
  • /core:anti-fabrication
  • /core:restraint
  • /core:agent-loop

Plus the stack-specific skills named in your dispatch (for example /rust:rust, /rust:testing, /rust:error-handling; /core:documentation; /github:workflows, /github:actions). See ../references/stack-detection.md.

Inputs expected from the caller

  • PR number, headRefName, headRefOid
  • Stack and the reviewer skill list
  • The pr-gate-runner report (baseline-diff table + execution evidence records) for headRefOid, including its Artifacts block (DIFF, SOURCE main, SOURCE branch)
  • Main branch name (default: main)

Execution order

Review the diff

You have no Bash tool and never run git yourself. Read the gate-runner's DIFF artifact and the SOURCE main / SOURCE branch snapshot paths with Read/Grep against ../references/review-rubric.md: correctness, security, test coverage, no leaked secrets, match to the PR's stated intent. Never read the shared working tree for the PR's content — only the artifact paths the gate-runner reported. Before judging, confirm each artifact's stated oid: the SOURCE branch path and the DIFF range's right side must equal headRefOid; the SOURCE main path and the DIFF range's left side must equal the main oid. Confirm each source snapshot by reading its .git/HEAD file and comparing it with the stated oid; for the diff, rely on the gate-runner's DIFF line oids. A missing or mismatched artifact means return verdict wait naming the artifact, per /core:agent-loop references/reviewer.md — never proceed on an unverified artifact. Verify claims against the real source with Read/Grep — do not assume. For Actions/digest PRs, confirm pins are full commit SHAs and digests are correct. Judge the pr-gate-runner's evidence per /core:agent-loop references/reviewer.md — read only RESULT and EXCERPT from each record, opening LOG only when a finding needs more than EXCERPT carries. Apply the rubric's optional comment-quality dimension inline yourself (you have no Task tool, so you never spawn a dedicated reviewer for it) — dispatching a separate comment-reviewer agent, if the orchestrator chooses to, is the orchestrator's job. When evidence you need is missing from the gate-runner report, return verdict wait with an evidenceRequests list per /core:agent-loop references/reviewer.md — never guess or re-run gates yourself.

Hard constraints

  • Never run gh pr merge, gh pr close, git commit, git push, or any gate task.
  • Never edit code or test files. You review; you do not fix.
  • Stop and report request-changes on a runner-reported regression or a diff that needs code changes to pass. Do not thrash.

Report format

PR #<n> REVIEW
- Verdict: approve | request-changes | wait
- Gate evidence: <cite the pr-gate-runner's execution evidence records; each REVISION must
  equal headRefOid for the branch-side records>
- Diff review findings: one line each per `/extras-claude-code:claude-output-styles`
  `assets/review-findings-format.md`, or "No findings."
- Evidence requests: <evidenceRequests list per /core:agent-loop references/reviewer.md —
  present only on wait>
- Notes: <anything the operator needs to know before merge>

Sponsors

Details

Marketplace
vinnie357/claude-skills
Source
plugins/tools/github
Category
Tools
Keywords
github, actions, workflows, ci-cd, act, testing, community-health, open-source, dependabot, dependencies, pr-review, code-review, collaborator

More from vinnie357/claude-skills

All 33