Add skill scaffolding guide and entity/localization system docs#199
Conversation
…ation docs - .claude/commands/add-skill.md: /add-skill slash command with a 10-step checklist covering ConfigFile creation, FileType registration, YAML resource, LevelableComponent, skill class, LocalizationKey route, locale YAML entry, McRPGExpansion registration, and final verification — mirrors the depth of /add-ability for skill authoring - .cursor/rules/entity-system.mdc: new glob-targeted rule for entity/**/*.java and holder/**/*.java covering the full holder hierarchy (AbilityHolder → LoadoutHolder → SkillHolder, with McRPGPlayer as a composition), when to type to each level, EntityManager retrieval patterns, McRPGPlayer retrieval via PlayerManager, and anti-patterns around cross-tick holder references - CLAUDE.md: add Localization System section documenting McRPGLocalizationManager locale chain resolution order, BundledLocale vs DynamicLocale, LocalizationKey route constant conventions, how to send localized messages, and the rule against direct MiniMessage sends; update Keeping This File Current maintenance table with entity hierarchy and localization change triggers https://claude.ai/code/session_01A9C5oe6ZEHpfYop6k29mkN
WalkthroughThree new documentation files introduced to guide McRPG development: skill scaffolding workflow (steps 0-11 with code templates and file paths), entity and holder system architecture including retrieval patterns and lifecycle rules, and localization system implementation covering locale resolution, registration, and messaging methods. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.claude/commands/add-skill.md:
- Around line 253-261: The fenced command blocks in
.claude/commands/add-skill.md (the blocks containing "./gradlew compileJava" and
"./gradlew test") lack language specifiers; update each triple-backtick fence to
include a shell language tag (e.g., ```shell or ```bash) so the blocks become
```shell ./gradlew compileJava ``` and ```shell ./gradlew test ``` for proper
syntax highlighting.
- Around line 215-224: Fix the markdown in Step 7 by ensuring proper blank lines
and correct ordered list numbering around the code blocks: add a blank line
before the first java code block that demonstrates creating the header constant
(referencing the pattern using SKILLS_HEADER, toRoutePath and the
<NAME_UPPER>_HEADER symbol), restart the numbering for the next sub-item as "1."
and add a blank line after the second java code block that shows the
display-item Route (referencing <NAME_UPPER>_DISPLAY_ITEM and Route.fromString).
Ensure both code fences are separated from text by blank lines so the markdown
renders correctly.
In `@CLAUDE.md`:
- Around line 386-399: Fix the markdown in the "Adding a New Locale Key"
section: ensure there is a blank line after the code fence that contains
mcRPGLocalizationManager.registerLanguageFile(myMcRPGLocalization); and add a
blank line before the "### Adding a New Locale Key" header; wrap the Java
snippet beginning with the LocalizationKey example (references: toRoutePath,
MY_SECTION_HEADER, MY_NEW_KEY, Route) in proper triple-backtick fences with a
blank line after the opening fence and before the closing fence; finally restart
the ordered list numbering so the list items under the code sample start at 1
(i.e., change the two trailing items to "1.") so the ordered list displays
correctly.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 16ddd918-ead6-4994-b571-1af54c0f0f02
📒 Files selected for processing (3)
.claude/commands/add-skill.md.cursor/rules/entity-system.mdcCLAUDE.md
| 1. Add a skill header constant (following the existing pattern, e.g. `SWORDS_HEADER`): | ||
| ```java | ||
| private static final String <NAME_UPPER>_HEADER = toRoutePath(SKILLS_HEADER, "<name_key>"); | ||
| ``` | ||
|
|
||
| 2. Add the display item route: | ||
| ```java | ||
| public static final Route <NAME_UPPER>_DISPLAY_ITEM = Route.fromString(toRoutePath(<NAME_UPPER>_HEADER, "display-item")); | ||
| ``` | ||
|
|
There was a problem hiding this comment.
Fix markdown formatting in Step 7.
The ordered list numbering and code block spacing violate markdown conventions:
- Missing blank line before the first code block
- The second list item should be numbered
1.(lists restart within each step context) - Missing blank line after the second code block
📝 Proposed formatting fix
In `src/main/java/us/eunoians/mcrpg/configuration/file/localization/LocalizationKey.java`:
-1. Add a skill header constant (following the existing pattern, e.g. `SWORDS_HEADER`):
+1. Add a skill header constant (following the existing pattern, e.g. `SWORDS_HEADER`):
+
```java
private static final String <NAME_UPPER>_HEADER = toRoutePath(SKILLS_HEADER, "<name_key>");-2. Add the display item route:
+1. Add the display item route:
+
public static final Route <NAME_UPPER>_DISPLAY_ITEM = Route.fromString(toRoutePath(<NAME_UPPER>_HEADER, "display-item"));</details>
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.21.0)</summary>
[warning] 216-216: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
---
[warning] 220-220: Ordered list item prefix
Expected: 1; Actual: 2; Style: 1/1/1
(MD029, ol-prefix)
---
[warning] 221-221: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
Verify each finding against the current code and only fix it if needed.
In @.claude/commands/add-skill.md around lines 215 - 224, Fix the markdown in
Step 7 by ensuring proper blank lines and correct ordered list numbering around
the code blocks: add a blank line before the first java code block that
demonstrates creating the header constant (referencing the pattern using
SKILLS_HEADER, toRoutePath and the <NAME_UPPER>_HEADER symbol), restart the
numbering for the next sub-item as "1." and add a blank line after the second
java code block that shows the display-item Route (referencing
<NAME_UPPER>_DISPLAY_ITEM and Route.fromString). Ensure both code fences are
separated from text by blank lines so the markdown renders correctly.
</details>
<!-- This is an auto-generated comment by CodeRabbit -->
| ``` | ||
| ./gradlew compileJava | ||
| ``` | ||
|
|
||
| If compilation succeeds, run: | ||
|
|
||
| ``` | ||
| ./gradlew test | ||
| ``` |
There was a problem hiding this comment.
Add language specifiers to code blocks.
The shell command blocks should specify shell or bash as the language identifier for proper syntax highlighting.
📝 Proposed fix
## Step 11 — Final verification
-```
+```shell
./gradlew compileJavaIf compilation succeeds, run:
- +shell
./gradlew test
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 253-253: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 259-259: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.claude/commands/add-skill.md around lines 253 - 261, The fenced command
blocks in .claude/commands/add-skill.md (the blocks containing "./gradlew
compileJava" and "./gradlew test") lack language specifiers; update each
triple-backtick fence to include a shell language tag (e.g., ```shell or
```bash) so the blocks become ```shell ./gradlew compileJava ``` and ```shell
./gradlew test ``` for proper syntax highlighting.
| ```java | ||
| mcRPGLocalizationManager.registerLanguageFile(myMcRPGLocalization); | ||
| ``` | ||
|
|
||
| ### Adding a New Locale Key | ||
|
|
||
| 1. Define a `public static final Route` constant in `LocalizationKey` under the appropriate section header constant: | ||
| ```java | ||
| private static final String MY_SECTION_HEADER = toRoutePath(PARENT_HEADER, "my-section"); | ||
| public static final Route MY_NEW_KEY = Route.fromString(toRoutePath(MY_SECTION_HEADER, "my-key")); | ||
| ``` | ||
| 2. Add the corresponding entry to every bundled locale YAML (`en.yml`, `en_gui.yml`, etc. — whichever file owns that section). | ||
| 3. **Always add new keys in the same PR as the feature that uses them.** | ||
|
|
There was a problem hiding this comment.
Fix markdown formatting in Localization System section.
Multiple markdown formatting issues affect readability:
- Missing blank lines after code blocks (lines 388, 395, 398)
- Ordered list numbering should restart at 1 for items on lines 397-398
📝 Proposed formatting fix
Third-party plugins add custom locale files via:
+
```java
mcRPGLocalizationManager.registerLanguageFile(myMcRPGLocalization);Adding a New Locale Key
- Define a
public static final Routeconstant inLocalizationKeyunder the appropriate section header constant:
private static final String MY_SECTION_HEADER = toRoutePath(PARENT_HEADER, "my-section");
public static final Route MY_NEW_KEY = Route.fromString(toRoutePath(MY_SECTION_HEADER, "my-key"));-2. Add the corresponding entry to every bundled locale YAML (en.yml, en_gui.yml, etc. — whichever file owns that section).
-3. Always add new keys in the same PR as the feature that uses them.
+
+1. Add the corresponding entry to every bundled locale YAML (en.yml, en_gui.yml, etc. — whichever file owns that section).
+1. Always add new keys in the same PR as the feature that uses them.
</details>
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.21.0)</summary>
[warning] 386-386: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
---
[warning] 393-393: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
---
[warning] 396-396: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
---
[warning] 397-397: Ordered list item prefix
Expected: 1; Actual: 2; Style: 1/2/3
(MD029, ol-prefix)
---
[warning] 398-398: Ordered list item prefix
Expected: 2; Actual: 3; Style: 1/2/3
(MD029, ol-prefix)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
Verify each finding against the current code and only fix it if needed.
In @CLAUDE.md around lines 386 - 399, Fix the markdown in the "Adding a New
Locale Key" section: ensure there is a blank line after the code fence that
contains mcRPGLocalizationManager.registerLanguageFile(myMcRPGLocalization); and
add a blank line before the "### Adding a New Locale Key" header; wrap the Java
snippet beginning with the LocalizationKey example (references: toRoutePath,
MY_SECTION_HEADER, MY_NEW_KEY, Route) in proper triple-backtick fences with a
blank line after the opening fence and before the closing fence; finally restart
the ordered list numbering so the list items under the code sample start at 1
(i.e., change the two trailing items to "1.") so the ordered list displays
correctly.
</details>
<!-- This is an auto-generated comment by CodeRabbit -->
…ation docs (#199) - .claude/commands/add-skill.md: /add-skill slash command with a 10-step checklist covering ConfigFile creation, FileType registration, YAML resource, LevelableComponent, skill class, LocalizationKey route, locale YAML entry, McRPGExpansion registration, and final verification — mirrors the depth of /add-ability for skill authoring - .cursor/rules/entity-system.mdc: new glob-targeted rule for entity/**/*.java and holder/**/*.java covering the full holder hierarchy (AbilityHolder → LoadoutHolder → SkillHolder, with McRPGPlayer as a composition), when to type to each level, EntityManager retrieval patterns, McRPGPlayer retrieval via PlayerManager, and anti-patterns around cross-tick holder references - CLAUDE.md: add Localization System section documenting McRPGLocalizationManager locale chain resolution order, BundledLocale vs DynamicLocale, LocalizationKey route constant conventions, how to send localized messages, and the rule against direct MiniMessage sends; update Keeping This File Current maintenance table with entity hierarchy and localization change triggers https://claude.ai/code/session_01A9C5oe6ZEHpfYop6k29mkN Co-authored-by: Claude <noreply@anthropic.com>
2 participants
Summary
This PR adds comprehensive developer documentation for the McRPG codebase, including a step-by-step skill scaffolding command and detailed system documentation for the entity hierarchy and localization system.
Key Changes
.claude/commands/add-skill.md— New 11-step command guide for scaffolding a complete McRPG skill end-to-end, from gathering inputs through final verification. Includes code templates for config files, components, skill classes, and registration points..cursor/rules/entity-system.mdc— New Cursor rules document covering the McRPG entity and holder hierarchy (AbilityHolder→LoadoutHolder→SkillHolder), howMcRPGPlayercomposes these holders, retrieval patterns viaEntityManagerandPlayerManager, key responsibilities of each holder type, and anti-patterns to avoid.CLAUDE.md— Enhanced with:BundledLocalevs.DynamicLocale, how to add new locale keys, and message resolution patternsImplementation Details
Swordsskill as the canonical reference implementation and provides concrete code templates for each stepMcRPGPlayerand emphasizes type-narrowing best practices to avoid unnecessary castshttps://claude.ai/code/session_01A9C5oe6ZEHpfYop6k29mkN
Summary by CodeRabbit