# Challenge Documentation

> Challenge Documentation and Structure Skill

- Skill: `juice-shop/challenge-documentation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add juice-shop/challenge-documentation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/juice-shop/challenge-documentation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: juice-shop (https://skillmd.com/u/juice-shop)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/juice-shop/challenge-documentation

---

### Challenge Documentation and Structure Skill

This skill summarizes the documentation and structure of challenges in the OWASP Juice Shop companion guide (`pwning-juice-shop`).

#### 1. Centralized Challenge Tables (`README.adoc`)
All challenges are listed in `docs/modules/ROOT/pages/part2/README.adoc`. The tables are split based on the `{is_ctf}` attribute:

- **CTF Mode (`is_ctf == 1`)**:
  - Columns: `Name`, `Description`, `Hints`.
  - `Hints` column contains a link (bulb emoji 💡) to the specific challenge section in its category page.
- **Normal Mode (`is_ctf == 0`)**:
  - Columns: `Name`, `Description`, `Hints`, `Solution`.
  - `Hints` column: same as CTF mode.
  - `Solution` column contains a link (book emoji 📕) to the specific step-by-step solution in the `appendix/solutions.adoc` page.

#### 2. Category Pages (`docs/modules/ROOT/pages/part2/*.adoc`)
Challenges are grouped by category (e.g., `xss.adoc`, `injection.adoc`). Each page follows this structure:

- **Category Introduction**: General description of the vulnerability type.
- **Challenges Overview Table**: A table at the beginning of the chapter listing:
  - `Name`, `Description`, `Difficulty` (represented by star emojis ⭐).
- **Challenge Sections**: Each challenge has its own `==` level heading.
  - Heading text is usually the challenge description or a closely related title.
  - The heading includes an anchor (e.g., `[[_anchor_name]]`) for direct linking from the main table.
  - Content includes a brief explanation of the challenge context.
  - **Hints Handling**: Hints are included from external files located in `docs/modules/ROOT/partials/hints/` using the `include::` directive.
y    - **CRITICAL**: Hint partials are created and updated exclusively by the `partialize_hints.yml` pipeline. AI agents MUST NEVER create or modify these files.
    - The 'Score Board' challenge (`scoreBoardChallenge`) does not have hints and must NEVER have a hint partial file.
  - **New Challenge Preparation Rules**:
    - The hint include (`include::partial$hints/*.adoc[]`) should only be added if a matching partial already exists in `docs/modules/ROOT/partials/hints/`.
    - If the partial does not exist, the expected partial include should be commented out (e.g., `// include::partial$hints/newChallenge.adoc[]`) and a `🚧 Work in progress...` note should be added below it.

#### 3. Hints Handling
- Hints are stored as small AsciiDoc snippets in `docs/modules/ROOT/partials/hints/`.
- **Note**: These snippets are managed exclusively by the `partialize_hints.yml` pipeline. AI agents MUST NOT modify them.
- This modular approach allows hints to be updated independently and potentially reused.
- Challenges in category pages typically end with an `include` of their corresponding hint file.
- **Exception**: The 'Score Board' challenge has no hints and no hint partial.

#### 4. Step-by-Step Solutions (`appendix/solutions.adoc`)
- All solutions are centralized in `docs/modules/ROOT/pages/appendix/solutions.adoc`.
- Solutions are grouped by difficulty levels (e.g., `== ⭐ Challenges`, `== ⭐⭐ Challenges`, etc.).
- Each solution has a `===` level heading matching the challenge name.
- **Format**:
  - Usually a numbered list of steps.
  - Often includes images (from `appendix/` directory) to illustrate the process.
  - URLs in solutions are typically based on `http://localhost:3000`.
  - Links to other parts of the book (e.g., `xref:part1/challenges.adoc#_success_notifications`) are used when relevant.
- **New Challenge Preparation Rules**:
  - When preparing a new challenge, the step-by-step solution should get its heading followed by `🚧 Work in progress...` unless the specific steps are already provided in the prompt triggering this skill.