Cicd Engineer

CI/CD Engineer

When to Use

• Design or implement CI/CD for a skills monorepo (validate on PR, package on release)
• Add or fix GitHub Actions workflows for skill folders, changed-path detection, and matrix validation
• Wire skill-creator scripts (quick_validate.py, package_skill.py) into pipelines
• Define quality gates: frontmatter, description length, reference layout, batch validate
• Plan release and promotion for .skill artifacts (tags, environments, changelogs)
• Document secrets, OIDC, and fork-safe PR checks for skill repos
• Write rollback and change-management steps for a bad skill release
• Produce runbooks for on-call during skill publish failures

When NOT to Use

• Application/service CI only (containers, K8s deploy, app test suites) without skill packaging → devops
• Pre-flight architecture or build go/no-go before execution → build-validator
• Internal developer platform, golden paths, Backstage, paved-road templates → platform-engineer
• SLI/SLO programs, error budgets, burn-rate alerting, PRR without pipeline work → site-reliability-engineer
• Skill catalog inventory, overlap dedup, deprecate/split governance without CI YAML → ai-skill-manager
• Security gates (SBOM, SAST policy, supply-chain signing) as the primary task → devsecops
• Author a single new skill from scratch (content only) → skill-creator / init_skill.py

Related skills

Core Workflows

1. Pipeline topology for skills repos

Standard stage order:

checkout → detect changed skills → validate (quick_validate) → optional lint/scripts → package on release tag → publish artifact → notify

Checklist:

• [ ] Pipeline as code under .github/workflows/; versioned with repo
• [ ] PR jobs run on changed skill directories only when possible
• [ ] quick_validate.py gates merge; fail closed on invalid frontmatter
• [ ] Release job runs package_skill.py only after validation passes
• [ ] Artifacts immutable (tag + commit SHA in name or metadata)
• [ ] Manual or environment approval before org-wide distribution

See `references/pipeline_design_and_workflow.md`.

2. GitHub Actions implementation

1. Use paths / paths-filter for **/SKILL.md and references/** 2. Matrix or loop per changed skill directory 3. Cache nothing sensitive; use GITHUB_TOKEN with least scope 4. Fork PRs: read-only checks; no secrets on pull_request_target without hardening 5. Reusable workflow (workflow_call) for validate + package jobs

See `references/github_actions_and_build.md`.

3. Testing and quality gates

See `references/testing_gates_and_quality.md`.

4. Skill validation and packaging CI

python3 ~/.claude/skills/skill-creator/scripts/quick_validate.py path/to/skill-dir
python3 ~/.claude/skills/skill-creator/scripts/package_skill.py path/to/skill-dir ./dist

• PR: validate changed skills only
• Release: package validated skills; attach .skill to GitHub Release or internal registry
• Do not package every skill on every PR unless releasing a bundle

See `references/skill_validation_and_packaging_ci.md`.

5. Deployment, promotion, and operations

1. Dev/staging: auto-validate on PR merge to main 2. Release: tag skill-v* or calendar version; package and publish 3. Promotion: copy artifacts to consumer paths (plugin cache, internal registry) with checksum 4. Rollback: re-publish previous tag artifacts; document superseded skill description if needed 5. Runbook: who approves, how to verify install, comms for broken bundle

See `references/deployment_promotion_and_operations.md`.

6. Scope and boundaries

Confirm the ask is skills-repo CI/CD, not generic platform ops. Load references/cicd_engineer_scope.md when routing or scoping engagements.

When to load references

CI/CD Engineer — scope

Role definition

Own continuous integration and delivery for repositories that ship Agent Skills (folders with SKILL.md, references/, optional scripts)—not general application runtime unless skill packaging is in scope.

In scope

Out of scope (route elsewhere)

Trigger phrases (description)

CI/CD, CI/CD engineer, pipeline design, GitHub Actions, skill validation CI, package skills, release pipeline, deploy skills, PR checks, continuous integration, skill release workflow.

Success criteria

• Every merged change to SKILL.md or skill tree passed quick_validate.py (or documented exception)
• Releases produce reproducible .skill artifacts tied to git tag and commit
• Rollback path tested or documented; secrets never in git history
• Peer skills cross-linked in When NOT to Use and Related skills

Engagement checklist

1. Confirm repo layout (monorepo of skills vs single skill) 2. Identify consumer (Cursor plugin, internal registry, manual install) 3. Choose PR vs release packaging cadence 4. Map required checks to existing scripts 5. Document owners for approve/promote/rollback

Deployment, promotion, and operations

Promotion model

PR validate → merge main → (optional) staging registry → release tag → production registry / plugin channel

Release versioning

• Calendar: 2025.05.1 for monthly skill bundles
• Semver: skill-catalog-v2.3.0 when breaking routing or folder moves
• Per-skill tags: cicd-engineer-v1.0.0 when releasing skills independently

Document scheme in release notes; consumers pin versions.

Rollback

1. Identify last good release tag and artifact checksums 2. Re-publish previous dist/*.skill assets to production channel (do not rebuild from old commit unless reproducibility required) 3. If bad skill content already merged: revert git commit or publish patch release with fixed description/body 4. Post-incident: add CI gate that would have caught the issue

Time target: rollback artifact promotion < 15 minutes; git revert separate.

Change management

Operational runbook (skill release failed)

Symptoms

• Release workflow red after tag push
• Users report missing or corrupt .skill install
• Validator passed locally but failed in CI

Triage

1. Open failed workflow run; read quick_validate vs package_skill step 2. Confirm tag points to intended commit (git rev-parse $TAG) 3. List artifacts uploaded; verify checksums

Mitigate

• Re-run workflow with fixed commit (new patch tag)
• Or rollback promotion to previous release assets
• Disable auto-update channel if bad bundle propagated

Communicate

• Internal: #skills-platform with tag, failing skill names, ETA
• External: minimal notice if consumer-facing plugin broke

Follow-up

• Add test fixture or gate
• Update runbook with new failure mode

Secrets rotation

• Rotate registry tokens on schedule; update GitHub secrets
• Re-run dry-run release without publishing to verify OIDC

Observability

• Alert on: release workflow failure, validate main failure, artifact upload 4xx/5xx
• Dashboard: validate duration p95, skills packaged per release

Boundaries

Promotion to Kubernetes clusters or cloud runtimes is devops / cloud-engineer. This reference covers skill artifact promotion only.

GitHub Actions and build

Workflow layout

.github/workflows/
  skill-validate-pr.yml      # on pull_request
  skill-release.yml          # on push tags or workflow_dispatch
  reusable-validate.yml      # workflow_call

Changed-skill detection

Option A — paths filter (simple)

on:
  pull_request:
    paths:
      - '**/SKILL.md'
      - '**/references/**'
      - '**/scripts/**'

Option B — dynamic list (monorepo)

• Job lists directories containing SKILL.md at depth 1 (or 2)
• git diff --name-only origin/main... → map files to skill roots
• Output JSON array for matrix skill: ${{ fromJson(needs.changes.outputs.skills) }}

Validate job pattern

jobs:
  validate:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        skill: ${{ fromJson(needs.detect.outputs.skills) }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - name: Install validator deps
        run: pip install pyyaml
      - name: quick_validate
        run: |
          python3 ~/.claude/skills/skill-creator/scripts/quick_validate.py "${{ matrix.skill }}"

Pin skill-creator via submodule, copy script into repo, or install from known commit in CI.

Reusable workflow

Expose inputs: skill_path, python_version. Call from PR and release workflows to avoid drift.

Permissions (least privilege)

Avoid permissions: write-all.

Fork safety

• Prefer pull_request over pull_request_target for untrusted forks
• Never expose org secrets to fork PR workflows
• For label-gated workflows on external contributors, use explicit labeled + CODEOWNERS review

Caching

• Cache pip packages for PyYAML if validator needs it
• Do not cache dist/*.skill across release versions without content-addressed keys

Secrets

Document required secrets in repo CONTRIBUTING or internal runbook—not in skill folders.

Build summary for PRs

Emit step summary markdown: skill name, pass/fail, validator message. Surfaces failures without digging logs.

Pipeline design and workflow

Recommended stages

Pull request (continuous integration)

1. Checkout — full history if versioning or path filters need base comparison 2. Discover changes — list skill directories touched (SKILL.md, references/, scripts/) 3. Validate — quick_validate.py per changed skill (fail job on first error or matrix all) 4. Optional — run skill-local scripts tests, markdown lint, secret scan 5. Report — PR check summary with skill names and validator output

Main branch (integration)

• Nightly or on-merge: validate_all_skills.sh for full-repo regression when cheap enough
• Skip full matrix if repo is huge; sample or shard by top-level directory

Release (continuous delivery)

1. Trigger — tag push (v*, skill-*) or manual workflow_dispatch 2. Validate — all skills in release set (never package unvalidated trees) 3. Package — package_skill.py → dist/<name>.skill 4. Publish — GitHub Release assets, internal blob store, or artifact registry 5. Record — changelog entry, commit SHA, artifact digest

Branching

Artifact strategy

Name artifacts with skill folder name + version + short SHA to avoid overwrites.

Environment gates

Use GitHub environments for approval on org-wide skill distribution, not for every PR validate job.

Idempotency and concurrency

• concurrency: group: release-${{ github.ref }} cancel-in-progress false for releases
• PR jobs: cancel superseded runs on same branch
• Re-running release workflow must not mutate prior release assets (new tag or version suffix)

Failure handling

Skill validation and packaging CI

Tooling paths

In CI, vendor scripts into tools/skill-creator/ or pin a container image if ~/.claude is unavailable.

PR workflow contract

Inputs: changed skill directory paths Outputs: pass/fail per skill; logs archived as workflow artifacts

Rules:

1. Every path with edited SKILL.md must run quick_validate.py on that directory 2. If only references/ changed, still validate owning skill root 3. Do not run package_skill.py on PR unless testing packaging explicitly (slow, noisy)

Release workflow contract

Inputs: tag, optional skill list (default: all skills or tag changelog) Steps:

mkdir -p dist
for skill_dir in skills/*/; do
  python3 tools/skill-creator/quick_validate.py "$skill_dir"
  python3 tools/skill-creator/package_skill.py "$skill_dir" dist/
done

Outputs:

• dist/<skill-name>.skill per packaged skill
• Optional dist/manifest.json with { name, path, sha256, git_sha, tag }

When to package

Artifact integrity

• Compute sha256sum dist/*.skill → attach checksums.txt to Release
• Upload artifacts with actions/upload-artifact and softprops/action-gh-release
• Consumers verify hash before org-wide push

Integration with skill-creator init

• init_skill.py scaffolds folders; CI should fail if example scripts/assets remain in merged skills (policy-dependent)
• Enforce deletion of scripts/example.py, assets/example_asset.txt via lint or CODEOWNERS review

Parallelism

Matrix over skill folders; cap max-parallel to avoid runner starvation on large monorepos.

Failure messages

Surface validator message verbatim in PR comment or check summary—speeds fix for frontmatter typos.

Coordination with ai-skill-manager

• ai-skill-manager: catalog, overlap, lifecycle governance
• cicd-engineer: wires validation into automation and release mechanics

Both may reference the same scripts; avoid duplicating validator logic in custom bash—call upstream scripts.

Testing gates and quality

Gate stack (skills repo)

quick_validate expectations

• SKILL.md exists with valid YAML frontmatter
• Only allowed frontmatter keys (per skill-creator): name, description, license, allowed-tools, metadata
• description ≤ 1024 characters; no angle brackets
• name conventions per org policy (many repos use hyphen-case folder name)

Treat validator exit code non-zero as hard fail.

Batch validation

From repo root:

bash ai-skill-manager/scripts/validate_all_skills.sh .

Use on:

• Nightly schedule
• Before major release tag
• After bulk import or rename

Shard by alphabet or top-level folder if runtime exceeds CI budget.

PR policy

• Require status check skill-validate (or matrix aggregate)
• Require up-to-date branch with main before merge
• Block force-push to main without admin exception

Quality beyond validator

Test data and fixtures

• Keep minimal fixture skill under tests/fixtures/valid-skill/ for workflow integration tests
• Do not commit real API keys in fixture skills

Flake management

• Validator should be deterministic; if flaky, fix script not retry blindly
• Network calls in CI for packaging uploads: retry with backoff only on 5xx

Reporting metrics (optional)

Track per week: PR validate duration, fail rate by skill, release count, rollback count.