Index of every page on this site: llms.txt
All skills
github avatar

/create-github-action-workflow-specification

@f10fdb8 official
by githubgithub/awesome-copilot41k stars
5,399
Run it yourself

Create a formal specification for an existing GitHub Actions CI/CD workflow, optimized for AI consumption and workflow maintenance.

Use this Skill: https://skilld.dev/gh/github/awesome-copilot/create-github-action-workflow-specification

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈44 tokens for metadata: the name and description. ≈1.9k when used: this file.

Description uses 2.2% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈177 characters, or 2.2%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Create GitHub Actions Workflow Specification

Create a comprehensive specification for the GitHub Actions workflow: ${input:WorkflowFile}.

This specification serves as a specification for the workflow's behavior, requirements, and constraints. It must be implementation-agnostic, focusing on what the workflow accomplishes rather than how it's implemented.

AI-Optimized Requirements

  • Token Efficiency: Use concise language without sacrificing clarity
  • Structured Data: Leverage tables, lists, and diagrams for dense information
  • Semantic Clarity: Use precise terminology consistently throughout
  • Implementation Abstraction: Avoid specific syntax, commands, or tool versions
  • Maintainability: Design for easy updates as workflow evolves

Specification Template

Save as: /spec/spec-process-cicd-[workflow-name].md

---
title: CI/CD Workflow Specification - [Workflow Name]
version: 1.0
date_created: [YYYY-MM-DD]
last_updated: [YYYY-MM-DD]
owner: DevOps Team
tags: [process, cicd, github-actions, automation, [domain-specific-tags]]
---

## Workflow Overview

**Purpose**: [One sentence describing workflow's primary goal]
**Trigger Events**: [List trigger conditions]
**Target Environments**: [Environment scope]

## Execution Flow Diagram

```mermaid
graph TD
    A[Trigger Event] --> B[Job 1]
    B --> C[Job 2]
    C --> D[Job 3]
    D --> E[End]
    
    B --> F[Parallel Job]
    F --> D
    
    style A fill:#e1f5fe
    style E fill:#e8f5e8

Jobs & Dependencies

Job Name Purpose Dependencies Execution Context
job-1 [Purpose] [Prerequisites] [Runner/Environment]
job-2 [Purpose] job-1 [Runner/Environment]

Requirements Matrix

Functional Requirements

ID Requirement Priority Acceptance Criteria
REQ-001 [Requirement] High [Testable criteria]
REQ-002 [Requirement] Medium [Testable criteria]

Security Requirements

ID Requirement Implementation Constraint
SEC-001 [Security requirement] [Constraint description]

Performance Requirements

ID Metric Target Measurement Method
PERF-001 [Metric] [Target value] [How measured]

Input/Output Contracts

Inputs

# Environment Variables
ENV_VAR_1: string  # Purpose: [description]
ENV_VAR_2: secret  # Purpose: [description]

# Repository Triggers
paths: [list of path filters]
branches: [list of branch patterns]

Outputs

# Job Outputs
job_1_output: string  # Description: [purpose]
build_artifact: file  # Description: [content type]

Secrets & Variables

Type Name Purpose Scope
Secret SECRET_1 [Purpose] Workflow
Variable VAR_1 [Purpose] Repository

Execution Constraints

Runtime Constraints

  • Timeout: [Maximum execution time]
  • Concurrency: [Parallel execution limits]
  • Resource Limits: [Memory/CPU constraints]

Environmental Constraints

  • Runner Requirements: [OS/hardware needs]
  • Network Access: [External connectivity needs]
  • Permissions: [Required access levels]

Error Handling Strategy

Error Type Response Recovery Action
Build Failure [Response] [Recovery steps]
Test Failure [Response] [Recovery steps]
Deployment Failure [Response] [Recovery steps]

Quality Gates

Gate Definitions

Gate Criteria Bypass Conditions
Code Quality [Standards] [When allowed]
Security Scan [Thresholds] [When allowed]
Test Coverage [Percentage] [When allowed]

Monitoring & Observability

Key Metrics

  • Success Rate: [Target percentage]
  • Execution Time: [Target duration]
  • Resource Usage: [Monitoring approach]

Alerting

Condition Severity Notification Target
[Condition] [Level] [Who/Where]

Integration Points

External Systems

System Integration Type Data Exchange SLA Requirements
[System] [Type] [Data format] [Requirements]

Dependent Workflows

Workflow Relationship Trigger Mechanism
[Workflow] [Type] [How triggered]

Compliance & Governance

Audit Requirements

  • Execution Logs: [Retention policy]
  • Approval Gates: [Required approvals]
  • Change Control: [Update process]

Security Controls

  • Access Control: [Permission model]
  • Secret Management: [Rotation policy]
  • Vulnerability Scanning: [Scan frequency]

Edge Cases & Exceptions

Scenario Matrix

Scenario Expected Behavior Validation Method
[Edge case] [Behavior] [How to verify]

Validation Criteria

Workflow Validation

  • VLD-001: [Validation rule]
  • VLD-002: [Validation rule]

Performance Benchmarks

  • PERF-001: [Benchmark criteria]
  • PERF-002: [Benchmark criteria]

Change Management

Update Process

  1. Specification Update: Modify this document first
  2. Review & Approval: [Approval process]
  3. Implementation: Apply changes to workflow
  4. Testing: [Validation approach]
  5. Deployment: [Release process]

Version History

Version Date Changes Author
1.0 [Date] Initial specification [Author]

Related Specifications

  • [Link to related workflow specs]
  • [Link to infrastructure specs]
  • [Link to deployment specs]

## Analysis Instructions

When analyzing the workflow file:

1. **Extract Core Purpose**: Identify the primary business objective
2. **Map Job Flow**: Create dependency graph showing execution order
3. **Identify Contracts**: Document inputs, outputs, and interfaces
4. **Capture Constraints**: Extract timeouts, permissions, and limits
5. **Define Quality Gates**: Identify validation and approval points
6. **Document Error Paths**: Map failure scenarios and recovery
7. **Abstract Implementation**: Focus on behavior, not syntax

## Mermaid Diagram Guidelines

### Flow Types
- **Sequential**: `A --> B --> C`
- **Parallel**: `A --> B & A --> C; B --> D & C --> D`
- **Conditional**: `A --> B{Decision}; B -->|Yes| C; B -->|No| D`

### Styling
```mermaid
style TriggerNode fill:#e1f5fe
style SuccessNode fill:#e8f5e8
style FailureNode fill:#ffebee
style ProcessNode fill:#f3e5f5

Complex Workflows

For workflows with 5+ jobs, use subgraphs:

graph TD
    subgraph "Build Phase"
        A[Lint] --> B[Test] --> C[Build]
    end
    subgraph "Deploy Phase"  
        D[Staging] --> E[Production]
    end
    C --> D

Token Optimization Strategies

  1. Use Tables: Dense information in structured format
  2. Abbreviate Consistently: Define once, use throughout
  3. Bullet Points: Avoid prose paragraphs
  4. Code Blocks: Structured data over narrative
  5. Cross-Reference: Link instead of repeat information

Focus on creating a specification that serves as both documentation and a template for workflow updates.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning2mo5 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    This skill is a documentation-focused tool that generates structured specifications for GitHub Actions workflows. It is safe to use because it only provides a template for text generation and does not include any executable code, network operations, or instructions to access sensitive data.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

  • Runlayer8mo

    1/1 file flagged

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at f10fdb8. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 9 months ago
  • Documentation
  • github-actions
  • ci-cd
  • workflow
  • specification
  • automation
  • schema

README badge

README badge for github/awesome-copilot/create-github-action-workflow-specification

Generates a formal specification document for an existing GitHub Actions workflow, abstracting implementation details to focus on behavior, requirements, and constraints. The specification is structured for AI consumption with tables, diagrams, and concise language, and targets teams that need maintainable, clear documentation of their CI/CD pipeline logic.

Generated from the current SKILL.md.

What does this skill actually output?
A structured markdown specification document that describes a GitHub Actions workflow's purpose, jobs, dependencies, requirements, and constraints in implementation-agnostic terms — designed for AI agents to understand and maintain the workflow.
Do I need to provide the workflow file as input?
Yes. The skill takes an existing GitHub Actions workflow file (YAML) as input and generates a formal specification from it; it does not create workflows from scratch.
Is this skill language or framework specific?
No. It works with any GitHub Actions workflow regardless of what the workflow builds, tests, or deploys — the output format is generic and tool-agnostic.
What is the primary use case for this skill?
Documenting CI/CD workflows in a format optimized for AI agent comprehension, enabling agents to understand workflow behavior, make changes, and maintain pipelines without decoding raw YAML.
Does this skill generate or update actual workflow files?
No. It generates a separate specification document only; it does not modify or generate the workflow YAML itself.

Generated from the current SKILL.md. These answers refresh after source changes.