PaperclipOrg
Claude Agent Skill · by Github

Create Github Action Workflow Specification

The create-github-action-workflow-specification skill generates formal, implementation-agnostic specifications for existing GitHub Actions workflows designed fo

Install
Terminal · npx
$npx skills add https://github.com/github/awesome-copilot --skill create-github-action-workflow-specification
Works with Paperclip

How Create Github Action Workflow Specification fits into a Paperclip company.

Create Github Action Workflow Specification drops into any Paperclip agent that handles this kind of work. Assign it to a specialist inside a pre-configured PaperclipOrg company and the skill becomes available on every heartbeat — no prompt engineering, no tool wiring.

S
SaaS FactoryPaired

Pre-configured AI company — 18 agents, 18 skills, one-time purchase.

$27$59
Explore pack
Source file
SKILL.md276 lines
Expand
---name: create-github-action-workflow-specificationdescription: 'Create a formal specification for an existing GitHub Actions CI/CD workflow, optimized for AI consumption and workflow maintenance.'--- # 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.0date_created: [YYYY-MM-DD]last_updated: [YYYY-MM-DD]owner: DevOps Teamtags: [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 ```mermaidgraph 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 VariablesENV_VAR_1: string  # Purpose: [description]ENV_VAR_2: secret  # Purpose: [description] # Repository Triggerspaths: [list of path filters]branches: [list of branch patterns]``` ### Outputs ```yaml# Job Outputsjob_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 first2. **Review & Approval**: [Approval process]3. **Implementation**: Apply changes to workflow4. **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 objective2. **Map Job Flow**: Create dependency graph showing execution order3. **Identify Contracts**: Document inputs, outputs, and interfaces4. **Capture Constraints**: Extract timeouts, permissions, and limits5. **Define Quality Gates**: Identify validation and approval points6. **Document Error Paths**: Map failure scenarios and recovery7. **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```mermaidstyle TriggerNode fill:#e1f5festyle SuccessNode fill:#e8f5e8style FailureNode fill:#ffebeestyle ProcessNode fill:#f3e5f5``` ### Complex WorkflowsFor workflows with 5+ jobs, use subgraphs:```mermaidgraph 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 format2. **Abbreviate Consistently**: Define once, use throughout3. **Bullet Points**: Avoid prose paragraphs4. **Code Blocks**: Structured data over narrative5. **Cross-Reference**: Link instead of repeat information Focus on creating a specification that serves as both documentation and a template for workflow updates.