docs · contribute

Contributing Guide.

Guidelines for developing skills, modifying the Rust CLI, running validation suites, and opening pull requests. Security disclosures should be submitted privately via SECURITY.md.

Developing Skills.

Skills are located under skills/<group>/<name>/. Every skill requires a primary SKILL.md file with YAML frontmatter conforming to the skills.sh specification. Keep the root file focused on routing and execution boundaries; move in-depth operational detail into references/ and helper scripts into scripts/.

File / Directory
Type
Convention & Purpose
01
SKILL.md
Required
Frontmatter (name, model, description, triggers) + concise routing and execution instructions.
02
references/
Optional
Markdown documents for deep domain knowledge, loaded progressively by the agent.
03
scripts/
Optional
Deterministic bash/python scripts executed by the agent for mechanical steps.

Validating Skills.

Validate skill structure, YAML frontmatter syntax, trigger definitions, and referenced file existence using the validation script:

bash — validate skills 
# Validate a single skill
$bash scripts/validate-skill.sh skills/workflow/work/SKILL.md

# Validate all skills in repository
$for skill in skills/*/*/SKILL.md; do bash scripts/validate-skill.sh "$skill"; done

CLI Development & Testing.

The zharness CLI is a Rust crate in cli/. CI (.github/workflows/cli-ci.yml) runs cargo fmt --check, cargo clippy -D warnings, and cargo test, and a size gate keeps the Linux musl release binary at or under 1,850,000 bytes. The tests include golden replay, playbook projection parity, and compatibility with manifests written by the Go-era binary.

bash — build and test cli 
# Navigate to CLI module
$cd cli

# Check formatting and lint
$cargo fmt --check
$cargo clippy --all-targets -- -D warnings

# Execute test suite
$cargo test

# Build the release binary
$cargo build --release

Verifying Documentation References.

To avoid dead links and drift between code and documentation, run verify-doc-links.sh. It validates repo-relative paths in backticks and markdown links across all tracked documentation.

bash — verify documentation links 
# Verify all documentation cross-references and claims
$bash scripts/verify-doc-links.sh

Pre-Commit Hooks & Fail-Closed Guards.

Install the repository pre-commit hooks to ensure every commit satisfies the workflow guarantees:

bash — install git hooks 
# Install pre-commit hook into .git/hooks/
$bash scripts/install-git-hooks.sh

The hook enforces four fail-closed rules on staged commits, and cli-ci.yml re-runs them on every push:

  1. Proof Re-execution: Any newly added plan review verdict of APPROVED or APPROVE_WITH_REQUESTS must have every nested proof command successfully re-executed by the hook before the commit is accepted.
  2. Independent Judge (high-risk): On a lane: high-risk plan, a new Validation entry declaring judge: same-session is rejected.
  3. Independent Judge (full): Any mode: full entry declaring judge: same-session is rejected, on every lane.
  4. One Active Plan: More than one non-empty file under docs/plans/active/ is rejected.

A stale hook from an earlier install is replaced automatically. A foreign pre-commit hook is refused unless you pass --force.

Pull Request Checklist.

Before opening a pull request on GitHub, verify:

  • Run targeted checks for changed components (skills validator, cargo test, scripts/test-guards.sh, or doc link checker).
  • Ensure all commit messages adhere to Conventional Commits format (e.g. feat(cli): ..., fix(skills): ..., docs(site): ...).
  • Never commit API keys, personal auth tokens, or private settings files.
Ready to contribute? Explore the repository code.
View on GitHub Install Guide