checksy-workflow

name	checksy-workflow
description	Configure, run, and debug checksy workspace health checks. Use when creating or editing .checksy.yaml files, troubleshooting rule failures, setting up git-based remote configs, using --fix auto-repair, integrating into CI/CD, or generating JSON schemas for IDE validation. Covers severity levels (debug/info/warn/error), preconditions, patterns, caching, and common errors — even if the user just says "health checks", "workspace validation", or mentions YAML config issues without naming checksy explicitly. Does NOT handle infrastructure health checks (Kubernetes probes, Docker HEALTHCHECK, application monitoring) — use this skill specifically for checksy CLI configuration and workspace validation.
license	MIT
compatibility	Requires checksy binary in PATH. Git required for remote configs. Bash required for rule execution.
metadata	{"author":"opencode","version":"1.0.0","category":"dev-tools","checksy_version_compatibility":">=0.7.0","last_updated":"2026-04-26","changelog":[{"version":"1.0.0","date":"2026-04-26","notes":"Initial release"}]}

checksy Workflow

This skill guides you through configuring, running, and debugging checksy — a Rust-based CLI tool for running lightweight health checks in development workspaces.

Table of Contents

1. Quick Reference
2. Installation & Setup
3. Configuration
4. Running checksy
5. Remote Configs
6. Fix Mode
7. CI/CD Integration
8. Testing Configs
9. Edge Cases
10. Debugging
11. Best Practices
12. Quick Command Reference
13. Feedback & Issues
14. Resources

---

Quick Reference

Essential Commands

checksy check                    # Run all checks
checksy check --fix             # Run with auto-fix
checksy check --cs=warn --fs=error  # Filter by severity
checksy install                 # Cache git remotes
checksy schema > .checksy.schema.json  # Generate IDE schema

Severity Levels

debug < info < warn < error

Level	CLI Flag	Use For
debug	--cs=debug	Verbose diagnostics
info	--cs=info	Informational checks
warn	--cs=warn	Non-blocking issues
error	--cs=error	Blocking failures

---

Installation & Setup

Standard Installation

curl -fsSL https://raw.githubusercontent.com/notwillk/checksy/main/scripts/install.sh | bash
checksy version

Devcontainer

{
  "features": {
    "ghcr.io/notwillk/checksy-feature:latest": {}
  }
}

Build from Source

git clone https://github.com/notwillk/checksy.git
cd checksy && just compile

---

Configuration

Basic Structure

preconditions:
  - name: Dependencies installed
    severity: error
    check: test -d node_modules
    fix: npm ci

rules:
  - name: Tests pass
    severity: error
    check: npm test
  - remote: shared/team-checks.yaml

patterns:
  - "scripts/check-*.sh"
  - "!**/*-skip.sh"

Rule Properties

Property	Required	Description
name	No	Display name
check	Yes*	Shell command
severity	No	debug/info/warn/error
fix	No	Auto-fix command
remote	Yes*	Config file path

*Either check OR remote, not both.

Severity Cascade

CLI flags → Rule-level → Top-level defaults:

checksy check --cs=warn --fs=error

For detailed examples including production configs and patterns, see references/config-examples.md.

---

Running checksy

The check Command

checksy check                          # Default config
checksy --config=./team.yaml check     # Specific config
cat config.yaml | checksy --stdin-config check  # From stdin
checksy check --fix                    # Auto-fix failures
checksy check --no-fail                # Never exit with failure

The install Command

Cache git remotes before using:

checksy install           # Cache remotes
checksy install --prune   # Update and clean

The init Command

Create starter config:

checksy init  # Creates .checksy.config.yaml

The schema Command

Generate JSON Schema for IDE:

checksy schema > .checksy.schema.json

---

Remote Configs

File Remotes

rules:
  - remote: shared/team-checks.yaml

Git Remotes

Format: git+<url>#<ref>:<path>

rules:
  - remote: git+https://github.com/org/shared-checks.git
  - remote: git+https://github.com/org/shared-checks.git#develop
  - remote: git+https://github.com/org/shared-checks.git#v1.0.0:configs/dev.yaml

Important: Run checksy install before using git remotes.

Remote Rules Limitations

• Can ONLY have remote property
• Cannot have name, check, severity, fix, or hint
• Circular references are automatically detected

---

Fix Mode

How It Works

When --fix is enabled:

1. Run check command
2. If fails and fix exists, run fix
3. If fix succeeds, re-run check
4. Report final result

Example

rules:
  - name: Dependencies installed
    check: test -d node_modules
    fix: npm ci

Limitations

• Only works with inline rules (not patterns)
• Failed fixes don't stop execution
• Re-check runs after successful fix

---

CI/CD Integration

Template

# Install
curl -fsSL https://raw.githubusercontent.com/notwillk/checksy/main/scripts/install.sh | bash

# Cache remotes (if using git configs)
checksy install

# Run checks
checksy check

GitHub Actions

name: Health Checks
on: [push, pull_request]
jobs:
  checks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: curl -fsSL https://raw.githubusercontent.com/notwillk/checksy/main/scripts/install.sh | bash
      - run: checksy install
      - run: checksy check

GitLab CI

checksy:
  stage: test
  before_script:
    - curl -fsSL https://raw.githubusercontent.com/notwillk/checksy/main/scripts/install.sh | bash
    - checksy install
  script: checksy check

---

Testing Configs

Dry-Run Validation

checksy check --check-severity=debug --no-fail

Fixture-Based Testing

Create test fixtures in fixtures/:

fixtures/
├── passing/
│   └── .checksy.yaml
└── failing/
    └── .checksy.yaml

Schema Validation

checksy schema > /tmp/schema.json
# Validate configs against schema

---

Edge Cases

• Multiple configs: Use remote: to compose global + local
• Performance: Use --check-severity to filter; split by domain
• Partial configs: Test with --no-fail flag
• Windows: Use forward slashes in patterns; requires Git Bash/WSL

For advanced scenarios including performance optimization and complex configurations, see references/edge-cases-guide.md.

---

Debugging

Common Errors

Error	Solution
git remote not cached	Run checksy install or use --fix
failed to load config	Check YAML syntax; use valid severities
invalid remote rule	Remote rules can ONLY have remote property
Rules not running	Check severity hierarchy with --cs flag

Exit Codes

Code	Meaning
0	Success
1	Usage error
2	Runtime error
3	Check failures

For detailed troubleshooting including Windows issues, diagnostic steps, and error patterns, see references/troubleshooting-guide.md.

---

Best Practices

Decision Guide

Question	Answer
Preconditions vs Rules?	Preconditions = must pass first; Rules = can fail independently
Inline vs Remote?	Inline = project-specific; File = team; Git = cross-org
When to use --fix?	Use in dev, not in CI/CD

Severity Guidelines

Level	Use For
error	Blocking (tests, security)
warn	Non-blocking (linting)
info	FYI only
debug	Troubleshooting

Config Structure

# 1. Preconditions first
preconditions:
  - name: Dependencies installed

# 2. Rules by severity (errors first)
rules:
  - name: Critical check
    severity: error
  - name: Optional check
    severity: warn

For detailed best practices including naming conventions, organization patterns, and advanced guidance, see references/best-practices-guide.md.

---

Quick Command Reference

Command	Purpose
checksy check	Run all checks
checksy check --fix	Run with auto-fix
checksy check --cs=warn --fs=error	Filter by severity
checksy check --no-fail	Never exit with failure
checksy install	Cache git remotes
checksy install --prune	Update and clean cache
checksy init	Create starter config
checksy schema	Output JSON schema
checksy version	Show version
checksy help	Show help

---

Feedback & Issues

If this skill gives incorrect advice, contains outdated information, or could be improved:

1. Open an issue or PR at https://github.com/notwillk/checksy/

2. Include:

   • What you asked for
   • What the skill suggested
   • What you expected instead
   • Your checksy version (checksy version)

3. For quick fixes: Check the source code for the latest SKILL.md updates

---

Resources

• Source Code: https://github.com/notwillk/checksy
• Issues: https://github.com/notwillk/checksy/issues
• Schema: Run checksy schema for official JSON Schema

---

Reference Guides

For detailed guidance on specific topics:

• Configuration Examples - Detailed YAML examples and production configs
• Command Cheatsheet - Quick command reference
• Troubleshooting Guide - Error patterns, diagnostics, Windows issues
• Best Practices Guide - Naming conventions, decision frameworks
• Edge Cases Guide - Advanced scenarios, performance optimization