GitHub Skills

A production-oriented skill for AI agents that design, audit, secure, automate, troubleshoot, and maintain professional GitHub repositories.

github-skills turns repository work into structured, implementation-ready deliverables: repository blueprints, community health files, issue forms, pull request workflows, ruleset plans, GitHub Actions, release systems, security controls, CLI/API plans, and evidence-based audits.

This project is independent and is not affiliated with or endorsed by GitHub.

What It Does

The skill can guide an AI agent through:

  • repository architecture and boundary design,
  • public, private, internal, template, monorepo, library, CLI, infrastructure, and documentation repositories,
  • README and documentation architecture,
  • contribution and community health files,
  • issue forms, labels, triage, milestones, Discussions, and Projects,
  • branch strategy, pull requests, CODEOWNERS, rulesets, and merge policy,
  • GitHub Actions design, reusable workflows, matrices, artifacts, caching, concurrency, and environments,
  • Actions security, least-privilege permissions, action pinning, OIDC, fork safety, and runner trust,
  • Dependabot, secret scanning, push protection, code scanning, and vulnerability reporting,
  • releases, tags, changelogs, packages, provenance, checksums, and rollback,
  • GitHub CLI, REST API, GraphQL, webhooks, and GitHub Apps,
  • repository audits, remediation plans, and troubleshooting.

Deliverables

Depending on the request, an agent using this skill can produce:

  • a Markdown repository architecture specification,
  • a machine-readable repository blueprint JSON,
  • an exact repository directory tree,
  • complete .github files,
  • issue forms and pull request templates,
  • CODEOWNERS and governance plans,
  • GitHub Actions workflow YAML,
  • repository and organization settings plans,
  • ruleset and branch-protection specifications,
  • security audit findings with severity and verification,
  • release and package publication workflows,
  • safe gh CLI or API execution plans,
  • migration and remediation runbooks.

Repository Layout

github-skills/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── references/
│   ├── repository-architecture.md
│   ├── community-health-and-governance.md
│   ├── issues-projects-and-triage.md
│   ├── pull-requests-branches-and-rulesets.md
│   ├── github-actions-design.md
│   ├── github-actions-security.md
│   ├── releases-versioning-and-packages.md
│   ├── repository-security.md
│   ├── github-cli-api-and-automation.md
│   ├── audit-and-troubleshooting.md
│   ├── output-templates.md
│   └── source-notes.md
├── scripts/
│   ├── validate_repository_blueprint.py
│   ├── validate_actions_workflow.py
│   └── audit_repository_package.py
└── assets/
    ├── repository-blueprint.schema.json
    ├── ruleset-blueprint.json
    ├── github-labels.json
    └── repository-starter/

The repository root also includes examples, tests, release documentation, CI, and a packaged dist/skill.zip.

Install

Download dist/skill.zip from the repository or a GitHub Release, then upload it through the custom skill installation flow of a skills-capable AI platform.

The archive contains a single skill directory named github-skills.

Example Requests

Design a secure public GitHub repository for a Rust CLI. Include the file tree,
issue forms, PR template, CODEOWNERS, default-branch ruleset, CI, release workflow,
and repository blueprint JSON.

Audit this repository and separate confirmed file findings from hosted settings
that cannot be observed. Rank risks and produce a remediation sequence.

Review this GitHub Actions workflow for excessive permissions, unsafe fork behavior,
script injection, mutable actions, release idempotency, and environment security.
Return a corrected workflow.

More prompts are available in examples/prompts.md.

Blueprint JSON

The skill defines a machine-readable repository blueprint contract. Validate a generated blueprint with:

python github-skills/scripts/validate_repository_blueprint.py examples/sample-repository-blueprint.json

The JSON Schema is available at:

github-skills/assets/repository-blueprint.schema.json

Validate an Actions Workflow

python github-skills/scripts/validate_actions_workflow.py path/to/workflow.yml

Use --strict to treat warnings as failures or --json for machine-readable output.

Audit a Local Repository Package

python github-skills/scripts/audit_repository_package.py /path/to/repository

The audit checks community health files, GitHub Actions structure, possible committed credentials, large files, unresolved placeholders, and common governance gaps. It cannot observe hosted GitHub settings unless an agent also has authenticated GitHub access.

Development

Requirements:

  • Python 3.10+
  • PyYAML

Install development dependencies:

python -m pip install -r requirements-dev.txt

Run all checks:

python -m unittest discover -s tests -v
python tools/validate_skill.py github-skills
python tools/package_skill.py github-skills dist

Design Principles

  • Separate repository files from hosted GitHub settings.
  • Inspect before changing existing repositories.
  • Require explicit authorization for destructive or externally visible actions.
  • Prefer pull requests over direct default-branch changes.
  • Use least-privilege Actions permissions.
  • Treat contributor-controlled content as untrusted input.
  • Never generate real credentials or unverifiable badges.
  • Make releases idempotent and traceable.
  • Keep machine-readable plans explicit enough for another agent to execute.

Sources

The skill prioritizes current official GitHub documentation and the GitHub CLI manual. The source map and freshness rules are in github-skills/references/source-notes.md.

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md. Do not open public issues for vulnerability details.

License

MIT License. See LICENSE.