🤖 GitHub Agentic Workflows Skill

Purpose

This skill provides comprehensive guidance on GitHub Agentic Workflows, a revolutionary approach to repository automation that uses AI to understand context, make decisions, and take autonomous actions through natural language instructions. Unlike traditional workflows with fixed if/then logic, agentic workflows interpret context and adapt behavior based on specific situations.

GitHub Agentic Workflows enables Continuous AI - systematic, automated application of AI to software collaboration tasks like triaging issues, maintaining documentation, improving code quality, and automating reviews.

When to Use

Apply this skill when:

• Creating AI-powered repository automation workflows

• Converting deterministic GitHub Actions to intelligent, context-aware workflows

• Implementing continuous AI patterns for issue triage, documentation sync, or code review

• Building workflows that require judgment, synthesis, or content generation

• Automating tasks that traditionally require human decision-making

Rules

Workflow Structure

MUST:

• Create workflow files as Markdown (.md ) in .github/workflows/ directory

• Include YAML frontmatter between --- markers at the top of the file

• Write natural language instructions below the frontmatter

• Compile Markdown workflows to .lock.yml files using gh aw compile

• Commit both .md (source) and .lock.yml (compiled) files to version control

• Use declarative, clear, imperative task descriptions in natural language

• Separate configuration (frontmatter) from instructions (markdown body)

MUST NOT:

• Write complex YAML conditionals or programming logic in workflow files

• Rely solely on .lock.yml files (they are generated artifacts)

• Mix configuration and instructions in the same section

• Use traditional GitHub Actions YAML syntax for agentic workflows

• Skip compilation step before deployment

Frontmatter Configuration

MUST:

• Define on: trigger(s) for when the workflow runs

• Set permissions: (default to read-all for security)

• Configure tools: that the AI agent can use

• Specify engine: if not using default GitHub Copilot

• Include safe-outputs: for any write operations

MUST NOT:

• Grant unnecessary write permissions

• Use permissions: write-all without explicit justification

• Omit critical configuration fields

• Hard-code secrets in frontmatter

Natural Language Instructions

MUST:

• Write clear, specific, actionable task descriptions

• Use imperative mood ("Analyze this issue", not "You should analyze")

• Include context about what the workflow should accomplish

• Define success criteria and constraints

• Specify expected outputs (comments, PRs, issues)

• Break complex tasks into clear phases

• Provide examples of expected behavior

MUST NOT:

• Write vague instructions ("Do something helpful")

• Assume the AI knows implicit context

• Include implementation details (let AI determine approach)

• Write instruction text that looks like code or YAML

Engines (AI Models)

MUST:

• Use GitHub Copilot as default engine (no explicit configuration needed)

• Configure appropriate secrets for alternative engines:

• Claude: ANTHROPIC_API_KEY secret

• Codex: OPENAI_API_KEY secret

• Test workflows with chosen engine before production deployment

MUST NOT:

• Mix multiple engines in same workflow

• Assume all engines have identical capabilities

• Skip engine-specific setup documentation

Triggers

MUST:

• Choose appropriate trigger(s) for workflow purpose:

• issues: for issue-related automation

• pull_request: for PR-related automation

• schedule: for periodic tasks

• workflow_dispatch: for manual execution

• slash_command: for comment-triggered actions

• Use human-friendly schedule syntax: daily , weekly on monday

• Consider rate limits and costs for scheduled workflows

• Test manual triggers before enabling automated triggers

MUST NOT:

• Use overly frequent schedules that waste resources

• Trigger on every event type without considering necessity

• Use fixed cron times (prefer scattered schedule syntax)

Tools and MCP Integration

MUST:

• Explicitly configure tools in frontmatter under tools: section

• Use github: tool for GitHub API operations (issues, PRs, comments)

• Configure network permissions when external API access is needed

• Use safe-inputs: for custom lightweight tools

• Use edit: tool for file modifications

• Use bash: tool for shell commands when needed

• Use web-search: or web-fetch: for external information

• Document tool purpose and constraints

MUST NOT:

• Grant unrestricted tool access without review

• Use tools without understanding their security implications

• Bypass tool allowlists

• Ignore network access controls

Compilation Process

MUST:

• Install gh-aw CLI extension: gh extension install github/gh-aw

• Compile workflows: gh aw compile (generates .lock.yml files)

• Use gh aw compile --watch for iterative development

• Review generated .lock.yml for security hardening

• Validate compilation errors before pushing changes

• Keep .md and .lock.yml files synchronized

MUST NOT:

• Manually edit .lock.yml files (regenerate with compile)

• Push .md changes without recompiling

• Ignore compilation warnings or errors

• Skip validation of generated Actions workflow

Repository Setup

MUST:

• Run gh aw init to initialize repository for agentic workflows

• Configure required secrets (engine API keys, tokens)

• Set up fine-grained Personal Access Tokens with minimal permissions

• Document secrets configuration in repository README

• Test workflow execution with gh aw run <workflow-name>

MUST NOT:

• Skip initialization steps

• Use classic PATs instead of fine-grained tokens

• Grant excessive permissions to workflow tokens

• Commit secrets to version control

Examples

Example 1: Simple Issue Triage Workflow

on: issues permissions: read-all tools: github: safe-outputs: create-comment: max: 1

Issue Triage

Analyze new issues and provide helpful triage information:

1. Assess if the issue description is clear and actionable
2. Check if it's a duplicate of existing issues
3. Suggest appropriate labels based on content
4. If the issue is unclear, politely ask for clarification

Provide your analysis as a comment on the issue.

Example 2: Documentation Sync Workflow

on: daily permissions: read-all tools: github: edit: safe-outputs: create-pull-request: max: 1

Daily Documentation Sync

Check if repository documentation is up to date:

1. Review README.md and compare with actual codebase structure
2. Check if API documentation matches current endpoints
3. Verify example code still works with current version
4. Update changelog if recent commits aren't documented

If updates are needed, create a pull request with:

• Clear description of documentation changes
• Reference to relevant code changes
• Explanation of why updates were necessary

Example 3: Code Review Assistant

on: pull_request permissions: read-all tools: github: safe-outputs: create-comment: max: 5

Code Review Assistant

Provide constructive code review feedback:

1. Check for common security issues (SQL injection, XSS, secrets in code)
2. Identify code style inconsistencies
3. Suggest performance improvements if obvious
4. Check test coverage for new code
5. Verify documentation is updated for API changes

Post review comments on specific lines where issues are found. Be constructive and educational in your feedback.

Example 4: Weekly Repository Status Report

on: weekly on monday permissions: read-all tools: github: safe-outputs: create-issue: max: 1

Weekly Repository Health Report

Generate a comprehensive repository status report:

Analysis Areas

1. Pull Requests: Count open PRs, age of oldest PR, stale PRs
2. Issues: Count open issues, recently closed issues, issue velocity
3. Activity: Commits this week, contributors this month
4. Dependencies: Any security alerts or outdated dependencies

Create an issue with the report titled "Weekly Status Report - [DATE]". Include actionable recommendations for repository maintainers.

Example 5: Slash Command Workflow

on: slash_command: command: /analyze permissions: read-all tools: github: web-search: safe-outputs: create-comment: max: 1

Issue Analysis Command

When triggered with /analyze command on an issue:

1. Search for similar issues in other repositories
2. Find relevant Stack Overflow discussions
3. Check if this is a known issue in dependencies
4. Provide links to relevant documentation

Respond with findings as a comment on the issue.

Example 6: Custom Tool with Safe Inputs

on: issues permissions: read-all tools: github: safe-inputs: calculate_priority: type: function description: Calculate issue priority based on labels and content code: | function calculate_priority(labels, body) { let score = 0; if (labels.includes('critical')) score += 10; if (labels.includes('security')) score += 8; if (labels.includes('bug')) score += 5; if (body.toLowerCase().includes('production')) score += 3; return score; } safe-outputs: create-comment: max: 1

Priority Calculator

Use the calculate_priority tool to assess issue priority. Post a comment with the priority score and recommended action timeline.

Example 7: Network-Restricted Workflow

on: pull_request permissions: read-all tools: github: network: defaults: - github.com - api.github.com safe-outputs: create-comment: max: 1

Security-Focused PR Review

Review pull request for security issues. Only access GitHub APIs - no external network calls allowed.

Focus on:

• Hard-coded secrets or credentials
• Unsafe input handling
• Missing authentication checks

Example 8: Multi-Engine Configuration

on: workflow_dispatch engine: claude # Use Anthropic Claude instead of Copilot permissions: read-all tools: github: safe-outputs: create-issue: max: 1

Advanced Analysis with Claude

Perform deep technical analysis of repository architecture. Create an issue with findings and recommendations.

Note: Requires ANTHROPIC_API_KEY secret to be configured.

Workflow Best Practices

Start Simple, Iterate

• Begin with read-only workflows

• Test with workflow_dispatch before enabling automatic triggers

• Add safe-outputs incrementally

• Use gh aw compile --watch for rapid iteration

Clear Instructions Win

• Write as if explaining task to a human colleague

• Include examples of desired output

• Define constraints and guardrails explicitly

• Specify what NOT to do when relevant

Security First

• Use minimal permissions (read-all by default)

• Leverage safe-outputs instead of direct write permissions

• Review AI-generated content before merging

• Monitor workflow costs and usage

Test Before Deploy

• Use gh aw run for manual testing

• Review logs with gh aw logs

• Test with real repository data

• Validate safe-outputs are appropriate

Monitor and Improve

• Track workflow success rates

• Gather feedback from generated outputs

• Refine instructions based on actual behavior

• Update workflows as repository evolves

Compilation and Deployment Flow

1. Author Workflow └─ Create .github/workflows/my-workflow.md

2. Compile └─ Run: gh aw compile └─ Generates: .github/workflows/my-workflow.lock.yml

3. Commit Both Files └─ git add .github/workflows/my-workflow.md └─ git add .github/workflows/my-workflow.lock.yml └─ git commit -m "Add my-workflow"

4. Push to GitHub └─ git push

5. Configure Secrets └─ Add required API keys/tokens in repository settings

6. Test └─ Run: gh aw run my-workflow └─ Or: Trigger from GitHub Actions tab

7. Monitor └─ Check: gh aw logs └─ Review: GitHub Actions logs

Troubleshooting

Compilation Fails

• Check YAML frontmatter syntax

• Verify all required fields are present

• Review error messages carefully

• Ensure gh-aw CLI is up to date: gh extension upgrade gh-aw

Workflow Doesn't Trigger

• Verify trigger configuration in frontmatter

• Check that .lock.yml file exists and is committed

• Review GitHub Actions logs for errors

• Ensure workflow file name matches Actions expectations

AI Output Quality Issues

• Refine instructions for clarity and specificity

• Add examples of desired outputs

• Include constraints and guardrails

• Consider switching engine if persistent issues

Permission Errors

• Review permissions in frontmatter

• Check if safe-outputs are properly configured

• Verify secrets are correctly set up

• Ensure token has required scopes

Related ISMS Policies

This skill aligns with:

• Secure Development Policy - Secure automation practices

• Access Control Policy - Least privilege for workflows

• Cryptographic Controls Policy - Secure secret management

• Information Security Policy - Overall security framework

Related Skills

• Agentic Workflow Security - Security best practices and threat detection

• Agentic Workflow Orchestration - Multi-agent patterns and coordination

• Agentic Workflow Development - CLI usage, testing, debugging

• Continuous AI Patterns - Automation patterns and best practices

• MCP Server Integration - Model Context Protocol servers

• Copilot Agent Patterns - Custom agent design patterns

Related Documentation

• GitHub Agentic Workflows Official Documentation

• GitHub Actions Documentation

• Model Context Protocol Specification

Compliance Mapping

ISO 27001:2022

• A.8.25 Secure development life cycle

• A.8.32 Change management

• A.5.23 Information security for use of cloud services

NIST Cybersecurity Framework 2.0

• GV.OV-03: Cybersecurity supply chain risk management

• PR.DS-02: Data-in-transit is protected

• DE.CM-07: Monitoring for unauthorized changes

CIS Controls v8.1

• Control 16: Application Software Security

• 16.1 Establish and Maintain a Secure Application Development Process

• 16.11 Leverage Vetted Modules or Services for Application Security Components

Enforcement

Violations of GitHub Agentic Workflows rules:

• Critical: Hard-coded secrets, unrestricted permissions - Block deployment

• High: Missing compilation, unsafe tool configuration - Require remediation before merge

• Medium: Unclear instructions, missing documentation - Create improvement tickets

• Low: Style inconsistencies, optimization opportunities - Optional improvements

Version History

• 2026-02-11: Initial skill creation based on latest GitHub Agentic Workflows features and documentation