concourse-ci

Concourse CI Skill

Agent Skill for expert Concourse CI pipeline development, optimization, and troubleshooting.

Supported Platforms

Platform	Status
Claude Code (Anthropic)	✅ Supported
Cursor	✅ Supported
GitHub Copilot	✅ Supported
Other skills-compatible AI agents	✅ Supported

Features

• Pipeline Creation: Write production-ready Concourse CI pipelines with proper structure
• Resource Configuration: Configure git-resource, registry-image-resource, and 50+ resource types
• Optimization: Parallel execution, task caching, resource filtering patterns
• Troubleshooting: Debug common issues including git tag detection problems
• Best Practices: YAML anchors for DRY, job lifecycle hooks, webhook triggers
• Multi-Branch Pipelines: Dynamic pipeline management with set_pipeline and across
• Container Builds: OCI image building with oci-build-task and versioning

Installation

Marketplace (Recommended)

Add the Netresearch marketplace once, then browse and install skills:

# Claude Code
/plugin marketplace add netresearch/claude-code-marketplace

npx (skills.sh)

Install with any Agent Skills-compatible agent:

npx skills add https://github.com/netresearch/concourse-ci-skill --skill concourse-ci

Download Release

Download the latest release and extract to your agent's skills directory.

Git Clone

git clone https://github.com/netresearch/concourse-ci-skill.git

Composer (PHP Projects)

composer require netresearch/concourse-ci-skill

Requires netresearch/composer-agent-skill-plugin.

npm (Node Projects)

npm install --save-dev \
  @netresearch/agent-skill-coordinator \
  github:netresearch/concourse-ci-skill

Requires @netresearch/agent-skill-coordinator, which discovers the skill in node_modules and registers it in AGENTS.md via a postinstall hook. For pnpm, also allowlist the coordinator's postinstall:

{
  "pnpm": {
    "onlyBuiltDependencies": ["@netresearch/agent-skill-coordinator"]
  }
}

Usage

The skill activates automatically when you work with Concourse CI topics:

"Create a Concourse pipeline for my Node.js app"
"Configure git-resource with tag filtering"
"Debug why my pipeline isn't detecting new tags"
"Optimize my Concourse CI build times"
"Add webhook triggers to my pipeline"

Skill Contents

skills/concourse-ci/
├── SKILL.md                          # Core guidance
├── references/
│   ├── pipeline-syntax.md            # Complete YAML schema
│   ├── resources-guide.md            # Git, registry-image, docker-image migration
│   ├── best-practices.md             # Optimization, notifications, deployment
│   └── resource-types-catalog.md     # 50+ resource types incl. Ansible, Terraform
├── examples/
│   ├── basic-pipeline.yml            # Build-test-deploy with oci-build-task
│   ├── modern-ci-cd.yml              # Modern patterns: across, build_log_retention
│   ├── multi-branch.yml              # Dynamic branch pipelines
│   ├── docker-build.yml              # OCI image building with versioning
│   └── vars-template.yml             # Variable file organization
└── scripts/
    └── validate-pipeline.sh          # Pipeline validation script

Key Topics Covered

Pipeline Architecture

• Resources, jobs, steps, and resource types
• Job lifecycle hooks (on_success, on_failure, on_error, on_abort, ensure)
• Step types (get, put, task, set_pipeline, in_parallel, do, try)
• Variable syntax and credential management

Critical Gotchas

Git Resource Tag Detection - The skill documents the notorious issue where Concourse stops detecting tags after force-pushing, including root causes and solutions:

# Enable tag cleanup to fix detection issues
resources:
- name: repo
  type: git
  source:
    uri: ((git.uri))
    branch: main
    tag_regex: "^v[0-9]+\\.[0-9]+\\.[0-9]+$"
    fetch_tags: true
    clean_tags: true  # Critical fix

Optimization Patterns

• Parallel step execution with in_parallel
• Task caching for dependencies
• Shallow clones with depth: 1
• Resource path filtering
• Serial groups for resource contention

Compatibility

• Concourse v8.0+ (current)
• Legacy support for v6.5+ where noted