Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Apply the AI FIRST principle: never accept first-pass quality. Minimum 2 iterations. Read all output, improve every section. No shortcuts.
๐ Purpose
Master the safe outputs pattern in GitHub Agentic Workflows - the foundational security mechanism that enables AI agents to perform write operations safely through explicit, human-approved outputs. This skill provides comprehensive expertise in designing, implementing, and operating safe output patterns for controlled AI automation.
๐ฏ Core Concept
What Are Safe Outputs?
Safe outputs are the only way AI agents can perform write operations (create/update files, issues, PRs) in GitHub Agentic Workflows. Unlike direct tool access, safe outputs require explicit approval and sanitization before execution.
Key Principles:
๐ Write Isolation: All write operations go through safe outputs
โ Explicit Approval: Outputs must be explicitly declared in workflow
๏ฟฝ๏ฟฝ Automatic Sanitization: All outputs sanitized before execution
๐ Auditable: All actions logged and traceable
๐ซ No Direct Writes: AI cannot write files/issues/PRs directly
Create or update GitHub issues with AI-generated content.
Configuration:
tools:safeoutputs___issue:# No additional config required
Usage Pattern:
# Workflow markdown body
Analyze this codebase and create issues for improvement opportunities.
For each issue, use safeoutputs___issue:
- title: Brief description
- body: Detailed explanation with code examples
- labels: ["enhancement", "ai-generated"]
Review this codebase and propose improvements.
Create a pull request using safeoutputs___pull_request:
- branch: "ai/improve-error-handling"
- title: "Improve error handling"
- body: Description of changes
- files: List of file changes
AI Output Format:
{"tool":"safeoutputs___pull_request","branch":"ai/improve-error-handling","title":"Improve error handling in authentication module","body":"## Changes\n\n- Added try-catch blocks\n- Implemented error logging\n- Added tests","files":[{"path":"src/auth.ts","content":"// New content...","encoding":"utf-8"}]}
Sanitization Applied:
โ Branch name validated (alphanumeric, hyphens, slashes only)
โ File paths validated (no directory traversal)
โ File content scanned for secrets
โ File size limits enforced (max 1MB per file)
โ Binary files rejected
โ Suspicious patterns blocked
Execution:
Creates new branch from base
Commits files with AI signature
Creates pull request
Returns PR URL
Triggers CI/CD
3. safeoutputs___comment
Add comments to issues or pull requests.
Configuration:
tools:safeoutputs___comment:# No additional config required
Usage Pattern:
Provide helpful feedback on this pull request.
Add a comment using safeoutputs___comment:
- issue_number: 123 # or pr_number
- body: Your feedback
AI Output Format:
{"tool":"safeoutputs___comment","issue_number":123,"body":"## Code Review\n\nI noticed a few areas for improvement:\n\n1. **Error Handling**: Consider adding...\n2. **Performance**: The loop in line 45 could be optimized..."}
Update documentation to reflect recent changes.
Create/update files using safeoutputs___file:
- path: docs/api.md
- content: Updated documentation
- commit_message: Update API documentation
AI Output Format:
{"tool":"safeoutputs___file","path":"docs/api.md","content":"# API Documentation\n\n## Authentication\n\n...","commit_message":"Update API documentation with new endpoints","encoding":"utf-8"}
Sanitization Applied:
โ Path validated against allowed_paths
โ No directory traversal (../)
โ File size limits enforced
โ Secret scanning
โ Binary file detection
โ Malicious content removed
5. safeoutputs___label
Add or remove labels from issues or pull requests.
Configuration:
tools:safeoutputs___label:# No additional config required
Usage Pattern:
Triage this issue and apply appropriate labels.
Use safeoutputs___label:
- issue_number: 123
- add: ["bug", "high-priority"]
- remove: ["needs-triage"]
No operation - AI provides information without taking action.
Configuration:
tools:safeoutputs___noop:# Always available, no config
Usage Pattern:
Analyze this issue and provide recommendations without taking action.
Use safeoutputs___noop to report findings.
AI Output Format:
{"tool":"safeoutputs___noop","message":"## Analysis\n\nThis issue appears to be a duplicate of #456.\n\n## Recommendation\n\nClose this issue and direct the reporter to #456."}
# โ DON'T: Grant all toolstools:safeoutputs___*:# โ DO: Grant only needed toolstools:safeoutputs___issue:safeoutputs___comment:
2. Restrict File Paths
# โ DON'T: Allow all pathstools:safeoutputs___file:allowed_paths: ["**"]
# โ DO: Whitelist specific pathstools:safeoutputs___file:allowed_paths:-"docs/**/*.md"-"README.md"
3. Use Human-in-the-Loop for Critical Operations
# For critical operations, use noop + manual approvaltools:safeoutputs___noop:# AI provides recommendation# Human reviews recommendation# Human manually executes if appropriate
# Test workflow with noop only
tools:
safeoutputs___noop:
# Review AI outputs# Enable actual tools gradually
๐ Workflow Examples
Example 1: Issue Triage
---
on: issues
tools:
github:
toolsets: [issues]
safeoutputs___label:
safeoutputs___comment:
---
Analyze this issue and provide triage:
1. Determine if it's a bug, feature, or question
2. Apply appropriate labels using safeoutputs___label
3. Add helpful comment using safeoutputs___comment
4. Suggest assignee if applicable
Example 2: Documentation Updates
---
on: push
tools:
github:
toolsets: [repos]
bash:
allowed-commands: [git]
safeoutputs___file:
allowed_paths: ["docs/**"]
---
Review recent code changes and update documentation:
1. Identify changed files
2. Review related documentation
3. Update docs using safeoutputs___file
4. Ensure examples are current
Example 3: Code Review
---
on: pull_request
tools:
github:
toolsets: [pull_requests]
safeoutputs___comment:
---
Review this pull request and provide feedback:
1. Check code quality
2. Identify potential issues
3. Add review comment using safeoutputs___comment
4. Suggest improvements
๐จ Common Pitfalls
Pitfall 1: Overly Permissive Paths
# โ BADallowed_paths: ["**"] # Allows all files# โ GOODallowed_paths: ["docs/**/*.md"] # Specific patterns
Pitfall 2: Assuming Direct Write Access
# โ BAD: Trying to write files directly
Write to src/config.ts
# โ GOOD: Using safe outputs
Use safeoutputs___file to update src/config.ts
Pitfall 3: Not Testing Sanitization
# Test with malicious inputs:# - Path traversal: ../../../etc/passwd# - XSS: <script>alert('xss')</script># - Secrets: API_KEY=abc123def456
Pitfall 4: Ignoring Size Limits
# Configure appropriate limitsmax_file_size:1048576# 1MB for codemax_file_size:10485760# 10MB for docs
Prompt injection โ Attempts to override instructions via crafted content
Leaked credentials โ API keys, tokens, passwords in output
Malicious code โ Known attack patterns, obfuscated payloads
This is automatic โ no configuration needed. If detection fails, nothing is written.
Safe Output Types Reference
Type
Frontmatter Key
What It Does
Issue
create-issue
Create/update GitHub issues
Pull Request
create-pull-request
Create PRs (including cross-repo)
Comment
add-comment
Add comments to issues/PRs
Label
add-labels
Add labels to issues/PRs
File
create-or-update-file
Modify repository files
Dispatch
dispatch-workflow
Trigger other workflows (with workflows whitelist and max count)
Noop
(default)
Read-only, no writes
Additionally, safe-outputs supports a top-level allowed-domains key to whitelist network endpoints the agent may contact (see this repo's news workflows for examples).
Constraints You Can Set
---
safe-outputs:
create-issue:
title-prefix: "[bot] " # Required title prefix
labels: [automated, report] # Allowed labels only
max-count: 1 # Max issues per run
close-older-issues: true # Auto-close previous
create-pull-request:
max-count: 1
target-repo: owner/other-repo # Cross-repo support
add-labels:
allowed: [bug, feature, docs] # Whitelist of labels
---
โ Safe outputs are the ONLY way AI agents write to GitHub
โ All outputs pass through threat detection before applying
โ Sanitization is automatic โ no opt-in needed
โ Set max-count to limit operations per run
โ Use title-prefix for easy identification
โ Use allowed lists to restrict labels/paths
โ Cross-repo PRs supported via target-repo
โ Use noop (default) for read-only analysis workflows
โ Monitor audit logs for anomalies
โ Secret scanning prevents credential leaks in outputs
Version: 2.0.0 Last Updated: 2026-04-02 Maintained by: Hack23 AB
๐ Integration with Riksdagsmonitor agentic workflows
This gh-aw skill is applied by the 11 agentic news workflows in .github/workflows/news-*.md. Their domain contract (analysis-artifact product, gate, article contract) lives in:
