CircleCI Config Validator

Validate .circleci/config.yml files for syntax, structure, security, and best practices. Use when validating CircleCI pipeline configuration, auditing CI/CD...

Security Scan

The skill's code and instructions align with its stated purpose (validating .circleci/config.yml) and it does not request extra credentials, installs, or network access in the visible code, but the source file provided in the prompt is partially truncated so full verification is limited.

Purpose & Capability

Name/description claim to validate CircleCI config files and the package includes a Python script that parses and checks .circleci/config.yml contents using YAML rules and heuristics. There are no unrelated required binaries, env vars, or config paths.

Instruction Scope

SKILL.md explicitly instructs running the included Python script with commands like `validate`, `check`, `jobs`, and `graph`. The instructions and the visible script only reference the target config file and do not direct the agent to read unrelated system files or transmit data externally.

Install Mechanism

No install spec is present (instruction-only installation). The code is bundled as a local Python script and has an optional dependency on PyYAML (graceful error if missing). No external downloads or archive extraction are used.

Credentials

The skill does not declare or require any environment variables, credentials, or config paths. The script contains regexes to detect hardcoded secrets in the config file (expected for a linter).

Persistence & Privilege

The skill is not forced-always, does not request elevated persistence, and there is no indication it modifies other skills or global agent settings.

Assessment

This skill appears coherent and focused: it reads and validates CircleCI YAML files and flags structural, best-practice, and secret-related issues. Because it includes an executable Python script, review the script yourself (or run it in an isolated/sandboxed environment) before installing or allowing autonomous execution. Confirm PyYAML is available if you want parsing to work. If you need absolute assurance, provide the full untruncated source for review or run the script in a disposable container to observe behavior (network activity, filesystem accesses) before integrating it into CI automation.

A pure Python 3 (stdlib + PyYAML) validator for .circleci/config.yml files covering 22 rules across 5 categories.

Commands

python3 scripts/circleci_config_validator.py <command> [options] FILE

Command	Description
validate	Full validation — all 22 rules
check	Quick syntax + structure check only
jobs	List all jobs with executor type and step count
graph	Show workflow dependency graph as text

Options

Option	Description
--format text|json|summary	Output format (default: text)
--strict	Treat warnings as errors (exit 1)

Rules

ID	Category	Sev	Description
S001	Structure	E	YAML syntax error
S002	Structure	E	Missing version key
S003	Structure	E	Invalid version (must be 2 or 2.1)
S004	Structure	W	Missing jobs or workflows section
S005	Structure	W	Unknown top-level keys
J001	Jobs	E	Job missing execution environment
J002	Jobs	E	Job missing steps
J003	Jobs	W	Empty steps list
J004	Jobs	W	Unknown step name
J005	Jobs	E	run step missing command
W001	Workflows	E	Workflow references undefined job
W002	Workflows	E	Circular job dependency via requires
W003	Workflows	E	requires references undefined job
W004	Workflows	W	Empty workflow (no jobs)
SEC1	Security	E	Hardcoded secret in environment variable
SEC2	Security	W	setup_remote_docker without version pin
SEC3	Security	W	Deprecated deploy step used
SEC4	Security	I	context used without branch filters
B001	Best Practices	I	Missing resource_class
B002	Best Practices	I	No working_directory set
B003	Best Practices	W	save_cache without matching restore_cache
B004	Best Practices	W	Docker image using latest tag

Examples

# Full validation
python3 scripts/circleci_config_validator.py validate .circleci/config.yml

# Quick syntax check
python3 scripts/circleci_config_validator.py check .circleci/config.yml

# JSON output for CI
python3 scripts/circleci_config_validator.py --format json validate .circleci/config.yml

# One-line pass/fail
python3 scripts/circleci_config_validator.py --format summary validate .circleci/config.yml

# Strict mode (warnings = errors)
python3 scripts/circleci_config_validator.py --strict validate .circleci/config.yml

# List jobs
python3 scripts/circleci_config_validator.py jobs .circleci/config.yml

# Dependency graph
python3 scripts/circleci_config_validator.py graph .circleci/config.yml

Exit Codes

• 0 — No errors (warnings may exist)
• 1 — Errors found (or warnings in --strict mode)
• 2 — File not found or YAML parse error

Requirements

• Python 3.7+
• PyYAML (falls back to graceful error if unavailable)