/composite-actions

name: composite-actions
description: Generate, review, secure, and test composite GitHub Actions following best practices — full repo scaffold, interview-driven generation, PR creation on existing repos, SHA pinning, secrets-as-inputs, job summaries, and actionlint validation.
argument-hint: "[generate|review|secure|test] [action.yml path or description]"
title: "Composite Actions Command"
sidebar_label: "composite-actions"
custom_edit_url: null

Composite Actions Command

Generate production-ready composite GitHub Actions or audit existing ones against best practices.

Activation

/platform-skills:composite-actions generate    # interview → full repo scaffold → optional PR
/platform-skills:composite-actions review      # audit an existing action.yml
/platform-skills:composite-actions secure      # harden an action in place
/platform-skills:composite-actions test        # generate a test workflow + act commands

---

Mode: generate

**Triggers:** generate, create, new action, scaffold, write action, build action

Run a guided interview, then generate a complete, production-ready composite action with all supporting files. If the target repo already exists, open a PR.

Interview — ask these questions in order

**Step 1 — Purpose** > What does this action do? Describe it in one or two sentences. > *(e.g. "Build a Docker image and push it to GHCR using OIDC", "Send a Slack notification with build status and PR link")*

Derive the action name from the description (kebab-case, under 30 chars). Confirm with the user.

**Step 2 — Repo destination** > Where should this action live? > 1. **New dedicated repo** — best for shared/public actions (Marketplace-publishable) > 2. **Existing repo** — internal action, placed under `.github/actions/<name>/` or `actions/<name>/`

If **existing repo**: ask for `owner/repo`. Verify it exists with `gh repo view owner/repo`. Then ask: > Which subdirectory? (default: `.github/actions/<action-name>`)

If the repo exists and is accessible, the action will be created on a branch and a PR will be opened automatically.

**Step 3 — Pinning strategy** > How should external actions be pinned? > 1. **SHA pinning** *(recommended — supply chain secure, immutable)* > 2. **Semver floating tag** *(e.g. `@v4` — easier to maintain, lower security)*

Resolve SHAs for all external actions used via `gh api repos/{owner}/{repo}/git/refs/tags/{tag}` if SHA pinning is chosen.

**Step 4 — Inputs** > What inputs does this action need? For each input, collect: > - Name (snake_case) > - Type: `string` / `boolean` / `choice` > - Required or optional? > - If optional: default value > - **Is it a secret?** (webhook URL, kubeconfig, token, password, API key)

List all inputs in a table and confirm before proceeding.

**Step 5 — Outputs** > What values should this action expose as outputs? For each: > - Name (snake_case) > - Description (one sentence)

**Step 6 — Cloud credentials** > Does this action need cloud credentials? > 1. AWS via OIDC (no long-lived keys — `id-token: write` required) > 2. Azure via OIDC > 3. Both > 4. Neither

**Step 7 — Notifications and PR comments** > Should this action send notifications or post PR comments? > 1. Slack webhook notification > 2. GitHub PR comment (requires `pull-requests: write`) > 3. Both > 4. Neither

**Step 8 — Job summary** > Should this action write a job summary visible in the Actions UI? > (Recommended: yes — adds a Markdown summary table with inputs, outputs, and status)

**Step 9 — Confirm and generate**

Show the user a summary of what will be generated:

Action: <name>
Description: <description>
Destination: <new repo | owner/repo/.github/actions/name>
Pinning: <SHA | semver>
Inputs: <count> (<N> are secrets)
Outputs: <count>
Cloud: <AWS OIDC | Azure OIDC | none>
Notifications: <Slack | PR comment | none>
Job summary: yes/no

Files to generate:
  action.yml
  README.md
  CHANGELOG.md
  .gitignore
  scripts/<script>.sh          (if logic warrants external scripts)
  .github/dependabot.yml
  .github/workflows/test-action.yml
  .github/workflows/release.yml

Ask for confirmation before generating.

Generated file contents

action.yml

Generate with:

• `name`, `description`, `author` filled from the interview
• All inputs from Step 4, with `description:` noting which are secrets
• All outputs from Step 5
• A validation step as the **first step** — validates all required inputs and enum constraints
• Log grouping (`::group::` / `::endgroup::`) around each logical phase
• All secrets passed through `env:` blocks — never `${{ inputs.secret }}` in `run:`
• `::add-mask::` on every secret value immediately after it is read
• `${{ github.action_path }}` for all file references
• `shell: bash` on every `run:` step
• All external `uses:` pinned per the chosen strategy
• `$GITHUB_STEP_SUMMARY` written in a final `if: always()` step
• `timeout-minutes:` on every network-bound step
• `branding:` block with an appropriate icon and color

README.md

Generate an awesome-docs-compatible README with:

# <action-name>

> <one-line description>

<!-- To add animated diagrams to this README, run: /platform-skills:awesome-docs generate -->

## Architecture

*(Shows where this action fits in a CI/CD pipeline — add diagram with `/platform-skills:awesome-docs generate`)*

## Quick start

\`\`\`yaml
- uses: <owner>/<repo>@v1
  with:
    <required inputs with example values>
\`\`\`

## Inputs

| Input | Type | Required | Secret | Default | Description |
|---|---|---|---|---|---|

## Outputs

| Output | Description |
|---|---|

## Variables and secrets

Explain which inputs are secrets and how to wire them from the caller:

\`\`\`yaml
- uses: <owner>/<repo>@v1
  with:
    image_name: my-service         # plain variable — safe to hardcode
    webhook_url: ${{ secrets.SLACK_WEBHOOK_URL }}   # secret — must come from secrets store
\`\`\`

## Permissions

\`\`\`yaml
permissions:
  <minimum required permissions>