@hybridlabor-api/aos 4.8.0 → 4.10.0

package/skills/global_config/github-actions-generator/SKILL.md

@@ -0,0 +1,353 @@
+---
+name: github-actions-generator
+description: Create, generate, or scaffold GitHub Actions workflows, action.yml, or .github/workflows CI/CD pipelines.
+category: engineering-method
+source: cc-devops-skills
+date_added: "2026-09-25"
+---
+
+# GitHub Actions Generator
+
+Generate production-ready GitHub Actions workflows and custom actions following current best practices, security standards, and naming conventions. All generated resources are automatically validated using the github-actions-validator skill.
+
+## Quick Reference
+
+| Capability | When to Use | Reference |
+|------------|-------------|-----------|
+| Workflows | CI/CD, automation, testing | `references/best-practices.md` |
+| Composite Actions | Reusable step combinations | `references/custom-actions.md` |
+| Docker Actions | Custom environments/tools | `references/custom-actions.md` |
+| JavaScript Actions | API interactions, complex logic | `references/custom-actions.md` |
+| Reusable Workflows | Shared patterns across repos | `references/advanced-triggers.md` |
+| Security Scanning | Dependency review, SBOM | `references/best-practices.md` |
+| Modern Features | Summaries, environments | `references/modern-features.md` |
+
+---
+
+## Trigger Decision Tree
+
+Route every request through this decision tree before reading references or generating files:
+
+1. If the user asks for `.github/workflows/*.yml` CI/CD automation, choose **Workflow Generation**.
+2. If the user asks for `action.yml` or a reusable step package, choose **Custom Action Generation**.
+3. If the user asks for `workflow_call` or shared pipelines across repositories, choose **Reusable Workflow Generation**.
+4. If the request includes security-only scanning (dependency review, SBOM, CodeQL), stay on **Workflow Generation** with the security pattern.
+5. If intent is ambiguous, ask one disambiguation question: "Do you want a workflow, a custom action, or a reusable workflow?"
+
+## Progressive Disclosure Route
+
+Load only what is needed for the selected route, in this order:
+
+| Route | Load First (required) | Load Next (only if needed) | Primary Template |
+|-------|------------------------|------------------------------|------------------|
+| Workflow Generation | `references/best-practices.md` | `references/common-actions.md`, `references/expressions-and-contexts.md`, `references/modern-features.md` | `assets/templates/workflow/basic_workflow.yml` |
+| Custom Action Generation | `references/custom-actions.md` | `references/best-practices.md` | `assets/templates/action/composite/action.yml`, `assets/templates/action/docker/`, `assets/templates/action/javascript/` |
+| Reusable Workflow Generation | `references/advanced-triggers.md` | `references/best-practices.md`, `references/common-actions.md` | `assets/templates/workflow/reusable_workflow.yml` |
+
+If a required reference/template is unavailable, continue with the closest available reference and report the fallback explicitly in output.
+
+---
+
+## Core Capabilities
+
+### 1. Generate Workflows
+
+**Triggers:** "Create a workflow for...", "Build a CI/CD pipeline..."
+
+**Process:**
+1. Understand requirements (triggers, runners, dependencies)
+2. Define trust boundaries (internal branches vs fork PRs vs external triggers)
+3. Set default `permissions` to read-only, then elevate only per job when required
+4. Reference `references/best-practices.md` for patterns
+5. Reference `references/common-actions.md` for action versions
+6. Generate workflow with:
+   - Semantic names, pinned actions (SHA), explicit permissions
+   - Concurrency controls, caching, matrix strategies
+   - Fork-safe PR handling (no secrets in untrusted contexts)
+7. **Validate** with github-actions-validator skill
+8. Fix issues and re-validate if needed
+
+**Minimal Example:**
+```yaml
+name: CI Pipeline
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
+        with:
+          node-version: '24'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm test
+```
+
+**Untrusted PR Guardrail (required for secret-using jobs):**
+```yaml
+jobs:
+  deploy:
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+```
+
+### 2. Generate Custom Actions
+
+**Triggers:** "Create a composite action...", "Build a Docker action...", "Create a JavaScript action..."
+
+**Types:**
+- **Composite:** Combine multiple steps → Fast startup
+- **Docker:** Custom environment/tools → Isolated
+- **JavaScript:** API access, complex logic → Fastest
+
+**Process:**
+1. Use templates from `assets/templates/action/`
+2. Follow structure in `references/custom-actions.md`
+3. Include branding, inputs/outputs, documentation
+4. **Validate** with github-actions-validator skill
+
+See `references/custom-actions.md` for:
+- Action metadata and branding
+- Directory structure patterns
+- Versioning and release workflows
+
+### 3. Generate Reusable Workflows
+
+**Triggers:** "Create a reusable workflow...", "Make this workflow callable..."
+
+**Key Elements:**
+- `workflow_call` trigger with typed inputs
+- Explicit secrets (avoid `secrets: inherit`)
+- Explicit trusted-caller expectations (document org/repo boundaries)
+- Outputs mapped from job outputs
+- Minimal permissions
+
+```yaml
+on:
+  workflow_call:
+    inputs:
+      environment:
+        required: true
+        type: string
+    secrets:
+      deploy-token:
+        required: false
+    outputs:
+      result:
+        value: ${{ jobs.build.outputs.result }}
+```
+
+When secrets are required, pass only the exact secret names needed and prefer environment protection rules for deployment stages.
+
+See `references/advanced-triggers.md` for complete patterns.
+
+### 4. Generate Security Workflows
+
+**Triggers:** "Add security scanning...", "Add dependency review...", "Generate SBOM..."
+
+**Components:**
+- **Dependency Review:** `actions/dependency-review-action@v4`
+- **SBOM Attestations:** `actions/attest-sbom@v2`
+- **CodeQL Analysis:** `github/codeql-action`
+
+**Permission Model:**
+Use a read-only workflow-level baseline, then elevate only in the security job that requires write scopes.
+```yaml
+permissions:
+  contents: read
+
+jobs:
+  security-scan:
+    permissions:
+      contents: read
+      security-events: write  # For CodeQL
+      id-token: write         # For attestations
+      attestations: write     # For attestations
+```
+
+See `references/best-practices.md` section on security.
+
+### 5. Modern Features
+
+**Triggers:** "Add job summaries...", "Use environments...", "Run in container..."
+
+See `references/modern-features.md` for:
+- Job summaries (`$GITHUB_STEP_SUMMARY`)
+- Deployment environments with approvals
+- Container jobs with services
+- Workflow annotations
+
+### 6. Third-Party Action Documentation and Citation
+
+When using third-party actions (any `uses:` entry not in the same repository):
+
+1. **Search for documentation:**
+   ```
+   "[owner/repo] [version] github action documentation"
+   ```
+
+2. **Or use Context7 MCP:**
+   - `mcp__context7__resolve-library-id` to find action
+   - `mcp__context7__query-docs` for documentation
+
+3. **Pin to SHA with version comment:**
+   ```yaml
+   - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+   ```
+
+4. **Cite source and version in the response:**
+   - Action source (repository URL)
+   - Version source (release/tag/changelog URL)
+   - Selected commit SHA and human-readable version
+   - Access date for the source used
+
+See `references/common-actions.md` for pre-verified action versions.
+
+---
+
+## Validation Workflow
+
+**CRITICAL:** Every generated resource MUST be validated.
+
+1. Generate workflow/action file
+2. Invoke `github-actions-validator` skill
+3. If errors: fix and re-validate
+4. If success: present with usage instructions
+
+**Skip validation only for:**
+- Partial code snippets
+- Documentation examples
+- User explicitly requests skip
+
+## Fallback Behavior (Tooling and Environment Constraints)
+
+If required tooling or network access is unavailable, use this deterministic fallback order:
+
+1. If `github-actions-validator` is unavailable, run local fallback checks:
+   - `actionlint` (if installed)
+   - `yamllint` (if installed)
+   - manual YAML/schema review with a clear "not tool-validated" note
+2. If Context7 or internet access is unavailable:
+   - use `references/common-actions.md` for known action versions
+   - state that external version verification could not be completed
+3. If a template path is missing:
+   - generate from the closest template pattern in `assets/templates/`
+   - document which template was substituted
+
+Fallback usage must always be reported in the final output.
+
+---
+
+## Mandatory Standards
+
+All generated resources must follow:
+
+| Standard | Implementation |
+|----------|---------------|
+| **Security** | Pin to SHA, minimal permissions, mask secrets |
+| **Performance** | Caching, concurrency, shallow checkout |
+| **Naming** | Descriptive names, lowercase-hyphen files |
+| **Error Handling** | Timeouts, cleanup with `if: always()` |
+
+See `references/best-practices.md` for complete guidelines.
+
+---
+
+## Resources
+
+### Reference Documents
+
+| Document | Content | When to Use |
+|----------|---------|-------------|
+| `references/best-practices.md` | Security, performance, patterns | Every workflow |
+| `references/common-actions.md` | Action versions, inputs, outputs | Public action usage |
+| `references/expressions-and-contexts.md` | `${{ }}` syntax, contexts, functions | Complex conditionals |
+| `references/advanced-triggers.md` | workflow_run, dispatch, ChatOps | Workflow orchestration |
+| `references/custom-actions.md` | Metadata, structure, versioning | Custom action creation |
+| `references/modern-features.md` | Summaries, environments, containers | Enhanced workflows |
+
+### Templates
+
+| Template | Location |
+|----------|----------|
+| Basic Workflow | `assets/templates/workflow/basic_workflow.yml` |
+| Reusable Workflow | `assets/templates/workflow/reusable_workflow.yml` |
+| Composite Action | `assets/templates/action/composite/action.yml` |
+| Docker Action | `assets/templates/action/docker/` |
+| JavaScript Action | `assets/templates/action/javascript/` |
+
+---
+
+## Common Patterns
+
+### Matrix Testing
+```yaml
+strategy:
+  matrix:
+    os: [ubuntu-latest, windows-latest]
+    node: [18, 20, 22]
+  fail-fast: false
+```
+
+### Conditional Deployment
+```yaml
+deploy:
+  if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+```
+
+### Artifact Sharing
+```yaml
+# Upload
+- uses: actions/upload-artifact@5d5d22a31266ced268874388b861e4b58bb5c2f3 # v4.3.1
+  with:
+    name: build-${{ github.sha }}
+    path: dist/
+
+# Download (in dependent job)
+- uses: actions/download-artifact@c850b930e6ba138125429b7e5c93fc707a7f8427 # v4.1.4
+  with:
+    name: build-${{ github.sha }}
+```
+
+### Third-Party Action Citation Block
+```text
+Third-party action citations:
+- actions/checkout: https://github.com/actions/checkout (version: v6.0.2, sha: de0fac2e4500dabe0009e67214ff5f5447ce83dd, accessed: 2026-02-28)
+```
+
+---
+
+## Done Criteria
+
+The task is complete only when all checks below pass:
+
+1. The request route was selected using the trigger decision tree.
+2. Only the minimum required references/templates were loaded first.
+3. Every third-party action is pinned to a commit SHA and has source/version citation.
+4. Validation was run, or a skip exception/fallback path was explicitly documented.
+5. Output includes assumptions, security-sensitive decisions (permissions/secrets), and generated file paths.
+
+---
+
+## Workflow Summary
+
+1. **Route** the request using the trigger decision tree
+2. **Load** the minimum references/templates for that route
+3. **Generate** using mandatory security and naming standards
+4. **Cite** and pin third-party actions (source, version, SHA)
+5. **Validate** with `github-actions-validator` (or documented fallback)
+6. **Fix and re-validate** until clean
+7. **Present** validated output with citations, assumptions, and file paths

package/skills/global_config/github-actions-generator/assets/templates/action/composite/action.yml

@@ -0,0 +1,82 @@
+name: '[ACTION_NAME]'
+description: '[ACTION_DESCRIPTION]'
+author: '[AUTHOR_NAME]'
+
+# Define inputs that users can provide
+inputs:
+  [input-name]:
+    description: '[INPUT_DESCRIPTION]'
+    required: [true/false]
+    default: '[DEFAULT_VALUE]'
+
+  [input-name-2]:
+    description: '[INPUT_DESCRIPTION]'
+    required: [true/false]
+
+# Define outputs that the action produces
+outputs:
+  [output-name]:
+    description: '[OUTPUT_DESCRIPTION]'
+    value: ${{ steps.[step-id].outputs.[output-name] }}
+
+  [output-name-2]:
+    description: '[OUTPUT_DESCRIPTION]'
+    value: ${{ steps.[step-id].outputs.[output-name-2] }}
+
+# Branding (optional - for GitHub Marketplace)
+branding:
+  icon: '[ICON_NAME]'  # Feather icon name
+  color: '[COLOR]'     # white, yellow, blue, green, orange, red, purple, gray-dark
+
+runs:
+  using: 'composite'
+  steps:
+    # Step 1: Validation
+    - name: Validate inputs
+      shell: bash
+      run: |
+        if [ -z "${{ inputs.[input-name] }}" ]; then
+          echo "::error::Input [input-name] is required"
+          exit 1
+        fi
+        echo "✅ Inputs validated"
+
+    # Step 2: Setup
+    - name: [SETUP_STEP_NAME]
+      uses: "[SETUP_ACTION]@[SHA]" # [VERSION]
+      with:
+        [SETUP_INPUT]: ${{ inputs.[input-name] }}
+
+    # Step 3: Main logic
+    - name: [MAIN_STEP_NAME]
+      id: [step-id]
+      shell: bash
+      env:
+        INPUT_VALUE: ${{ inputs.[input-name] }}
+      run: |
+        echo "::group::Running [MAIN_STEP_NAME]"
+
+        # Main action logic here
+        [MAIN_COMMAND]
+
+        # Set outputs
+        echo "[output-name]=[OUTPUT_VALUE]" >> $GITHUB_OUTPUT
+        echo "[output-name-2]=[OUTPUT_VALUE_2]" >> $GITHUB_OUTPUT
+
+        echo "::endgroup::"
+
+    # Step 4: Post-processing (optional)
+    - name: Post-processing
+      if: success()
+      shell: bash
+      run: |
+        echo "✅ Action completed successfully"
+        echo "Output: ${{ steps.[step-id].outputs.[output-name] }}"
+
+    # Step 5: Cleanup (optional)
+    - name: Cleanup
+      if: always()
+      shell: bash
+      run: |
+        # Cleanup logic here
+        echo "Cleanup completed"

package/skills/global_config/github-actions-generator/assets/templates/action/docker/Dockerfile

@@ -0,0 +1,25 @@
+# Base image
+FROM [BASE_IMAGE]:[TAG]
+
+# Install required tools with minimal packages, then clean package caches
+RUN [PACKAGE_MANAGER] update && \
+    [PACKAGE_MANAGER] install [PACKAGE_INSTALL_FLAGS] \
+    [PACKAGE_1] \
+    [PACKAGE_2] \
+    && [CLEANUP_COMMAND]
+
+# Set working directory
+WORKDIR /app
+
+# Copy application files
+COPY entrypoint.sh /entrypoint.sh
+
+# Make entrypoint executable
+RUN chmod +x /entrypoint.sh
+
+# Create and switch to a non-root runtime user (replace placeholders per base image)
+RUN [CREATE_NON_ROOT_USER_COMMAND]
+USER [RUNTIME_USER]
+
+# Set entrypoint
+ENTRYPOINT ["/entrypoint.sh"]

package/skills/global_config/github-actions-generator/assets/templates/action/docker/action.yml

@@ -0,0 +1,42 @@
+name: '[ACTION_NAME]'
+description: '[ACTION_DESCRIPTION]'
+author: '[AUTHOR_NAME]'
+
+# Define inputs that users can provide
+inputs:
+  [input-name]:
+    description: '[INPUT_DESCRIPTION]'
+    required: [true/false]
+    default: '[DEFAULT_VALUE]'
+
+  [input-name-2]:
+    description: '[INPUT_DESCRIPTION]'
+    required: [true/false]
+
+# Define outputs that the action produces
+outputs:
+  [output-name]:
+    description: '[OUTPUT_DESCRIPTION]'
+
+# Branding (optional - for GitHub Marketplace)
+branding:
+  icon: '[ICON_NAME]'  # Feather icon name
+  color: '[COLOR]'     # white, yellow, blue, green, orange, red, purple, gray-dark
+
+runs:
+  using: 'docker'
+  image: 'Dockerfile'
+  # Optional: Use pre-built image instead
+  # image: 'docker://[REGISTRY]/[IMAGE]:[TAG]'
+
+  # Arguments passed to container entrypoint
+  args:
+    - ${{ inputs.[input-name] }}
+    - ${{ inputs.[input-name-2] }}
+
+  # Environment variables
+  env:
+    [ENV_VAR]: ${{ inputs.[input-name] }}
+
+  # Optional: Override entrypoint
+  # entrypoint: '/entrypoint.sh'

package/skills/global_config/github-actions-generator/assets/templates/action/docker/entrypoint.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+set -e
+
+# Action entrypoint script
+# Arguments are passed from action.yml
+
+[INPUT_1]="$1"
+[INPUT_2]="$2"
+
+# Validate inputs
+if [ -z "$[INPUT_1]" ]; then
+  echo "::error::[INPUT_1] is required"
+  exit 1
+fi
+
+echo "::group::Running [ACTION_NAME]"
+echo "Input 1: $[INPUT_1]"
+echo "Input 2: $[INPUT_2]"
+
+# Main action logic
+[MAIN_COMMAND]
+
+# Set outputs
+echo "[output-name]=[OUTPUT_VALUE]" >> "$GITHUB_OUTPUT"
+
+echo "::endgroup::"
+echo "✅ Action completed successfully"

package/skills/global_config/github-actions-generator/assets/templates/action/javascript/action.yml

@@ -0,0 +1,33 @@
+name: '[ACTION_NAME]'
+description: '[ACTION_DESCRIPTION]'
+author: '[AUTHOR_NAME]'
+
+# Define inputs that users can provide
+inputs:
+  github-token:
+    description: 'GitHub token for API access'
+    required: false
+    default: ${{ github.token }}
+
+  [input-name]:
+    description: '[INPUT_DESCRIPTION]'
+    required: [true/false]
+    default: '[DEFAULT_VALUE]'
+
+# Define outputs that the action produces
+outputs:
+  [output-name]:
+    description: '[OUTPUT_DESCRIPTION]'
+
+# Branding (optional - for GitHub Marketplace)
+branding:
+  icon: '[ICON_NAME]'  # Feather icon name
+  color: '[COLOR]'     # white, yellow, blue, green, orange, red, purple, gray-dark
+
+runs:
+  using: 'node20'
+  main: 'dist/index.js'
+  # Optional: Run code before action
+  # pre: 'dist/pre.js'
+  # Optional: Run code after action
+  # post: 'dist/post.js'

package/skills/global_config/github-actions-generator/assets/templates/action/javascript/index.js

@@ -0,0 +1,50 @@
+const core = require('@actions/core');
+const github = require('@actions/github');
+
+async function run() {
+  try {
+    // Get inputs
+    const githubToken = core.getInput('github-token');
+    const inputName = core.getInput('[input-name]', { required: true });
+
+    // Log inputs (mask sensitive data)
+    core.info(`Input: ${inputName}`);
+
+    // Create GitHub client
+    const octokit = github.getOctokit(githubToken);
+
+    // Get context information
+    const context = github.context;
+    core.info(`Repository: ${context.repo.owner}/${context.repo.repo}`);
+    core.info(`Event: ${context.eventName}`);
+
+    // Main action logic
+    core.startGroup('Running [ACTION_NAME]');
+
+    // Example: Get repository information
+    const { data: repo } = await octokit.rest.repos.get({
+      owner: context.repo.owner,
+      repo: context.repo.repo,
+    });
+
+    core.info(`Repository stars: ${repo.stargazers_count}`);
+
+    // [ADD YOUR LOGIC HERE]
+
+    core.endGroup();
+
+    // Set outputs
+    core.setOutput('[output-name]', '[OUTPUT_VALUE]');
+
+    // Success
+    core.info('✅ Action completed successfully');
+  } catch (error) {
+    // Handle errors
+    core.setFailed(`Action failed: ${error.message}`);
+    if (error.stack) {
+      core.debug(error.stack);
+    }
+  }
+}
+
+run();

package/skills/global_config/github-actions-generator/assets/templates/action/javascript/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "[ACTION_NAME]",
+  "version": "1.0.0",
+  "description": "[ACTION_DESCRIPTION]",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "ncc build index.js -o dist --source-map --license licenses.txt",
+    "test": "jest",
+    "lint": "eslint ."
+  },
+  "keywords": [
+    "github-actions",
+    "[KEYWORD_1]",
+    "[KEYWORD_2]"
+  ],
+  "author": "[AUTHOR_NAME]",
+  "license": "MIT",
+  "dependencies": {
+    "@actions/core": "^1.10.1",
+    "@actions/github": "^6.0.0"
+  },
+  "devDependencies": {
+    "@vercel/ncc": "^0.38.1",
+    "eslint": "^8.57.0",
+    "jest": "^29.7.0"
+  }
+}