feat: add GitHub Actions skill for workflow creation and debugging

[juanmichelini]

Description

This PR adds a comprehensive GitHub Actions skill that helps with creating, testing, and debugging GitHub Actions workflows and custom actions.

Closes #55

What's Included

SKILL.md

• Complete guide for working with GitHub Actions
• Critical information about testing custom actions (must merge to main first)
• Debug step examples for printing non-secret parameters
• Coverage of all action types (workflows, composite actions, reusable workflows)
• Common pitfalls and non-obvious gotchas including:
  • Action deployment requirements
  • Permission issues (GITHUB_TOKEN, pull_request vs pull_request_target)
  • Secrets handling in fork PRs
  • Path filters, matrix builds, and workflow triggers
  • Artifact handling between jobs
• Local testing with act
• Debugging techniques and gh CLI usage
• Best practices for security and performance

README.md

• Detailed scenarios and use cases
• Step-by-step examples for common workflows
• Advanced patterns (reusable workflows, conditional jobs)
• Related skills and resources

marketplace.json

• Registered the skill with appropriate keywords and categorization

Key Features

✅ Testing Requirements: Clearly explains the requirement to merge actions to main before use
✅ Debug Guidance: Emphasizes adding debug steps that print non-secret parameters
✅ Practical Examples: Code snippets for real-world scenarios
✅ Security Focus: Covers permissions, secrets, and fork PR handling
✅ Comprehensive Coverage: Addresses tricky, non-obvious issues like:

• Workflow file changes not triggering themselves
• Path filter OR behavior
• Action version pinning vs @main
• Environment variable scopes

Testing

All existing tests pass:

• ✅ Skills have README test
• ✅ JSON validation for marketplace.json

Related Issue

Implements the feature requested in #55 by @juanmichelini

@juanmichelini can click here to continue refining the PR

[all-hands-bot]

Taste Rating: 🟡 Acceptable - Technically solid content but violates progressive disclosure principle.

Verdict: ✅ Worth merging with strong recommendation to refactor for efficiency.

Key Insight: You built a comprehensive reference manual when you needed a concise decision guide. SKILL.md at 530 lines will burn significant context tokens every time an agent loads it—that's the wrong data structure for the progressive disclosure use case.

[all-hands-bot]

Taste Rating: 🔴 Needs improvement - Violates AgentSkills progressive disclosure architecture

Verdict: Content quality is solid, but the data structure problem identified in previous reviews remains unaddressed.

Key Insight: SKILL.md should be a 50-80 line decision guide, not a 526-line reference manual—that's an architectural requirement, not a style preference.

[all-hands-bot]

🔴 Critical - Architecture Violation: This file is 526 lines. The AgentSkills spec and previous reviews identified this as a progressive disclosure violation. SKILL.md should be <100 lines—enough for an agent to decide "do I need this?" not "here's every detail."

The Fix: Keep lines 1-23 (frontmatter + Critical Rules). Add a "Quick Patterns" section with 3-5 common patterns (3 lines each). Add "See README.md for detailed examples." Total: ~50-80 lines. Move everything else to README.md.

Why this matters: Every skill load burns context tokens. 526 lines of examples that aren't needed for the initial decision is the wrong data structure for this use case.

[juanmichelini]

@OpenHands address the reviewers points

[openhands-ai]

I'm on it! juanmichelini can track my progress at all-hands.dev

[openhands-ai]

Summary of Changes Made

I've successfully addressed all reviewer feedback on PR #56 for the GitHub Actions skill. The changes have been committed and pushed to the remote branch.

✅ Request Completion Checklist

Reviewer Points Addressed:

• ✅ Progressive Disclosure Architecture: SKILL.md reduced from 526 to 81 lines (target: 50-80)
• ✅ Data Structure Fixed: SKILL.md is now a decision guide, README.md is the reference manual
• ✅ Context Token Efficiency: 84% reduction in SKILL.md size (526 → 81 lines)
• ✅ Redundancy Eliminated: No repeated content between files
• ✅ Debug Guidance Clarified: Updated to specify "for new actions OR tricky issues" (not always)
• ✅ Content Reorganized: All detailed examples, debugging, testing moved to README.md

Changes Made (2 files modified)

skills/github-actions/SKILL.md (526 → 81 lines):

• Kept frontmatter and Critical Rules section
• Added concise Quick Patterns (3 action type examples)
• Added Key Gotchas (4 most critical issues)
• Added pointer to README.md for detailed information

skills/github-actions/README.md (285 → 607 lines):

• Expanded Types of Actions with full examples
• Enhanced Common Pitfalls (5 → 10 with code samples)
• Added Local Testing with act section
• Added Debugging Failed Workflows section
• Added Best Practices with implementation example

Validation

• ✅ All tests pass (README existence check, JSON validation)
• ✅ No extraneous changes
• ✅ Changes are concise and focused
• ✅ Committed with descriptive message
• ✅ Already pushed to origin/openhands/add-github-actions-skill

PR #56 has been updated and now properly implements the AgentSkills progressive disclosure specification.

[juanmichelini]

@OpenHands remove the Quick Patterns section. Add comments to make sure the agent is effective when testing and understanding actions. We want to monitor them, we want to read logs, we want to figure out what's actually happenning not guessing. Think best practices for developing an action with confidence and add them.

Notice that actions have costs so we should take that into account when deciding a plan to test and monitor.
This skill is about effectiveness when working with github actions as SWE, not about syntax.

[openhands-ai]

I'm on it! juanmichelini can track my progress at all-hands.dev

[openhands-ai]

Summary of Changes

I've successfully addressed the reviewer's feedback on PR #56 for the GitHub Actions skill. Here's what was changed:

✅ Request Completion Checklist

• ✅ Removed Quick Patterns section - Eliminated syntax-focused code examples (basic workflow, composite action, reusable workflow)
• ✅ Added Testing & Monitoring Strategy section - New content focused on SWE effectiveness
• ✅ Emphasized cost awareness - Highlighted that actions consume CI minutes and planning is essential
• ✅ Added monitoring best practices - Included practical gh CLI commands for watching runs and reading logs
• ✅ Focused on understanding, not guessing - Emphasized reading actual logs and values instead of trial-and-error
• ✅ Added visibility examples - Provided debug step patterns for printing inputs and verifying outputs

Changes Are Concise

The modification was surgical - only the "Quick Patterns" section (lines 26-65) was replaced with the new "Testing & Monitoring Strategy" section. No extraneous changes were made. The file went from 82 to 88 lines, with the increase coming from more detailed debugging guidance as requested.

What Changed

The SKILL.md now leads with practical effectiveness instead of syntax examples:

• 5-point strategy for efficient testing (local first, debug early, monitor actively, read logs, understand before changing)
• Real debugging workflow with gh run watch, gh pr checks --watch, and log viewing commands
• Example debug steps showing how to add visibility to actions (inputs at start, results at end)

Commit pushed: ecc38a31588e2f17dd73148c7462b111032445fc

The skill is now focused on working with GitHub Actions as a professional SWE - monitoring, understanding, and debugging with confidence rather than just syntax knowledge.