Skill: dot-github

Standardize .github directory structure, enforce agentic documentation patterns.

When to Use

• When establishing or organizing the structure of the .github/ directory for a new repository.
• To create or update AGENTS.md documentation specifically for the workflows folder.
• When you need to safely disable a workflow by moving it instead of deleting it.

When Not to Use

• For creating generic documentation outside of the .github/ folder (use docs-writer instead).
• When configuring actual CI/CD pipeline logic inside the YAML files (use github-actions or gh-aw-syntax).
• If you are managing organization-wide .github repository templates and don't want to override them locally.

Common Pitfalls

• Creating .github/README.md: Generating a README inside the .github/ directory, which GitHub prioritizes and uses to completely overwrite the repository's main homepage.
• Inventing CODEOWNERS: Guessing usernames or teams in the CODEOWNERS file instead of verifying their existence, rendering the file invalid and breaking PR approvals.
• Destructive Deletion: Deleting a workflow file completely instead of moving it to .github/workflows-disabled/, losing its history and configuration.

Core Principles

• Configuration Validation: Validate .github/mcp-config.json if the file exists.
• Disabling Workflows: To temporarily disable workflows, consider moving them to .github/workflows-disabled/.
• Do Not Invent CODEOWNERS: Never guess or invent teams in CODEOWNERS when they are unknown. Only use verified, existing teams.
• Agentic Instructions (AGENTS.md):
  • Use .github/AGENTS.md to describe the structure of the .github directory and its contents (agents, instructions, prompts, skills).
  • Use .github/workflows/AGENTS.md to list workflows that can be triggered manually (crucial when the agent has actions write permissions).
  • Document available prompts in .github/prompts/AGENTS.md and specify when to load them.
  • Document instruction scopes in .github/instructions/AGENTS.md.
• Upstream Organization Fallbacks: If an org/owner-level .github repository exists, follow its upstream guides instead of creating local duplicates (e.g., CONTRIBUTING.md, ISSUE_TEMPLATE/).
• Workflow Documentation: Document the list of available workflows in .github/workflows/README.md.

Firewall

To document encountered restrictive firewall during runtime, this can be documented in .github/FIREWALL.md, e.g.

# Firewall Allowlist

If your agent runs behind a restrictive firewall, allow these hosts.
Always check the official guidance for updates.

```plaintext
agents.md
aka.ms
gh.io
ghcr.io
github.com
img.shields.io
pkg-containers.githubusercontent.com
raw.githubusercontent.com
support.github.com
tldrlegal.com
uploads.github.com
user-images.githubusercontent.com
yaml-multiline.info
web.archive.org
```

Note: Keep the list sorted alphabetically for easier maintenance.

Reference: <https://gh.io/copilot/firewall-config>

Hardened NEVER List

• NEVER create .github/README.md: GitHub renders .github/README.md with the highest priority. Creating it will override the main README.md on the repository homepage and profile page.
• Do not break your own workflow: Refactoring, such as removing required triggers, can prevent the workflow from being triggered again. Always be careful and double-check your changes to ensure the continuity of your own runtime workflow.

What to Avoid

• Creating undocumented workflows in .github/workflows/.
• Deleting workflows instead of moving them to .github/workflows-disabled/.
• Overwriting upstream organization defaults in .github/ repo.

Related Skills

• agents-md-writer: You MUST load this skill when creating or updating AGENTS.md files.
• docs-writer: You MUST load this skill when asked to write, document, or generate new documentation.