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. Hintscolumn contains a link (bulb emoji 💡) to the specific challenge section in its category page.
- Columns:
- Normal Mode (
is_ctf == 0):- Columns:
Name,Description,Hints,Solution. Hintscolumn: same as CTF mode.Solutioncolumn contains a link (book emoji 📕) to the specific step-by-step solution in theappendix/solutions.adocpage.
- Columns:
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 theinclude::directive. y - CRITICAL: Hint partials are created and updated exclusively by thepartialize_hints.ymlpipeline. 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.
- The 'Score Board' challenge (
- New Challenge Preparation Rules:
- The hint include (
include::partial$hints/*.adoc[]) should only be added if a matching partial already exists indocs/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.
- The hint include (
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.ymlpipeline. 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
includeof 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.
- When preparing a new challenge, the step-by-step solution should get its heading followed by