Create Github Action Workflow Specification
Document an existing GitHub Actions workflow as a maintainable, AI-readable spec without tying it to transient YAML syntax.
Overview
Create GitHub Action Workflow Specification is an agent skill for the Ship phase that documents an existing GitHub Actions workflow as an implementation-agnostic CI/CD specification for AI consumption.
Install
npx skills add https://github.com/github/awesome-copilot --skill create-github-action-workflow-specificationWhat is this skill?
- Implementation-agnostic spec focused on what the workflow does, not YAML trivia
- AI-optimized structure: tables, lists, diagrams, token-efficient prose
- Template with metadata front matter, overview, triggers, and execution flow
- Input-driven target: `${input:WorkflowFile}` workflow file
- Save path pattern: `/spec/spec-process-cicd-[workflow-name].md`
- Specification template includes Workflow Overview, Trigger Events, Target Environments, and Execution Flow Diagram secti
Adoption & trust: 9.4k installs on skills.sh; 34.6k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your CI/CD YAML works but nobody—including your agent—has a durable, semantic description of triggers, flow, and constraints.
Who is it for?
Indie repos with non-trivial GitHub Actions that you want to hand to Claude, Cursor, or Codex for safe maintenance.
Skip if: Greenfield workflow authoring from scratch when no workflow file exists yet—use a generator skill first, then spec it.
When should I use this skill?
You need a formal, AI-optimized specification for an existing GitHub Actions workflow file.
What do I get? / Deliverables
You get a structured `spec-process-cicd-[workflow-name].md` file agents can use to reason about pipeline changes without re-parsing brittle workflow syntax.
- Markdown CI/CD spec at `/spec/spec-process-cicd-[workflow-name].md`
Recommended Skills
Journey fit
How it compares
Use for human- and agent-readable process specs, not as a drop-in MCP server or workflow runner.
Common Questions / FAQ
Who is create-github-action-workflow-specification for?
Solo builders and small teams who own GitHub Actions and need maintainable documentation for themselves and coding agents.
When should I use create-github-action-workflow-specification?
During Ship when preparing a release pipeline review, onboarding a collaborator, or before an agent refactors CI/CD jobs.
Is create-github-action-workflow-specification safe to install?
It reads and describes workflow files you point at; check the Security Audits panel on this page and avoid embedding secrets in specs.
SKILL.md
READMESKILL.md - Create Github Action Workflow Specification
# 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` ```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 ```yaml # 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 ```yaml # 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