
github
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@vinnie357Run it inside Claude Code after adding the marketplace with /plugin marketplace add vinnie357/claude-skills.
Contents
Discovered from sourceSkills 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:
- Determines which actions and jobs to execute
- Pulls or builds required Docker images
- Creates containers matching GitHub's runner environment
- Executes steps in isolated containers
- 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 --versionbefore documenting version numbers - Use
act -lto verify actual workflows before claiming their presence - Execute
docker psto confirm Docker is running before troubleshooting - Run
act -nto validate workflow syntax before claiming correctness - Execute actual
actcommands to verify behavior before documenting output format - Use
docker imagesto verify available images before recommending specific versions - Never claim success rates or performance metrics without actual measurement
- Execute
act -vto 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,.actrcconfiguration, 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/corefor inputs/outputs - Use
@actions/githubfor 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
- Create release with semantic version tag:
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0
- Create GitHub Release from tag
- Check "Publish this Action to GitHub Marketplace"
- Select primary category
- 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:
- README — project overview, usage, and getting started
- LICENSE — open-source license file in repo root
- CODE_OF_CONDUCT.md — community behavior standards
- CONTRIBUTING.md — how to contribute
- Issue templates — structured bug/feature reporting
- 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/profileto 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 viewto 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/*.ymlonly): 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:
- Identify the gates:
cargo test,npm test, lint, type-check, build, integration scripts. - Run each gate on
main/ merge-base. Capture output. Record pass/fail per gate. - Checkout the consolidated branch. Run the same gates. Capture output.
- Diff: classify only gates that were PASSING on main and are now FAILING on branch as blocking.
- 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:
- Green on local gates (baseline-diff verified)
- Green on remote CI (
gh pr checks— all checks passing) - 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
mainbefore 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
@v4vs full-SHA style. - When reporting cherry-pick conflicts, show the exact
git statusoutput, 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:
- 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. Seereferences/stack-detection.mdfor the full table. - Gates — discover the repo's own gate tasks with
/core:mise: runmise tasksand pick the PR-gating tasks (ci,pre-commit,test,lint,fmt:check,audit,gitleaks). Run the discovered tasks — never assumecargo/mix/npmdirectly.
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:
- Green on local gates (baseline-diff verified)
- Green on remote CI (
gh pr checks— all checks passing) - 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
mainbut 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-changesor 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
mainbefore 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
diffof 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: trueACTIONS_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 listto 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 listto 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 examplesreferences/jobs-and-steps.md— job configuration, runners, matrix strategy, dependencies, step mechanics, environment variables and secretsreferences/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
-
List open Dependabot PRs:
gh pr list --author "app/dependabot" --state open \ --json number,title,headRefName,headRefOid,filesConfirm output contains only
app/dependabot-authored entries. -
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)
- All paths under
-
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
gitcommands 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
ghis not authenticated or returns an error, report the error verbatim and stop.
Anti-fabrication
- Show the raw
gh pr listoutput before the classified report so the caller can verify. - Do not infer ecosystem from PR title alone; read the
filesfield. - 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 statusand 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 mergeorgh pr close. - Never modify test files.
- Never run a global
cargo updateornpm 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
-
Working-tree guard: run
git status --shortand report it verbatim. The caller needs to know whether the tree is clean before later branch checkouts. -
List open PRs:
gh pr list --state open \ --json number,title,author,headRefName,headRefOid,files,additions,deletions,changedFilesDrop every entry where
author.is_botis true or login isapp/dependabot. Confirm the kept list contains only human authors. Bot PRs are out of scope. -
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:.rsorCargo.toml→ rust.ex/.exsormix.exs→ elixir.zigorbuild.zig→ zig.ts/.jsorpackage.json→ js.mdordocs/only → documentation.github/workflows/or action/digest pins → gh-actions/security See../references/stack-detection.mdfor the full skill-set mapping.
-
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 -
Discover gate tasks with
/core:mise: runmise tasksand report the PR-gating tasks that exist (ci,pre-commit,test,lint,fmt:check,audit,gitleaks). Paste the verbatim relevant lines. -
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 taskssection and thegit status --shortoutput.
Constraints
- Do not run
gitcommands 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
ghis not authenticated or returns an error, report the error verbatim and stop.
Anti-fabrication
- Show the raw
gh pr listoutput before the classified report so the caller can verify. - Read the
filesfield to classify stack; never guess from the title alone. - Report
mise tasksoutput 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 tasksdiscovery)
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-stylesassets/ci-evidence-format.md"Execution evidence" for every gate run, on both sides —REVISIONis the main oid for the baseline runs andheadRefOidfor 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, orgit 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-changeson 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