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
/plugin install concourse-ci@netresearch-claude-code-marketplace

Without a marketplace

Since Claude Code 2.1.157 a plugin directory under your personal skills directory loads on its own:

mkdir -p ~/.claude/skills
git clone https://github.com/netresearch/concourse-ci-skill.git \
  ~/.claude/skills/concourse-ci

It loads as concourse-ci@skills-dir on the next session. Update with git -C ~/.claude/skills/concourse-ci pull and start a new session; remove it by deleting the directory. This route has no claude plugin update.

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

Related Resources

Development and tests

The shell scripts have behaviour tests in tests/:

tests/validate-pipeline.sh runs skills/concourse-ci/scripts/validate-pipeline.sh against pipeline fixtures: usage and missing-file errors, valid and invalid YAML, missing jobs and resources, literal versus ((var)) credentials, tag_regex findings, jobs without a triggering get, and the fly branch through a stub. It needs yq v4 and GNU grep; a locally installed fly is never called.
tests/check-plugin-version.sh covers Build/Scripts/check-plugin-version.sh, the version comparison the pre-push hook runs.

Run them locally from the repository root:

for t in tests/*.sh; do bash "$t" || exit 1; done

Each test prints ok or FAIL per case, followed by the captured output of a failing case, and exits non-zero if any case failed. CI runs the same files on every pull request and on pushes to main (.github/workflows/tests.yml). The pre-commit hooks in .pre-commit-config.yaml run the linters that lint.yml runs in CI.

New or changed behaviour in a script needs a test case in tests/ in the same pull request.

Governance and policies

This repository follows the Netresearch organisation policies:

Governance: who decides, how changes are accepted, and how disputes are resolved.
Roadmap: planned and excluded work for the coming year.
Handling of dependency and code analysis findings: thresholds, deadlines and exceptions for dependency and static-analysis findings.
Secret management: how CI and release credentials are stored, accessed and rotated.
Access roster: the accounts that can change code, settings or releases of this repository, with their access level.
Security assurance case: threat model, trust boundaries and countermeasures for this skill.

Every pull request to main runs these security checks (.github/workflows/security.yml): dependency review, Composer Audit, Opengrep (static analysis), Betterleaks (secret scanning) and zizmor (workflow analysis). CodeQL analyses the GitHub Actions workflows through the repository's default setup.

License

This project uses split licensing:

Code (scripts, workflows, configs): MIT
Content (skill definitions, documentation, references): CC-BY-SA-4.0

See the individual license files for full terms.

Author

Netresearch DTT GmbH

Website: netresearch.de
GitHub: @netresearch