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.

[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.

[all-hands-bot]

Taste Rating: 🟡 Acceptable but could be more concise

Verdict: ✅ Worth merging - Massive improvement from 526→87 lines, but 45 lines of how-to content still belongs in README.md

Key Insight: The "Critical Rules" section shows what good progressive disclosure looks like—apply that pattern to the entire SKILL.md by moving detailed debugging workflows to README.md.

[all-hands-bot]

🟡 Acceptable - Solid improvement (526→78 lines) but still mixing decision criteria with tutorial content per previous reviews.

[juanmichelini]

@OpenHands address reviewrs conerns and mark for rereview

[openhands-ai]

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

[juanmichelini]

Reviewer Concerns Addressed — Ready for Re-review

All three unresolved review threads from the last bot review have been addressed in 6dd9504 and the threads have been resolved.

#	Concern	Resolution
1	Grammar: should tested → should be tested	Fixed
2	46-line Testing & Monitoring section is tutorial content — move to README.md	Moved. SKILL.md is now 43 lines (decision criteria only)
3	Expand README.md with the practical how-to	README.md is now ~189 lines covering the full develop-with-confidence loop

What's in SKILL.md now (43 lines)

• Critical Rules — action deployment + when to add debug steps
• Effectiveness Principles — five bullets covering cost awareness, monitoring vs. polling, reading logs vs. guessing, printing actual values, local-first testing, and smallest reproduction
• Key Gotchas — fork secrets, version pinning, permissions, artifacts
• Pointer to README.md for commands and YAML examples

What's in README.md now (~189 lines)

• Cost Awareness — concrete practices to minimize CI-minute spend
• Develop With Confidence: The Loop — 6-step debug methodology (don't change → push → hope)
• Monitoring Runs With gh — gh run watch, gh pr checks --watch, listing runs
• Reading Logs (Don't Guess) — gh run view --log, --log-failed, per-job logs, rerunning only failed jobs
• Adding Visibility to Actions — YAML debug-step example gated by runner.debug == '1' so it doesn't bloat normal runs
• Testing Locally With act — commands and honest caveats about runner differences
• Custom Actions Require Merge to Main — why, and the SHA/local-path workaround
• 10 Common Pitfalls — with specific guidance
• Best Practices — pinning, least-privilege, concurrency, timeouts, set -euo pipefail

Verification

• ✅ pytest tests/ — 3 passed
• ✅ marketplace.json JSON validates
• ✅ All three previously-unresolved review threads now resolved with reply comments referencing the fix commit

This comment was created by an AI agent (OpenHands) on behalf of @juanmichelini.

[openhands-ai]

Summary

Addressed all three remaining unresolved reviewer concerns on PR #56 and marked it for re-review.

Request Completion Checklist

• ✅ Fetched unresolved review threads via GraphQL and identified exactly what was still blocking
• ✅ Grammar fix — should tested → should be tested in SKILL.md
• ✅ Progressive disclosure — moved the 46-line "Testing & Monitoring Strategy" section (bash commands + YAML examples) out of SKILL.md, which is now 43 lines of pure decision criteria (Critical Rules, 5 Effectiveness Principles, Key Gotchas, pointer to README)
• ✅ README expansion — README.md grew from 34 → 189 lines absorbing the practical how-to: cost awareness, 6-step develop-with-confidence loop, gh run monitoring/log commands, act usage with caveats, debug-step YAML gated by runner.debug == '1', custom-action merge-to-main rationale, 10 pitfalls, best practices
• ✅ Preserved prior user guidance (effectiveness, monitoring, reading logs, cost awareness, no guessing) — kept as concise principles in SKILL.md and elaborated in README.md
• ✅ Tests pass — pytest tests/ shows 3 passed
• ✅ JSON valid — marketplace.json still validates
• ✅ Committed and pushed as 6dd9504 to openhands/add-github-actions-skill
• ✅ Replied to and resolved all three review threads with references to the fix commit
• ✅ Posted PR summary comment with AI-disclosure footer
• ✅ Requested re-review from all-hands-bot via the pulls API

Conciseness

Only two files changed: skills/github-actions/SKILL.md (78 → 43 lines) and skills/github-actions/README.md (34 → 189 lines). No extraneous edits to other skills, tests, or config. The diff is 2 files changed, 180 insertions(+), 60 deletions(-). The PR remains in draft state — per policy I did not mark it ready for review.

[all-hands-bot]

✅ Review complete.

This review was performed through OpenHands Cloud Automation. You can log in and view the conversation here.

[all-hands-bot]

Good addition — the README is thorough, the gh command examples are accurate, and the cost-awareness / debug-loop framing is genuinely useful. There is one blocking bug (wrong source path in marketplace.json) and a couple of issues in SKILL.md worth addressing before merge.

This review was generated by an AI agent (OpenHands) on behalf of the user through OpenHands Automation. View conversation

[juanmichelini]

@OpenHands address reviewrs concerns and mark for rereview

[openhands-ai]

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

[juanmichelini]

Reviewer Concerns Addressed — Ready for Re-review

Addressed the 5 unresolved threads from the last bot review in 888acf2.

#	Concern	Resolution
1	marketplace.json source path	Declined — file has metadata.pluginRoot: "./skills"; all existing entries use ./<name>. Suggested change would break path resolution. Explained inline.
2	Triggers too generic (workflow, ci/cd)	Replaced with GitHub-Actions-specific triggers: github actions, github workflow, actions workflow, gh actions, .github/workflows
3	pull_request_target wording too soft	Adopted reviewer-suggested phrasing — explicit about RCE risk if fork PR code is checked out
4	act Docker prerequisite missing	Noted Docker must be installed and running
5	Pitfall #5 inaccurate	Rewrote — real gotcha is schedule:/workflow_dispatch: triggers, not pull_request workflows

Threads 2–5 are resolved. Thread 1 left unresolved for human reviewer judgement since the suggested fix appears factually incorrect.

This comment was generated by an AI agent (OpenHands) on behalf of @juanmichelini.

[openhands-ai]

Summary

Addressed all 5 unresolved review threads on PR #56 in commit 888acf2, pushed, and requested re-review from all-hands-bot.

Request Completion Checklist

• ✅ Fetched unresolved threads via GraphQL — identified 5 open items
• ✅ SKILL.md triggers tightened — replaced generic workflow, ci/cd with GitHub-Actions-specific triggers (github actions, github workflow, actions workflow, gh actions, .github/workflows)
• ✅ SKILL.md pull_request_target wording — adopted reviewer's exact suggested wording making the RCE risk explicit
• ✅ README.md act Docker prerequisite — added note that Docker must be installed and running
• ✅ README.md pitfall Add skill for writing behavior tests #5 — corrected the inaccurate claim; now correctly describes schedule:/workflow_dispatch: triggers needing to be on default branch
• ✅ Replied + resolved threads 2–5 with commit reference
• ✅ marketplace.json source path — respectfully declined with technical explanation: the file's metadata.pluginRoot: "./skills" means ./github-actions already resolves correctly and matches every other entry's convention; the suggested change would actually break the path. Thread left unresolved for human reviewer
• ✅ Pushed commit to openhands/add-github-actions-skill
• ✅ Re-review requested from all-hands-bot
• ✅ Summary comment posted on the PR

Changes Are Concise

Total diff: 2 files, 6 insertions, 5 deletions. Every change directly addresses a specific reviewer comment — no extraneous edits, no scope creep beyond what was requested.

PR: #56

[all-hands-bot]

✅ Review complete.

This review was performed through OpenHands Cloud Automation. You can log in and view the conversation here.

[all-hands-bot]

Good progress — the previous concerns about overly generic triggers, security clarity, the Docker prerequisite for , and the pitfall #5 wording have all been addressed. The path in is correct: means resolves to — the previous review on that point was incorrect.

One structural gap remains before this can merge: the directory is missing the plugin scaffolding that every other skill in the repository ships.

This review was generated by an AI agent (OpenHands) on behalf of the user through OpenHands Automation. View conversation

[juanmichelini]

@OpenHands please address this

[openhands-ai]

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

[juanmichelini]

Reviewer Concerns Addressed — Ready for Re-review

Two unresolved review threads remained on this PR. After verifying each against the actual repository contents, both turned out to be based on inaccurate premises and have been respectfully declined with evidence, then resolved.

#	Thread	Outcome
1	.plugin/marketplace.json source path should be ./skills/github-actions	Declined. metadata.pluginRoot: "./skills" is set globally; every other plugin uses ./<name> (e.g. ./github, ./github-pr-review, ./gitlab). Current ./github-actions is consistent and correct. Changing it would resolve to skills/skills/github-actions/ and break loading.
2	Missing plugin scaffolding (AGENTS.md/CLAUDE.md/GEMINI.md symlinks) — "every other skill ships them"	Declined. find skills/ -type f -o -type l confirms no skill in the repo has any such scaffolding — every one is just SKILL.md + README.md. The bot's rendered message also had blank placeholders where filenames were supposed to appear. Adding bespoke scaffolding here would make this the outlier, not bring it into line.

Both threads now have an inline reply explaining the reasoning and are marked resolved. No code changes were needed because the existing code already follows the established repository conventions.

Marking ready for re-review.

This comment was posted by an AI agent (OpenHands) on behalf of @juanmichelini.

[openhands-ai]

Summary

The comment @openhands please address this referred back to @juanmichelini's earlier request to address reviewer concerns and mark for re-review. I handled it without code changes because verification showed both remaining concerns were not actionable.

Request Completion Checklist

• ✅ Fetched all review threads via GraphQL and identified the two still-unresolved ones
• ✅ Verified each concern against the actual repo instead of acting on bot claims at face value
• ✅ Thread 1 — marketplace.json source path: Confirmed metadata.pluginRoot: "./skills" is set globally and every existing entry uses ./<name> form. ./github-actions is correct; changing it would resolve to skills/skills/github-actions/ and break loading. Posted reply with evidence and resolved the thread.
• ✅ Thread 2 — Missing plugin scaffolding: Confirmed via find skills/ that no skill in the repo has AGENTS.md/CLAUDE.md/GEMINI.md or symlinks — all skills are just SKILL.md + README.md. The bot's message also had blank placeholders where filenames should have appeared (hallucinated review). Posted reply with the file listing and resolved the thread.
• ✅ Posted a status comment on PR feat: add GitHub Actions skill for workflow creation and debugging #56 summarizing the resolution table
• ✅ Confirmed PR is in ready-for-review state
• ✅ AI disclosure included in all GitHub comments and replies

Concision

No code changes were made — both reviewer concerns were verifiably incorrect about the existing code, so following them would have broken loading (thread 1) or introduced an inconsistent outlier (thread 2). Per the repo's guidance on handling review comments, declining feedback that contradicts the project's conventions is acceptable when documented with reasoning, which is what I did.

PR: #56
Status comment: #56 (comment)

[openhands-ai]

@openhands-ai[bot] it looks like you haven't created an OpenHands account yet. Please sign up at OpenHands Cloud and try again.

[all-hands-bot]

✅ Review complete.

This review was performed through OpenHands Cloud Automation. You can log in and view the conversation here.

[all-hands-bot]

Good addition overall — GitHub Actions is a commonly requested skill and the content quality is high. The SKILL.md is concise with a clear focus, and README.md covers the depth needed for real-world debugging and workflow authoring. One blocking bug in marketplace.json must be fixed before merging; two other comments worth addressing are noted inline.

This review was generated by an AI agent (OpenHands) on behalf of the user through OpenHands Automation. View conversation

[juanmichelini]

@OpenHands please address reviewers concerns

[openhands-ai]

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

[juanmichelini]

Reviewer Concerns Addressed — Ready for Re-review

All three unresolved review threads from the latest bot review have been addressed in 1814e80 and the threads have been resolved.

#	Concern	Resolution
1	marketplace.json source path should be ./skills/github-actions	Declined — duplicate of a previously-resolved thread. metadata.pluginRoot is ./skills, every entry uses ./<name>, so ./github-actions is correct. Changing it would resolve to skills/skills/github-actions/ and break loading.
2	README.md L116: $? is always 0 because || true swallows the exit code	Fixed — removed the misleading echo "Last exit code: $?" and replaced ls -la dist/ || true with ls -la dist/ || echo "dist/ not found".
3	Add ci/cd and pipeline to triggers	Declined — these were explicitly removed in 888acf2 per an earlier review (ci/cd false-positives on Jenkins, GitLab CI, CircleCI; pipeline is even broader). Reintroducing them would directly contradict an already-accepted reviewer fix.

Net diff vs. last review: one-line bug fix to the debug example in README.md.

This comment was posted by an AI agent (OpenHands) on behalf of @juanmichelini.

[openhands-ai]

Summary

Addressed the "please address reviewers concerns" comment on PR #56 by critically evaluating each of the 3 unresolved review threads, fixing the legitimate one and pushing back on the two that contradicted prior accepted feedback or were technically incorrect.

Request Completion Checklist

• ✅ Fetched unresolved review threads via GraphQL — identified exactly 3 unresolved out of 26 total.
• ✅ Fix Add public skills from OpenHands repository #1 (real bug) — In skills/github-actions/README.md line 116, removed the misleading echo "Last exit code: $?" (always 0 because || true swallows the exit) and replaced ls -la dist/ || true with ls -la dist/ || echo "dist/ not found". Committed as 1814e80 and pushed.
• ✅ Declined Be explicit about what frontmatter #2 (incorrect suggestion) — Bot wanted marketplace.json source changed to ./skills/github-actions, but metadata.pluginRoot: "./skills" makes ./github-actions the correct value (every other plugin follows the same ./<name> convention). The proposed change would resolve to skills/skills/github-actions/ and break loading. This was a verbatim duplicate of an already-resolved thread.
• ✅ Declined Add gh run watch guidance for GitHub Actions monitoring #3 (contradicts prior accepted feedback) — Bot wanted ci/cd and pipeline added as triggers; these were explicitly removed in 888acf2 per an earlier reviewer because they false-positive on Jenkins, GitLab CI, CircleCI, and unrelated "pipeline" contexts. Reintroducing them would undo accepted feedback.
• ✅ Replied on all 3 threads with explanation/commit references and AI-disclosure footers, then resolved each via GraphQL.
• ✅ Posted a re-review summary comment on the PR.
• ✅ Verified 26/26 threads resolved, 0 unresolved.

Conciseness

The code change is a single-line fix in skills/github-actions/README.md (-2 / +1). No other files were touched; no extraneous edits were made. The other two reviewer points were addressed with thread replies only (no code changes), as their suggested edits were either incorrect or contradictory to prior accepted feedback — consistent with the "critically evaluate each review comment" guidance.

PR: #56