feat: add GitHub Actions skill for workflow creation and debugging by juanmichelini · Pull Request #56 · OpenHands/extensions

juanmichelini · 2026-02-18T21:03:37Z

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

- Add comprehensive GitHub Actions skill with SKILL.md - Include practical examples for testing, debugging, and best practices - Cover common pitfalls like action deployment requirements and permissions - Add README.md with detailed scenarios and use cases - Register skill in marketplace.json Closes #55 Co-authored-by: openhands <openhands@all-hands.dev>

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.

@juanmichelini

- Consolidated repetitive content into a single 'Critical Rules' section - Clarified that debug steps should be used for NEW actions OR tricky issues, not always - Removed redundant explanations scattered throughout the document - Updated both SKILL.md and README.md for consistency Addresses feedback from @juanmichelini

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 · 2026-02-23T16:36:28Z

@OpenHands address the reviewers points

openhands-ai · 2026-02-23T16:36:49Z

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

- Reduced SKILL.md from 526 to 81 lines (within 50-80 line target) - Kept frontmatter and Critical Rules section (got positive review feedback) - Added concise Quick Patterns section showing 3 action types - Condensed Key Gotchas to 4 most critical issues - Moved detailed content to README.md (examples, debugging, testing, best practices) - Eliminated redundancy between SKILL.md and README.md - README.md now contains comprehensive detailed reference material Addresses reviewer feedback: - Progressive disclosure architecture now properly implemented - SKILL.md is a decision guide, not a reference manual - Reduced context token usage for skill loading - No repeated content between files

openhands-ai · 2026-02-23T16:42:52Z

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 · 2026-03-03T00:54:31Z

@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 · 2026-03-03T00:54:52Z

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

- Remove Quick Patterns section (syntax examples moved to README) - Add Testing & Monitoring Strategy focused on effectiveness - Emphasize cost awareness (CI minutes consumption) - Add practical debugging workflow with gh CLI commands - Focus on reading logs and understanding actual behavior vs guessing - Include visibility best practices (debug steps for inputs/outputs) Addresses reviewer feedback to make skill about SWE effectiveness, not syntax.

openhands-ai · 2026-03-03T00:57:01Z

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.

Removed detailed sections on key concepts, scenarios, common pitfalls, advanced patterns, and best practices from the GitHub Actions README.

all-hands-bot

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

juanmichelini · 2026-05-27T22:28:21Z

@OpenHands address reviewrs conerns and mark for rereview

openhands-ai · 2026-05-27T22:28:34Z

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

- Fix grammar: 'should tested' -> 'should be tested' - Move detailed gh CLI commands, debugging workflow, and YAML debug-step examples from SKILL.md to README.md (progressive disclosure - SKILL.md is now 43 lines) - Keep core principles (cost awareness, monitor, read logs, print actual values, local-first, smallest reproduction) in SKILL.md as a concise decision guide - Expand README.md with full debugging loop, gh run/checks commands, log-reading patterns, act usage and caveats, visibility/debug-step example with runner.debug gating, cost-awareness practices, and pitfalls reference Co-authored-by: openhands <openhands@all-hands.dev>

juanmichelini · 2026-05-27T22:31:52Z

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 · 2026-05-27T22:32:25Z

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 · 2026-05-27T22:33:11Z

✅ 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

all-hands-bot · 2026-05-27T22:36:26Z

        },
+        {
+            "name": "github-actions",
+            "source": "./github-actions",


🔴 Critical: wrong source path — will break skill loading.

Every other entry in this file uses ./skills/<name> (e.g. ./skills/agent-creator, ./skills/github-pr-review). This entry uses ./github-actions, which resolves to a non-existent .plugin/github-actions/ directory.

Suggested change

"source": "./github-actions",

"source": "./skills/github-actions",

Respectfully pushing back on this one. The file declares metadata.pluginRoot: "./skills" at the top, and every existing entry uses ./<name> (e.g. ./github, ./github-pr-review, ./gitlab, ./agent-creator). They all resolve to ./skills/<name> via pluginRoot. Changing this entry to ./skills/github-actions would actually break it — it would resolve to ./skills/skills/github-actions, inconsistent with every other plugin in the file.

The current ./github-actions is consistent with the existing convention. Happy to change it if the convention itself is being updated, but a one-off change here would be the outlier.

juanmichelini · 2026-05-27T22:55:35Z

@OpenHands address reviewrs concerns and mark for rereview

openhands-ai · 2026-05-27T22:55:48Z

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

…g, docs - SKILL.md: replace overly generic triggers (workflow, ci/cd) with GitHub Actions-specific ones to prevent false positives - SKILL.md: clarify pull_request_target risk (RCE if checking out fork code) - README.md: note Docker prerequisite for act - README.md: correct pitfall #5 - it's non-pull_request triggers (schedule/workflow_dispatch) that need to be on default branch, not pull_request workflows Co-authored-by: openhands <openhands@all-hands.dev>

juanmichelini · 2026-05-27T22:58:09Z

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 · 2026-05-27T22:58:40Z

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 · 2026-05-27T22:59:10Z

✅ 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

all-hands-bot · 2026-05-27T23:02:51Z

@@ -0,0 +1,189 @@
+# GitHub Actions Skill


🟠 Important: missing plugin scaffolding — skill won't load in Claude/Codex environments.

Every skill in this repository ships three additional items alongside and . The skill is the only one missing them.

Compare with any peer skill (, , ):

The and files are symlinks pointing to . They let Claude and Codex discover the skill automatically when the repo is cloned locally.

The should contain:

Without this scaffolding the skill loads fine in the OpenHands marketplace, but is invisible to Claude and Codex environments that rely on those dotfile symlinks for auto-discovery.

openhands-ai Bot mentioned this pull request Feb 18, 2026

feat: skill for github actions #55

Open

all-hands-bot reviewed Feb 18, 2026

View reviewed changes

Comment thread skills/github-actions/SKILL.md Outdated

Comment thread skills/github-actions/SKILL.md Outdated

Comment thread skills/github-actions/SKILL.md Outdated

Comment thread skills/github-actions/README.md

Comment thread skills/github-actions/SKILL.md Outdated

juanmichelini marked this pull request as draft February 18, 2026 21:22

juanmichelini requested a review from all-hands-bot February 20, 2026 17:27

all-hands-bot reviewed Feb 20, 2026

View reviewed changes

Comment thread skills/github-actions/SKILL.md

Comment thread skills/github-actions/SKILL.md Outdated

Comment thread skills/github-actions/SKILL.md Outdated

Comment thread skills/github-actions/SKILL.md Outdated

Comment thread skills/github-actions/README.md Outdated

juanmichelini marked this pull request as ready for review March 4, 2026 00:14

all-hands-bot reviewed Mar 4, 2026

View reviewed changes

Comment thread skills/github-actions/SKILL.md Outdated

Comment thread skills/github-actions/README.md Outdated

Comment thread skills/github-actions/SKILL.md

Comment thread skills/github-actions/SKILL.md

juanmichelini added 2 commits March 3, 2026 21:19

Removed red herrings

e26df73

Refactor GitHub Actions README to remove excess content

11f1459

Removed detailed sections on key concepts, scenarios, common pitfalls, advanced patterns, and best practices from the GitHub Actions README.

juanmichelini requested a review from all-hands-bot March 4, 2026 00:22

all-hands-bot reviewed Mar 4, 2026

View reviewed changes

Comment thread skills/github-actions/SKILL.md Outdated

Comment thread skills/github-actions/SKILL.md Outdated

Comment thread skills/github-actions/README.md

juanmichelini marked this pull request as draft April 1, 2026 20:05

juanmichelini requested a review from all-hands-bot May 27, 2026 22:31

all-hands-bot requested changes May 27, 2026

View reviewed changes

juanmichelini requested a review from all-hands-bot May 27, 2026 22:58

all-hands-bot requested changes May 27, 2026

View reviewed changes

	"source": "./github-actions",
	"source": "./skills/github-actions",

Conversation

juanmichelini commented Feb 18, 2026

Description

What's Included

SKILL.md

README.md

marketplace.json

Key Features

Testing

Related Issue

Uh oh!

all-hands-bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

all-hands-bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

juanmichelini commented Feb 23, 2026

Uh oh!

openhands-ai Bot commented Feb 23, 2026

Uh oh!

openhands-ai Bot commented Feb 23, 2026

Summary of Changes Made

✅ Request Completion Checklist

Changes Made (2 files modified)

Validation

Uh oh!

juanmichelini commented Mar 3, 2026

Uh oh!

openhands-ai Bot commented Mar 3, 2026

Uh oh!

openhands-ai Bot commented Mar 3, 2026

Summary of Changes

✅ Request Completion Checklist

Changes Are Concise

What Changed

Uh oh!

all-hands-bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

all-hands-bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

juanmichelini commented May 27, 2026

Uh oh!

openhands-ai Bot commented May 27, 2026

Uh oh!

juanmichelini commented May 27, 2026

Reviewer Concerns Addressed — Ready for Re-review

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

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

Verification

Uh oh!

openhands-ai Bot commented May 27, 2026

Summary

Request Completion Checklist

Conciseness

Uh oh!

all-hands-bot commented May 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

all-hands-bot left a comment

Choose a reason for hiding this comment

all-hands-bot commented May 27, 2026 •

edited

Loading

all-hands-bot commented May 27, 2026 •

edited

Loading