authoring-gzcli-challenge-yml

name	authoring-gzcli-challenge-yml
description	Use this skill when creating, editing, or reviewing a `challenge.yml` in a gzcli event. Covers the schema (type, value, flags, container, provide, scripts), the value=1000 rule, the flag-template format for DynamicContainer, and the rules for writing the player-facing description (English-only, no hints, no spoilers).

challenge.yml Authoring

For event-level layout, use authoring-gzcli-ctf-events. The authoritative schema lives in .gzctf/challenge.schema.yaml of any ctf-template directory.

Required fields

• name: — challenge title shown to players.
• author: — your handle.
• description: — markdown / HTML, shown verbatim. See "Description style" below.
• type: — exactly one of StaticAttachment, DynamicContainer, StaticContainer.
• value: — see "Value" below.
• flags: (for static types) or container.flagTemplate: (for DynamicContainer).
• provide: "./dist" — set only when dist/ ships artifacts to players.

Value

• value: 1000 for every challenge. This matches gzcli's .example/static-attachment/challenge.yml and .example/dynamic-container/challenge.yml, both of which carry value: 1000 # don't touch this value.
• Do not introduce 100 / 150 / 200 / 300 / 350 even when copying from a different template. If the template is at 1000, keep it.
• Scoring is balanced by gzctf's dynamic-scoring curve, not by per-challenge values.

Flag template

• Read the event's flag prefix from .gzevent or look at neighbouring challenges. Don't hardcode LKS{, flag{, or HTB{ — quote the event's convention.
• For DynamicContainer: flagTemplate: "<PREFIX>{<slug>_[TEAM_HASH]}". gzctf substitutes [TEAM_HASH] per-team at flag issue time.
• For StaticAttachment / StaticContainer: a single literal flag string under flags:.
• Do not double-brace the placeholder. The template <PREFIX>{x_[TEAM_HASH]} produces <PREFIX>{x_<hash>} — exactly one closing brace.

Description style

The description is problem statement, not a hint sheet. A player reading it should learn the lore and the artifact list — not the solving technique.

Allowed:

• Short scenario / lore (1–2 paragraphs).
• List of artifact filenames the player will work with.
• Service endpoint paths, request schema, response shape — the technical contract a player needs to use the service.
• An nc <host> <port> snippet or POST /endpoint Content-Type: … block.
• A neutral CTA: "Recover the flag." / "Submit the flag." / nothing.

Not allowed:

• **Hint:** lines, in any language.
• Leading questions that telegraph the solving path: "What does the attacker actually run on the victim's machine?", "Apa yang terjadi kalau name-nya berisi %p?"
• "The flag lives in X" / "the next-stage payload contains Y" reveals.
• Recommended-tool lists: "Try Ghidra / radare2 / IDA, perhaps photorec / binwalk."
• Bilingual descriptions with --- splitting English from the local language. Pick one (usually English) and translate the rest.

Self-check: read the description as a player who hasn't solved it. Could a stronger player infer extra solving steps that the lore alone wouldn't suggest? If yes, those sentences are hints — strip them.

Container fields (DynamicContainer / StaticContainer)

• containerImage: "{{.slug}}:latest" — gzcli runtime-substitutes {{.slug}} (see "Slug templating" below). Must match the image tag built by scripts.start:.
• exposePort: — single port the container listens on.
• memoryLimit, cpuCount, storageLimit — keep modest defaults (64–512 MB memory, 1 CPU) unless the workload demands more.
• enableTrafficCapture: — true only when the challenge legitimately benefits from gzctf's per-team pcap recording (typically for traffic-analysis style challenges).

Slug templating ({{.slug}})

gzcli runtime-substitutes {{.slug}} and {{.host}} across challenge.yml at sync / watch time (see ProcessChallengeTemplate in internal/gzcli/config/challenges.go). The slug is generated as <event>-<category>-<challenge-name>, lowercased and dash-normalized — e.g. for an event bali, category Web, name Sticky Secrets, the slug is bali-web-sticky-secrets.

Use {{.slug}} literally (with the curly braces) in these fields:

• containerImage: "{{.slug}}:latest"
• scripts.start: cd src && docker build -t {{.slug}} .
• For compose-based starts: cd src && docker compose -p {{.slug}} up --build -d
• scripts.stop: cd src && docker compose -p {{.slug}} down --volumes (if defined)
• scripts.restart: cd src && docker compose -p {{.slug}} restart (if defined)

The upload validator rejects scripts.start / scripts.stop / scripts.restart that don't use the literal {{.slug}} form. Only the exact strings above are accepted (see internal/gzcli/uploadserver/validation.go:384-428). Hardcoding the challenge name (docker build -t sticky-secrets .) will fail upload validation.

flagTemplate: is not processed by gzcli — [TEAM_HASH] is substituted by gzctf at flag-issue time. Don't put {{.slug}} inside flagTemplate:.

For maintainer local-test builds, substitute the slug manually: cd src && docker build -t bali-web-sticky-secrets:latest . (use whatever the resolved slug would be).

Common mistakes

• Description starts with **Hint:** or contains questions ending in ? that telegraph the solve.
• value: is anything other than 1000.
• flagTemplate: literal includes two trailing }, or omits the [TEAM_HASH] placeholder.
• flags: list set on a DynamicContainer (use container.flagTemplate instead).
• provide: "./dist" set without any files under dist/.
• containerImage: slug doesn't match the tag scripts.start actually builds.
• Hardcoded challenge name in containerImage: / scripts.start: instead of {{.slug}}. Upload validator will reject this.

Related sub-skills

• For service implementation in src/: authoring-gzcli-challenge-src.
• For dist/ artifacts: authoring-gzcli-challenge-dist.
• For solver/: authoring-gzcli-challenge-solver.