Authoring Gzcli Ctf Events

GZCLI CTF Event Authoring (orchestrator)

This skill covers event-level concerns. For work inside a specific challenge folder, route to a sub-skill.

Quick Use

• Confirm whether the task is event-level (this skill) or challenge-level (one of the sub-skills above).
• For event structure questions, read ./references/event-repo-structure.md.
• For the challenge directory contract (working-tree vs upload-portable view), read ./references/challenge-directory-contract.md.
• For sync, watch, and upload behavior, read ./references/sync-watch-and-upload-rules.md.

Core Workflow

1. Read .gzevent when event metadata (title, schedule, flag prefix convention) matters. 2. Keep challenges under the fixed category directories only: Misc, Crypto, Pwn, Web, Reverse, Blockchain, Forensics, Hardware, Mobile, PPC, OSINT, Game Hacking, AI, Pentest. 3. Start new challenges from the closest .example/ template instead of inventing a layout from scratch. 4. For each challenge sub-folder, defer to the matching sub-skill above. 5. Validate the intended solve path end-to-end before treating the challenge as ready.

Event-Level Rules

• challenge.yml must remain the canonical challenge definition filename.
• If provide: ./dist is set, dist/ must contain real files.
• solver/ must contain meaningful intended-solution material.
• Treat solver/ and writeup content as documentation — the watcher ignores them, they are not deploy inputs.

Related Files

• ./references/event-repo-structure.md
• ./references/challenge-directory-contract.md
• ./references/sync-watch-and-upload-rules.md

Challenge Directory Contract

There are two useful views of a challenge directory in a gzcli event repo.

1. Working Tree View

Inside the event repository, a challenge folder may contain:

• challenge.yml
• dist/
• src/
• solver/
• optional infrastructure files like Dockerfile and docker-compose.yml
• generated maintainer or contributor docs copied from .structure/

This is the view maintainers work with during normal authoring.

2. Portable Upload View

If a challenge is being prepared for the upload server or archive validation path, keep the root compatible with the embedded starter templates:

• required:
• challenge.yml
• dist/
• src/
• solver/
• optional:
• Dockerfile
• docker-compose.yml
• .dockerignore
• .gitignore

Additional root entries may fail upload validation.

Authoring Guidance

• Start from the closest .example/ template.
• Rename the folder to the final challenge slug early.
• Replace placeholder metadata in challenge.yml immediately.
• Keep downloadable player artifacts in dist/ — place raw files directly, do not zip them; gzcli automatically zips dist/ contents when uploading/syncing.
• Keep service code and build inputs in src/.
• Keep the intended solution or solver in solver/.

Event Repository Structure

This template is copied into events/<event-name>/.

Expected event-root files and directories:

• .gzevent: event metadata such as title, schedule, visibility, summary, and writeup policy
• .example/: starter challenge templates for common deployment models
• .structure/: reusable scaffold copied into challenge folders by gzcli structure
• .agents/skills/: shared skill references plus Codex/OpenAI-flavored manifests
• .claude/skills/: project-local Claude Code skills (slash-invocable as /authoring-gzcli-ctf-events)
• AGENTS.md: auto-loaded by Codex; points at .agents/skills/
• CLAUDE.md: auto-loaded by Claude Code; points at .claude/skills/
• README.md: participant and author guidance
• Kriteria.md: organizer challenge criteria
• Category directories:
• Misc
• Crypto
• Pwn
• Web
• Reverse
• Blockchain
• Forensics
• Hardware
• Mobile
• PPC
• OSINT
• Game Hacking
• AI
• Pentest

Use one folder per challenge inside the correct category:

<Category>/<challenge-slug>/

When gzcli structure is used, .structure/ content is copied into challenge directories. That scaffold may add repo-facing documentation like README.md, writeups/, or helper placeholders for maintainers and contributors.

Sync, Watch, and Upload Rules

Watcher Behavior

File changes map to update behavior:

• challenge.yml: metadata update
• dist/: attachment update
• src/: full redeploy
• Dockerfile, docker-compose.yml, Makefile: full redeploy
• solver/ and writeup content: no deploy action

Anything outside the allowed challenge update paths is ignored by the watcher.

Upload Validation Expectations

The upload path expects:

• the challenge definition file to be named exactly challenge.yml
• dist/, src/, and solver/ to exist
• solver/ to contain meaningful content
• challenge.yml to differ from the stock embedded templates
• dist/ to contain real files when provide: ./dist is used

Additional rules:

• if dashboard.config is present, it must point to ./src/docker-compose.yml
• for StaticContainer using a local image tag, include Dockerfile or src/Dockerfile

Recommended Development Loop

1. Create or update the challenge from the closest .example/ template. 2. Validate the full solve path from a clean start. 3. Use gzcli sync for explicit synchronization. 4. Use gzcli watch start for iterative development after the base layout is correct.