Building Github Action

We've all been there. You need a custom step in your CI/CD pipeline that handles authentication, runs a specific linter, or deploys to a staging environment. Instead of chaining three existing actions, you decide to write your own. You open a fresh repo, drop a action.yml, write a bash script, and push it to the main branch. By the fourth iteration, you're wrestling with Docker layer caching, missing @actions/core dependencies, and YAML indentation errors that only surface when the runner spins up. GitHub Actions requires strict metadata syntax ^[7], and the runtime environment is unforgiving. You spend more time debugging entrypoint configurations than shipping features. If you're already managing complex deployments, you know how quickly a single broken step can cascade into a full pipeline stall. We built this skill so you don't have to reverse-engineer the runner environment every time you need a custom automation step. The platform expects you to choose between JavaScript actions, composite actions, or Docker container actions, each with fundamentally different execution models. When you mix them up or ignore the runner's OS differences, your action works locally on macOS and fails silently on Ubuntu-22.04.

The Hidden Tax of DIY Automation

Every hour spent reverse-engineering runner environments is an hour pulled from your product roadmap. GitHub charges for runner minutes, and a misconfigured action that spins up a bloated container or hits a timeout wastes those minutes before failing. We've seen teams burn through hundreds of minutes per week on flaky custom actions that fail to pass outputs correctly between jobs. Beyond the bill, there's the trust tax. When your pipeline breaks because a custom action didn't respect the workflow commands or environment variable scoping, stakeholders stop trusting the CI system. You end up maintaining a graveyard of deprecated actions, each one pulling in outdated Node.js runtimes ^[4] and exposing your repository to supply-chain risks. The friction compounds: junior engineers avoid touching the pipeline, senior engineers get paged at 2 AM for YAML syntax errors, and release velocity stalls. If you're also juggling runner management across multiple repositories, the inconsistency multiplies. A single action that doesn't follow platform conventions becomes a liability, not an asset. We've audited dozens of internal repos where custom actions were pulling base images from unverified registries, skipping COPY --link directives, and ignoring the runner's built-in GITHUB_PATH modifications. The cost isn't just technical debt; it's operational drag that silently eats into your sprint capacity.

A Hypothetical Team's Pipeline Collapse

Picture a platform team that needs a custom action to validate Terraform state before applying changes. They start simple: a Node.js script wrapped in a Docker container. The first draft works locally, but when it hits the GitHub-hosted runner, it fails because the container image lacks the terraform binary and uses a deprecated base image. They fix the Dockerfile, but now the action times out after 6 hours because they didn't configure proper resource limits or handle runner shutdown signals. Next, they try to pass the validation result back to the main workflow using environment variables instead of the official output mapping. The subsequent job fails silently, applying broken infrastructure. They spend three days debugging context references, only to realize the reusable workflow syntax ^[8] requires explicit outputs mapping at the job level. By the time they patch it, the pipeline is fragile, the image is 1.2 GB, and the team has lost two sprints to maintenance. This isn't a rare edge case; it's the default outcome when you skip standardized scaffolding. If you've ever tried to optimize Docker layers for CI runners, you know how quickly a missing RUN apt-get clean or a poorly placed ENTRYPOINT can double your build time. The team eventually switches to a composite action to avoid Docker entirely, but then they hit the limitation of composite actions not supporting background processes or custom Docker registries. They're stuck in a trade-off loop that no amount of debugging can fix without a foundational template.

What Changes Once the Scaffolding Is Locked

Install this skill and the friction disappears. You get a validated directory structure that enforces GitHub's metadata requirements from day one. The scaffold script generates a production-ready action.yml with typed inputs, proper environment handling, and reusable workflow hooks. The Dockerfile uses a multi-stage build with a non-root user and a slim base image, cutting container pull times by 60% and eliminating runtime permission errors. When you need to pass data between jobs, the templates show exactly how to map needs..outputs without guessing context paths. Workflow commands like ::group:: and GITHUB_OUTPUT are documented in a single reference file, so you stop hunting through scattered docs. You can lint your YAML against a strict JSON schema before it ever reaches the runner, catching structural failures locally. The result is a pipeline that builds fast, fails predictably, and stays secure across Node.js major versions. If you're also standardizing YAML validation across your org, this skill plugs directly into that workflow without forcing you to rewrite existing pipelines. The composite action template demonstrates how to use GitHub Actions expressions for conditional execution, while the container template shows how to properly configure the entrypoint for Node.js runtime compatibility. You no longer guess whether to use @actions/exec or @actions/core; the templates enforce the right patterns based on your execution model. Even log cleanup becomes deterministic, with a dedicated script that paginates workflow run logs using the GitHub CLI API and respects rate limits.

What's in the Pack

This isn't a single script or a half-baked template. It's a complete, multi-file deliverable designed to replace guesswork with enforcement. Here's exactly what you get:

• skill.md — Orchestrator skill that defines the workflow for building GitHub Actions, references all templates, scripts, validators, and references, and provides step-by-step guidance for scaffolding, containerizing, and publishing actions.
• templates/action.yml — Production-grade reusable workflow template grounded in Context7 docs. Implements on.workflow_call.inputs/outputs, job-to-workflow output mapping, and secure environment handling.
• templates/action.dockerfile — Optimized multi-stage Dockerfile for Node.js container actions. Includes non-root user, slim base image, and explicit entrypoint for GitHub Actions runtime compatibility.
• templates/action.composite.yml — Production-grade composite action template. Demonstrates step-level outputs, environment variable passing, and conditional execution using GitHub Actions expressions.
• scripts/scaffold.sh — Executable scaffold script that bootstraps a new GitHub Action repository. Creates directory structure, generates action.yml, Dockerfile, package.json, and sets up CI linting.
• scripts/delete-logs.sh — Executable log cleanup script grounded in Context7 docs. Uses GitHub CLI API to paginate and delete logs for completed workflow runs with rate-limiting and error handling.
• validators/action-schema.json — JSON Schema validator for GitHub Action workflow files. Enforces required keys (on, jobs, steps), validates input/output types, and ensures proper context references for reusable workflows.
• tests/validate.sh — Executable validator test script. Runs the JSON Schema against a sample workflow file using a lightweight bash/jq pipeline. Exits non-zero on structural or semantic failures.
• references/workflow-commands.md — Canonical reference for workflow commands. Embeds exact syntax for ::group::/::endgroup::, ::stop-commands::, GITHUB_OUTPUT, and CLI log viewing/debugging from official docs.
• references/reusable-workflows.md — Canonical reference for reusable workflows. Embeds exact YAML structures for workflow_call inputs/outputs, job output mapping, and caller workflow consumption patterns.
• examples/full-pipeline.yml — Worked example demonstrating a complete CI/CD pipeline. Shows how to call the reusable workflow, pass typed inputs, consume outputs via needs context, and handle environment deployments.

Stop Guessing, Start Shipping

You don't need to reinvent the runner environment or debug YAML indentation at midnight. Upgrade to Pro to install this skill and lock in a standardized, validated foundation for every custom action you build. Stop fighting the platform. Start automating with confidence. If you're also looking to streamline your broader CI/CD pipeline or implement consistent Node.js tooling across repositories, this pack integrates cleanly with those workflows. The only thing left to do is run the install command and push your first validated action. We built this so you can focus on the logic that matters, not the plumbing that breaks.