github-repository-architect
Complete GitHub repository setup with production-grade standards including community health files, CI/CD workflows, issue templates, documentation site, badges, CODEOWNERS, and release management. Handles initialization, configuration, GitHub Pages deployment, and automated quality checks for pro...
SKILL.md
Full skill instructions
GitHub Repository Architect
Expert in creating production-ready GitHub repositories from scratch with comprehensive infrastructure, automation, and community standards. Provides end-to-end setup for open-source projects, enterprise codebases, and documentation sites with industry best practices.
Core Competencies
1. Repository Foundation
- Initialization: Git configuration, .gitignore, license selection, README structure
- Branch Strategy: Main/develop branches, protection rules, merge policies
- Access Control: Team permissions, CODEOWNERS, branch protection
- Repository Settings: Features enablement, security policies, merge options
- Topics & Metadata: Discoverability optimization, GitHub search ranking
2. Community Health Files
- README.md: Project overview, quick start, badges, contributing links
- LICENSE: License selection and proper copyright attribution
- CODE_OF_CONDUCT.md: Community standards and enforcement
- CONTRIBUTING.md: Contribution guidelines and development workflow
- SECURITY.md: Security policy and vulnerability reporting
- CHANGELOG.md: Version history following Keep a Changelog format
- CITATION.cff: Academic citation support (Citation File Format)
3. Issue & PR Templates
- Issue Templates: Bug reports, feature requests, documentation improvements
- Pull Request Template: PR description structure, checklist, review guidelines
- Discussion Templates: Q&A, ideas, announcements (if Discussions enabled)
- Custom Forms: GitHub issue forms with type validation
- Auto-labeling: Automatic label application based on issue type
4. CI/CD Automation
- GitHub Actions: Automated testing, linting, building, deployment
- Quality Gates: Code coverage, security scanning, dependency audits
- Release Automation: Semantic versioning, changelog generation, asset publishing
- Documentation Deployment: GitHub Pages auto-deployment on push
- Dependency Management: Dependabot, automated PR creation for updates
5. Documentation Site
- GitHub Pages: Static site deployment (Jekyll, Docsify, MkDocs, or custom)
- Site Structure: Hierarchical navigation, search functionality
- Custom Domain: DNS configuration and HTTPS setup
- SEO Optimization: Meta tags, sitemaps, structured data
- Mobile Responsive: Cross-device compatibility testing
Implementation Phases
Phase 1: Repository Initialization (30 min)
Step 1: Local Repository Setup
# Initialize git repository
git init
git branch -M main
# Create essential files
touch README.md LICENSE .gitignore
# First commit
git add .
git commit -m "chore: initialize repository"
Step 2: GitHub Repository Creation
# Create on GitHub (via gh CLI)
gh repo create OWNER/REPO --public --source=. --remote=origin
# Or use GitHub web interface for more options
Step 3: Repository Settings
- Enable Issues, Discussions, Projects (as needed)
- Disable Wiki (if using external docs)
- Set default branch to
main - Configure merge options (squash, rebase, merge commits)
- Enable "Automatically delete head branches"
Phase 2: Community Health Files (45 min)
README.md Template:
# Project Name
[](https://github.com/OWNER/REPO/releases)
[](LICENSE)
[](https://github.com/OWNER/REPO/actions)
**One-sentence project description**
## Features
- Feature 1
- Feature 2
- Feature 3
## Quick Start
\`\`\`bash
# Installation
npm install @org/package
# Usage
import { function } from '@org/package'
\`\`\`
## Documentation
Full documentation: [https://owner.github.io/repo](https://owner.github.io/repo)
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.
## License
[MIT License](LICENSE) - see LICENSE file for details.
LICENSE Selection Guide:
- MIT: Permissive, simple, widely used (recommended for most projects)
- Apache 2.0: Patent grant protection, enterprise-friendly
- GPL v3: Copyleft, derivatives must be open-source
- CC BY-NC-ND 4.0: Creative Commons for non-code content (documentation, frameworks)
- Proprietary: Custom license for closed-source with limited distribution
CODE_OF_CONDUCT.md: Use Contributor Covenant (industry standard):
# Via gh CLI
gh repo create-conduct
# Or download from https://www.contributor-covenant.org/
CONTRIBUTING.md Structure:
- Getting Started (development environment setup)
- Development Workflow (branch naming, commit messages)
- Pull Request Process (review criteria, testing requirements)
- Code Style Guidelines (linting, formatting)
- Testing Requirements (coverage thresholds, test types)
- Documentation Standards (inline comments, external docs)
SECURITY.md:
# Security Policy
## Supported Versions
| Version | Supported |
| ------- | ------------------ |
| 1.x | :white_check_mark: |
| < 1.0 | :x: |
## Reporting a Vulnerability
**DO NOT** open a public issue for security vulnerabilities.
Email: [email protected]
Expected response time: 48 hours
CHANGELOG.md: Follow Keep a Changelog format:
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
## [1.0.0] - 2025-11-01
### Added
- Initial release
- Feature X
- Feature Y
### Changed
- Updated dependency Z
### Fixed
- Bug fix for issue #123
CITATION.cff:
cff-version: 1.2.0
title: "Project Name"
message: "If you use this software, please cite it as below."
type: software
authors:
- family-names: Last
given-names: First
email: [email protected]
orcid: "https://orcid.org/0000-0000-0000-0000"
repository-code: "https://github.com/OWNER/REPO"
url: "https://owner.github.io/repo"
license: MIT
version: 1.0.0
date-released: 2025-11-01
Phase 3: Issue & PR Templates (30 min)
Directory Structure:
.github/
├── ISSUE_TEMPLATE/
│ ├── bug_report.md
│ ├── feature_request.md
│ └── documentation.md
├── PULL_REQUEST_TEMPLATE.md
└── CODEOWNERS
Bug Report Template (.github/ISSUE_TEMPLATE/bug_report.md):
---
name: Bug Report
about: Report a bug or unexpected behavior
title: "[BUG] "
labels: bug
assignees: ''
---
## Description
A clear description of the bug.
## Steps to Reproduce
1. Step 1
2. Step 2
3. See error
## Expected Behavior
What should happen.
## Actual Behavior
What actually happens.
## Environment
- OS: [e.g., macOS 14.0]
- Version: [e.g., 1.0.0]
- Node: [e.g., 20.10.0]
## Additional Context
Screenshots, logs, or other context.
Feature Request Template:
---
name: Feature Request
about: Suggest a new feature or enhancement
title: "[FEATURE] "
labels: enhancement
assignees: ''
---
## Problem Statement
What problem does this solve?
## Proposed Solution
How should it work?
## Alternatives Considered
Other approaches you've thought about.
## Additional Context
Any other relevant information.
Pull Request Template (.github/PULL_REQUEST_TEMPLATE.md):
## Description
Brief description of changes.
## Type of Change
- [ ] Bug fix (non-breaking change fixing an issue)
- [ ] New feature (non-breaking change adding functionality)
- [ ] Breaking change (fix or feature causing existing functionality to break)
- [ ] Documentation update
## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed
## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex code
- [ ] Documentation updated
- [ ] No new warnings generated
- [ ] Tests added covering changes
- [ ] All tests passing
- [ ] CHANGELOG.md updated
## Related Issues
Closes #(issue number)
CODEOWNERS (.github/CODEOWNERS):
# Global owners
* @organization/maintainers
# Specific paths
/docs/ @organization/docs-team
/src/ @organization/core-team
/.github/ @organization/devops-team
/tests/ @organization/qa-team
Phase 4: CI/CD Workflows (60 min)
Lint Workflow (.github/workflows/lint.yml):
name: Lint
on:
push:
branches: [ main, develop ]
pull_request:
branches: [ main, develop ]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Run ESLint
run: npm run lint
- name: Run Prettier
run: npm run format:check
Test Workflow (.github/workflows/test.yml):
name: Test
on:
push:
branches: [ main, develop ]
pull_request:
branches: [ main, develop ]
jobs:
test:
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-latest, windows-latest, macos-latest]
node-version: [18.x, 20.x]
steps:
- uses: actions/checkout@v4
- name: Setup Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v4
with:
node-version: ${{ matrix.node-version }}
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Run tests
run: npm test
- name: Upload coverage
uses: codecov/codecov-action@v3
with:
files: ./coverage/lcov.info
Release Workflow (.github/workflows/release.yml):
name: Release
on:
push:
tags:
- 'v*'
jobs:
release:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/checkout@v4
- name: Create Release
uses: actions/create-release@v1
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
with:
tag_name: ${{ github.ref }}
release_name: Release ${{ github.ref }}
draft: false
prerelease: false
GitHub Pages Deploy (.github/workflows/pages.yml):
name: Deploy to GitHub Pages
on:
push:
branches: [ main ]
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Pages
uses: actions/configure-pages@v4
- name: Build site
run: |
# Build commands here
npm run build:docs
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: ./docs
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
needs: build
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
Phase 5: Documentation Site (60 min)
Option 1: Docsify (Recommended for simplicity)
- Create
docs/directory structure:
docs/
├── index.html (Docsify config)
├── README.md (Home page)
├── _sidebar.md (Navigation)
├── guide/
│ ├── getting-started.md
│ └── advanced.md
└── reference/
├── api.md
└── cli.md
docs/index.html:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Project Documentation</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css">
</head>
<body>
<div id="app"></div>
<script>
window.$docsify = {
name: 'Project Name',
repo: 'https://github.com/owner/repo',
loadSidebar: true,
subMaxLevel: 2,
search: 'auto'
}
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
</body>
</html>
docs/_sidebar.md:
- [Home](/)
- [Getting Started](guide/getting-started.md)
- [API Reference](reference/api.md)
Option 2: Jekyll (GitHub Pages default)
- Create
_config.yml:
title: Project Documentation
description: Project description
theme: jekyll-theme-cayman
markdown: kramdown
- Enable GitHub Pages in repository settings
- Select source:
mainbranch,/docsfolder
Option 3: MkDocs (Python-based, feature-rich)
- Install:
pip install mkdocs mkdocs-material - Initialize:
mkdocs new . - Configure
mkdocs.yml - Build:
mkdocs build - Deploy:
mkdocs gh-deploy
Phase 6: Badges & Metadata (15 min)
Essential Badges:
[](https://github.com/OWNER/REPO/releases)
[](LICENSE)
[](https://github.com/OWNER/REPO/actions)
[](https://codecov.io/gh/OWNER/REPO)
[](https://www.npmjs.com/package/@org/package)
Repository Topics:
- Maximum 20 topics
- Use lowercase, hyphens for spaces
- Include: language, framework, use-case, industry
- Example:
typescript,api,mental-models,cognitive-framework
About Section:
- Concise description (160 chars max)
- Include primary use case
- Add website URL if applicable
- Select appropriate topics
Quality Checklist
Repository Health ✅
- README with badges, quick start, and documentation links
- LICENSE file present and appropriate
- CODE_OF_CONDUCT.md following Contributor Covenant
- CONTRIBUTING.md with clear guidelines
- SECURITY.md with vulnerability reporting process
- CHANGELOG.md following Keep a Changelog format
- .gitignore appropriate for project type
Automation ✅
- CI workflow testing on push/PR
- Linting workflow enforcing code style
- Security scanning (Dependabot, CodeQL)
- Automated releases on version tags
- Documentation deployment on main branch push
Templates ✅
- Bug report template
- Feature request template
- Pull request template with checklist
- CODEOWNERS file for automatic review assignment
Documentation ✅
- GitHub Pages enabled and deploying
- Navigation structure clear and hierarchical
- Search functionality working
- Mobile-responsive design
- All links functional
Metadata ✅
- Repository description set
- Topics configured (10-20 relevant tags)
- Website URL added (if applicable)
- Social preview image (1280x640px)
Best Practices
Branch Protection Rules
Settings → Branches → Add rule
Branch name pattern: main
Protection settings:
✅ Require pull request before merging
✅ Require approvals (1-2)
✅ Dismiss stale reviews
✅ Require status checks to pass
✅ Require branches to be up to date
✅ Require conversation resolution before merging
✅ Require signed commits (optional, high security)
✅ Include administrators (recommended)
Semantic Versioning
MAJOR.MINOR.PATCH (e.g., 2.1.3)
MAJOR: Breaking changes
MINOR: New features (backwards compatible)
PATCH: Bug fixes (backwards compatible)
Pre-release: 1.0.0-alpha.1, 1.0.0-beta.2, 1.0.0-rc.1
Build metadata: 1.0.0+20130313144700
Commit Message Convention
<type>(<scope>): <subject>
<body>
<footer>
Types:
- feat: New feature
- fix: Bug fix
- docs: Documentation only
- style: Formatting, no code change
- refactor: Code change (neither fix nor feature)
- perf: Performance improvement
- test: Adding or updating tests
- chore: Maintenance (dependencies, config)
- ci: CI/CD changes
Examples:
feat(api): add mental model search endpoint
fix(parser): handle empty input gracefully
docs(readme): update installation instructions
Release Process
# 1. Update version
npm version [patch|minor|major]
# 2. Update CHANGELOG.md
# Add new version section with changes
# 3. Commit changes
git add .
git commit -m "chore: release v1.2.0"
# 4. Create and push tag
git tag -a v1.2.0 -m "Release v1.2.0"
git push origin main --tags
# 5. GitHub Actions automatically creates release
# Or manually via gh CLI:
gh release create v1.2.0 --title "v1.2.0" --notes-file RELEASE_NOTES.md
Common Pitfalls
Pitfall 1: Incomplete .gitignore
Problem: Sensitive files or build artifacts committed
Solution: Use gitignore.io templates, review before first commit
Pitfall 2: No Branch Protection
Problem: Direct pushes to main, untested code in production
Solution: Enable branch protection immediately after repo creation
Pitfall 3: Unclear Contributing Guidelines
Problem: Poor quality PRs, inconsistent code style
Solution: Detailed CONTRIBUTING.md with examples and linting automation
Pitfall 4: Missing CI/CD
Problem: Broken code merged, manual deployment friction
Solution: Set up basic CI before accepting first PR
Pitfall 5: Stale Documentation
Problem: Docs out of sync with code
Solution: Automate docs deployment, make docs updates part of PR checklist
Resources
- GitHub Docs: https://docs.github.com
- Keep a Changelog: https://keepachangelog.com
- Semantic Versioning: https://semver.org
- Contributor Covenant: https://www.contributor-covenant.org
- Citation File Format: https://citation-file-format.github.io
- GitHub Actions Marketplace: https://github.com/marketplace?type=actions
Success Criteria
Production-ready repository includes:
- ✅ All community health files present and complete
- ✅ Automated testing and linting via GitHub Actions
- ✅ Branch protection preventing untested code in main
- ✅ Clear contribution guidelines and templates
- ✅ GitHub Pages documentation site live
- ✅ Proper versioning and release automation
- ✅ Security policy and vulnerability reporting process
- ✅ Repository discoverable via topics and description
Repository fails if:
- ❌ Missing LICENSE or unclear licensing
- ❌ No CI/CD, manual testing only
- ❌ Direct commits to main possible
- ❌ No documentation or stale docs
- ❌ No contribution guidelines
- ❌ Security vulnerabilities in dependencies