feat(skills): Add Claude Code validator setup skill #335
Conversation
Add comprehensive Claude Code skill for setting up and updating GenLayer validator nodes with focus on zero-downtime operations and proactive issue prevention. Key features: - Interactive installation wizard for new validator nodes - Zero-downtime update procedure (10-15 sec vs 3-4 min downtime) - Shared database structure for patch versions (v0.4.x) - Proactive edge case detection and prevention (30+ documented cases) - Pre-update validation checklist to catch issues before they occur - Support for local, SSH, GCP, AWS, and Azure deployments Critical edge cases documented: - OpenAI provider disabled by default (prevents bootstrap failure) - Database storage must be shared between patch versions - High-downtime update procedure (stops node before preparation) - LLM configuration validation before version switching Files added: - skill.yaml: Main skill definition with installation flow - sharp-edges.yaml: 30+ edge cases with detection and fixes - validations.yaml: Automated validation rules - update-procedure.md: Zero-downtime update guide - pre-update-checklist.md: Proactive validation steps - SKILL.md: Complete skill documentation
Add documentation requiring the validator setup skill to display a complete overview of all installation steps at the start of any setup or upgrade operation. This ensures users understand the full process before beginning and know what each step will do before it executes. Includes: - Required start message template with all 11 steps - Per-step explanation requirement before execution - Clear guidance to never skip showing step descriptions
Add an info callout at the top of the validator setup guide that introduces the assisted setup option via Claude Code. The callout includes: - Instructions to install the skill from the marketplace - Commands to run the wizard (install node / upgrade node) - Brief description of supported environments (local, SSH, cloud VMs)
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📝 WalkthroughWalkthroughThis PR introduces a new Claude plugin and interactive skill "genlayer-validator-setup" (v1.3.0) for assisting with GenLayer validator node deployment on Linux. It includes comprehensive documentation, validation rules, dependency checks, edge-case handlers, update procedures, and modifies the setup guide to highlight the assisted setup workflow. Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~50 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
✅ Deploy Preview for genlayer-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 8
🤖 Fix all issues with AI agents
In @.claude/skills/genlayer-validator-setup/pre-update-checklist.md:
- Around line 10-19: Replace the incorrect env var name IOINTELLIGENCEKEY with
the canonical IOINTELLIGENCE_API_KEY, and fix the OpenAI enablement test by
removing the piped grep after grep -q (which discards input); instead test for a
non-empty, non-comment OPENAIKEY entry by running a pipeline that filters
comments/empty values (e.g., grep -E 'OPENAIKEY=' .env | grep -v '^#' | grep -v
'=$' ) and use its exit status in the if, or use grep -q directly against the
filtered file content (avoid "grep -q ... | grep -v ..."); keep the subsequent
check that inspects the 'openai:' block in genvm-module-llm.yaml for the
'enabled' field.
In @.claude/skills/genlayer-validator-setup/sharp-edges.yaml:
- Around line 587-589: Remove the stray character that precedes the YAML comment
header so the line begins with a proper comment marker; specifically, delete the
leading "T" before the "#
============================================================================
# UPDATE PROCEDURE
# ==========================================================================="
block (or replace it with a valid key/value) so the YAML parser no longer
encounters a stray character breaking parsing.
In @.claude/skills/genlayer-validator-setup/SKILL.md:
- Around line 403-431: The two headings "### 1. Check Prerequisites" and "### 1.
New Validator or Existing?" are duplicate; update the headings to match the
process overview by renumbering them (change "### 1. Check Prerequisites" to
"### 2. Check Prerequisites" and "### 1. New Validator or Existing?" to "### 3.
New Validator or Existing?") or renumber the entire sequence so all section
numbers align with the overview; adjust any subsequent section numbers
accordingly to preserve a consistent step sequence.
In @.claude/skills/genlayer-validator-setup/skill.yaml:
- Around line 1088-1094: The handoffs section currently references three
nonexistent skills (genlayer-validator-monitor, genlayer-validator-manage,
genlayer-validator-upgrade); update the handoffs block by either removing those
entries, replacing each skill value with the correct existing skill names, or
implement new skills with those exact names; ensure the handoffs entries (the
"handoffs" list and each "skill" string) point to valid skill IDs so consumers
won't hit broken references.
In @.claude/skills/genlayer-validator-setup/validations.yaml:
- Around line 230-235: The rpc-url-reachable validation currently hardcodes the
Caldera RPC URL; update the rule with id "rpc-url-reachable" to use the
configured environment variable GENLAYERNODE_ROLLUP_GENLAYERCHAINRPCURL instead.
Change the command to reference the env var (e.g. curl -sf -X POST
"$GENLAYERNODE_ROLLUP_GENLAYERCHAINRPCURL" -H 'Content-Type: application/json'
-d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' | grep -q
'result'), ensure the variable is quoted to handle empty/space-containing
values, and adjust the message to indicate it checks the configured RPC URL. If
desired, add a pre-check to fail with a clear message when
GENLAYERNODE_ROLLUP_GENLAYERCHAINRPCURL is unset or empty.
- Around line 134-139: Add a prerequisite check that verifies PyYAML is
installed before running the YAML validation: create a new command check with id
"pyyaml-installed" that runs a short python3 -c 'import yaml' (or equivalent)
and add "pyyaml-installed" to the on_warn list for the existing check with id
"config-valid-yaml" (name "Config file is valid YAML") so missing PyYAML
produces a clear dependency warning instead of a misleading YAML syntax error.
- Around line 148-153: The llm-key-configured validation currently only checks
HEURISTKEY, COMPUT3KEY, and IOINTELLIGENCE_API_KEY; update the command for the
validation with id "llm-key-configured" to also check for the other documented
provider env vars (ANTHROPICKEY, XAIKEY, GEMINIKEY, ATOMAKEY, OPENAIKEY) so the
command succeeds if any of those are set; keep the validation
type/expect/message unchanged but expand the command's OR conditions to include
these additional environment variable checks.
In `@pages/validators/setup-guide.mdx`:
- Around line 9-28: The bash code block in the Callout mixes a shell invocation
("claude") with Claude REPL commands ("/plugin marketplace add" and "/plugin
install"), which will break if users copy-paste into a shell; split the block in
the Callout so the first block remains a bash block containing only the shell
command "claude" (and any real shell steps), and add a second block labeled as
text or plain (e.g., "text") that contains only the REPL commands "/plugin
marketplace add genlayerlabs/genlayer-docs" and "/plugin install
genlayer-validator-setup@genlayer-docs", updating the surrounding explanatory
sentence to say "Then, in the Claude Code prompt:" and removing the duplicated
bash-tagged REPL block.
🧹 Nitpick comments (3)
.claude/skills/genlayer-validator-setup/update-procedure.md (1)
12-18: Parameterize old/new versions to avoid stale rollback steps.The procedure hardcodes
v0.4.5and rollback tov0.4.3. Consider capturing the current version once and reusing it, so instructions stay correct across releases.♻️ Suggested refactor
-# 1. Check current version -curl -s http://localhost:9153/health | jq '.node_version' +# 1. Check current version +OLD_VERSION=$(curl -s http://localhost:9153/health | jq -r '.node_version') +echo "Current version: ${OLD_VERSION}" @@ -# 2. Download new version to /tmp -VERSION=v0.4.5 # or whatever new version +# 2. Download new version to /tmp +NEW_VERSION=v0.4.5 # set your target version -wget https://storage.googleapis.com/gh-af/genlayer-node/bin/amd64/${VERSION}/genlayer-node-linux-amd64-${VERSION}.tar.gz \ - -O /tmp/genlayer-node-${VERSION}.tar.gz +wget https://storage.googleapis.com/gh-af/genlayer-node/bin/amd64/${NEW_VERSION}/genlayer-node-linux-amd64-${NEW_VERSION}.tar.gz \ + -O /tmp/genlayer-node-${NEW_VERSION}.tar.gz @@ -ln -sfn /opt/genlayer-node/v0.4.3/bin bin -ln -sfn /opt/genlayer-node/v0.4.3/third_party third_party -ln -sfn /opt/genlayer-node/v0.4.3/data data -ln -sfn /opt/genlayer-node/v0.4.3/configs configs -ln -sfn /opt/genlayer-node/v0.4.3/docker-compose.yaml docker-compose.yaml -ln -sfn /opt/genlayer-node/v0.4.3/.env .env +ln -sfn /opt/genlayer-node/${OLD_VERSION}/bin bin +ln -sfn /opt/genlayer-node/${OLD_VERSION}/third_party third_party +ln -sfn /opt/genlayer-node/${OLD_VERSION}/data data +ln -sfn /opt/genlayer-node/${OLD_VERSION}/configs configs +ln -sfn /opt/genlayer-node/${OLD_VERSION}/docker-compose.yaml docker-compose.yaml +ln -sfn /opt/genlayer-node/${OLD_VERSION}/.env .envAlso applies to: 125-133
.claude/skills/genlayer-validator-setup/SKILL.md (2)
773-773: Consider using markdown link syntax for bare URLs.The bare URL
https://docs.genlayer.com/validators/monitoringwould render better as a proper markdown link.📝 Suggested fix
-- See: https://docs.genlayer.com/validators/monitoring +- See: [Monitoring documentation](https://docs.genlayer.com/validators/monitoring)
989-992: Same suggestion for the documentation URL at the end.📝 Suggested fix
## Official Documentation For the latest official setup guide, see: -https://docs.genlayer.com/validators/setup-guide +[GenLayer Validator Setup Guide](https://docs.genlayer.com/validators/setup-guide)
| ```bash | ||
| # Check which LLM key is set in .env | ||
| grep -E '(HEURISTKEY|COMPUT3KEY|IOINTELLIGENCEKEY|OPENAIKEY|LIBERTAI_API_KEY|ANTHROPICKEY|GEMINIKEY)=' /opt/genlayer-node/.env | grep -v '^#' | grep -v '=$' | ||
|
|
||
| # For each non-empty key, check if that provider is enabled | ||
| # Example for OpenAI: | ||
| if grep -q 'OPENAIKEY=' /opt/genlayer-node/.env | grep -v '=$'; then | ||
| grep -A 2 'openai:' /opt/genlayer-node/third_party/genvm/config/genvm-module-llm.yaml | grep 'enabled' | ||
| # If shows "enabled: false" → FLAG FOR FIX | ||
| fi |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
rg -n "IOINTELLIGENCE" -g '*.{md,mdx}'Repository: genlayerlabs/genlayer-docs
Length of output: 416
🏁 Script executed:
# Search for all IOINTELLIGENCEKEY references (without underscore)
rg -n "IOINTELLIGENCEKEY" --no-headingRepository: genlayerlabs/genlayer-docs
Length of output: 52
🏁 Script executed:
# Check if the file exists and read the relevant lines
cat -n ".claude/skills/genlayer-validator-setup/pre-update-checklist.md" | sed -n '1,25p'Repository: genlayerlabs/genlayer-docs
Length of output: 1304
Fix the OpenAI enablement check and correct the io.net environment variable name.
Line 12 uses IOINTELLIGENCEKEY, but the canonical name across documentation is IOINTELLIGENCE_API_KEY. Additionally, line 16 has a logic error: grep -q suppresses output, so the piped grep -v receives no input and the condition always fails. The check will never detect active OpenAI providers.
Proposed fix
# Check which LLM key is set in .env
-grep -E '(HEURISTKEY|COMPUT3KEY|IOINTELLIGENCEKEY|OPENAIKEY|LIBERTAI_API_KEY|ANTHROPICKEY|GEMINIKEY)=' /opt/genlayer-node/.env | grep -v '^#' | grep -v '=$'
+grep -E '(HEURISTKEY|COMPUT3KEY|IOINTELLIGENCE_API_KEY|OPENAIKEY|LIBERTAI_API_KEY|ANTHROPICKEY|GEMINIKEY)=' /opt/genlayer-node/.env | grep -v '^#' | grep -v '=$'
# For each non-empty key, check if that provider is enabled
# Example for OpenAI:
-if grep -q 'OPENAIKEY=' /opt/genlayer-node/.env | grep -v '=$'; then
+if grep -Eq '^OPENAIKEY=.+$' /opt/genlayer-node/.env; then
grep -A 2 'openai:' /opt/genlayer-node/third_party/genvm/config/genvm-module-llm.yaml | grep 'enabled'
# If shows "enabled: false" → FLAG FOR FIX
fi🤖 Prompt for AI Agents
In @.claude/skills/genlayer-validator-setup/pre-update-checklist.md around lines
10 - 19, Replace the incorrect env var name IOINTELLIGENCEKEY with the canonical
IOINTELLIGENCE_API_KEY, and fix the OpenAI enablement test by removing the piped
grep after grep -q (which discards input); instead test for a non-empty,
non-comment OPENAIKEY entry by running a pipeline that filters comments/empty
values (e.g., grep -E 'OPENAIKEY=' .env | grep -v '^#' | grep -v '=$' ) and use
its exit status in the if, or use grep -q directly against the filtered file
content (avoid "grep -q ... | grep -v ..."); keep the subsequent check that
inspects the 'openai:' block in genvm-module-llm.yaml for the 'enabled' field.
| T # ============================================================================ | ||
| # UPDATE PROCEDURE | ||
| # ============================================================================ |
There was a problem hiding this comment.
YAML syntax error: Stray character breaks parsing.
Line 587 has a stray T character before the comment marker that causes the YAML parser to fail with "could not find expected ':'". This will prevent the file from being parsed correctly.
🐛 Proposed fix
-T # ============================================================================
+ # ============================================================================
# UPDATE PROCEDURE
# ============================================================================📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| T # ============================================================================ | |
| # UPDATE PROCEDURE | |
| # ============================================================================ | |
| # ============================================================================ | |
| # UPDATE PROCEDURE | |
| # ============================================================================ |
🤖 Prompt for AI Agents
In @.claude/skills/genlayer-validator-setup/sharp-edges.yaml around lines 587 -
589, Remove the stray character that precedes the YAML comment header so the
line begins with a proper comment marker; specifically, delete the leading "T"
before the "#
============================================================================
# UPDATE PROCEDURE
# ==========================================================================="
block (or replace it with a valid key/value) so the YAML parser no longer
encounters a stray character breaking parsing.
| ### 1. Check Prerequisites | ||
| Verify system meets requirements before starting: | ||
|
|
||
| ```bash | ||
| # Check architecture (must be x86_64) | ||
| uname -m | ||
|
|
||
| # Check Node.js (v18+ required) | ||
| node --version | ||
|
|
||
| # Check Docker and Docker Compose | ||
| docker --version | ||
| docker compose version | ||
|
|
||
| # Check Python 3 with pip and venv | ||
| python3 --version | ||
| pip3 --version | ||
| python3 -m venv --help | ||
| ``` | ||
|
|
||
| **Minimum requirements:** | ||
| - AMD64 (x86_64) architecture | ||
| - 16GB+ RAM, 8+ CPU cores, 128GB+ SSD | ||
| - Node.js v18+ | ||
| - Docker with Compose plugin | ||
| - Python 3 with pip and venv | ||
|
|
||
| ### 1. New Validator or Existing? | ||
| **Note**: Commands shown here assume local execution. For remote servers, adapt based on your chosen access method from Step 0. |
There was a problem hiding this comment.
Duplicate step numbering: Two sections labeled "Step 1".
Lines 403 and 430 both define "### 1. ..." sections:
- Line 403:
### 1. Check Prerequisites - Line 430:
### 1. New Validator or Existing?
This creates confusion about the actual step sequence. Based on the process overview at lines 35-85 which shows prerequisites as Step 2 and new/existing validator as Step 3, the numbering here should be corrected.
📝 Suggested fix
-### 1. Check Prerequisites
+### 2. Check Prerequisites
Verify system meets requirements before starting:
...
-### 1. New Validator or Existing?
+### 3. New Validator or Existing?
**Note**: Commands shown here assume local execution...Alternatively, renumber all subsequent sections to maintain a consistent 1-11 sequence matching the overview.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ### 1. Check Prerequisites | |
| Verify system meets requirements before starting: | |
| ```bash | |
| # Check architecture (must be x86_64) | |
| uname -m | |
| # Check Node.js (v18+ required) | |
| node --version | |
| # Check Docker and Docker Compose | |
| docker --version | |
| docker compose version | |
| # Check Python 3 with pip and venv | |
| python3 --version | |
| pip3 --version | |
| python3 -m venv --help | |
| ``` | |
| **Minimum requirements:** | |
| - AMD64 (x86_64) architecture | |
| - 16GB+ RAM, 8+ CPU cores, 128GB+ SSD | |
| - Node.js v18+ | |
| - Docker with Compose plugin | |
| - Python 3 with pip and venv | |
| ### 1. New Validator or Existing? | |
| **Note**: Commands shown here assume local execution. For remote servers, adapt based on your chosen access method from Step 0. | |
| ### 2. Check Prerequisites | |
| Verify system meets requirements before starting: | |
🤖 Prompt for AI Agents
In @.claude/skills/genlayer-validator-setup/SKILL.md around lines 403 - 431, The
two headings "### 1. Check Prerequisites" and "### 1. New Validator or
Existing?" are duplicate; update the headings to match the process overview by
renumbering them (change "### 1. Check Prerequisites" to "### 2. Check
Prerequisites" and "### 1. New Validator or Existing?" to "### 3. New Validator
or Existing?") or renumber the entire sequence so all section numbers align with
the overview; adjust any subsequent section numbers accordingly to preserve a
consistent step sequence.
| handoffs: | ||
| - skill: "genlayer-validator-monitor" | ||
| when: "After node is running, to set up monitoring dashboards." | ||
| - skill: "genlayer-validator-manage" | ||
| when: "To manage stake, exit, or update validator identity." | ||
| - skill: "genlayer-validator-upgrade" | ||
| when: "To upgrade to a new node version." |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# List all skill directories to see what exists
echo "=== Skills in .claude/skills/ ==="
if [ -d ".claude/skills" ]; then
ls -1 .claude/skills/
else
echo ".claude/skills directory not found"
fi
echo ""
echo "=== Checking for referenced skill files ==="
for skill in "genlayer-validator-monitor" "genlayer-validator-manage" "genlayer-validator-upgrade"; do
if [ -d ".claude/skills/$skill" ]; then
echo "✓ $skill: EXISTS"
ls -la ".claude/skills/$skill/"
else
echo "✗ $skill: NOT FOUND"
fi
done
echo ""
echo "=== Searching for any references to missing skills ==="
rg "genlayer-validator-monitor|genlayer-validator-manage|genlayer-validator-upgrade" --type yaml -cRepository: genlayerlabs/genlayer-docs
Length of output: 358
🏁 Script executed:
#!/bin/bash
# Search for handoffs usage patterns to understand if referencing non-existent skills is intentional
echo "=== Searching for 'handoffs' in repository ==="
rg "handoffs" -t yaml -B 2 -A 5
echo ""
echo "=== Checking skill.yaml for any planning/roadmap notes ==="
rg -i "planned|future|todo|roadmap" .claude/skills/genlayer-validator-setup/skill.yamlRepository: genlayerlabs/genlayer-docs
Length of output: 176
🏁 Script executed:
#!/bin/bash
# Search for skill.yaml format documentation or examples
echo "=== Looking for README or documentation about skill.yaml format ==="
cat .claude/skills/README.md 2>/dev/null || echo "No README found"
echo ""
echo "=== Checking if there are other examples of skill.yaml ==="
find . -name "skill.yaml" -type f | head -20Repository: genlayerlabs/genlayer-docs
Length of output: 2705
🏁 Script executed:
#!/bin/bash
# Let's look at the actual handoffs section in context
echo "=== Handoffs section from skill.yaml (lines 1088-1094) ==="
sed -n '1085,1100p' .claude/skills/genlayer-validator-setup/skill.yaml
echo ""
echo "=== Broader context around handoffs ==="
sed -n '1080,1100p' .claude/skills/genlayer-validator-setup/skill.yamlRepository: genlayerlabs/genlayer-docs
Length of output: 1054
Remove or resolve handoff references to non-existent skills.
The handoffs section (lines 1088-1094) references three skills that do not exist in this repository:
genlayer-validator-monitorgenlayer-validator-managegenlayer-validator-upgrade
Either remove these handoffs, create the referenced skills, or update them to point to existing skills. As-is, users will encounter broken references when following this skill.
🤖 Prompt for AI Agents
In @.claude/skills/genlayer-validator-setup/skill.yaml around lines 1088 - 1094,
The handoffs section currently references three nonexistent skills
(genlayer-validator-monitor, genlayer-validator-manage,
genlayer-validator-upgrade); update the handoffs block by either removing those
entries, replacing each skill value with the correct existing skill names, or
implement new skills with those exact names; ensure the handoffs entries (the
"handoffs" list and each "skill" string) point to valid skill IDs so consumers
won't hit broken references.
| - id: config-valid-yaml | ||
| name: "Config file is valid YAML" | ||
| type: command | ||
| command: "python3 -c 'import yaml; yaml.safe_load(open(\"configs/node/config.yaml\"))' 2>/dev/null" | ||
| expect: "exit 0" | ||
| message: "Configuration file has YAML syntax errors." |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Search for PyYAML references in docs and configuration files
rg -n "pyyaml|python3-yaml" -g '*.{md,mdx,yaml}' --max-count=20Repository: genlayerlabs/genlayer-docs
Length of output: 52
🏁 Script executed:
#!/bin/bash
# Examine the validations.yaml file structure around lines 134-139
cat -n ".claude/skills/genlayer-validator-setup/validations.yaml" | head -160 | tail -40Repository: genlayerlabs/genlayer-docs
Length of output: 1988
🏁 Script executed:
#!/bin/bash
# Check if there are any prerequisite checks for yaml module already
rg -n "yaml|PyYAML" ".claude/skills/genlayer-validator-setup/validations.yaml"Repository: genlayerlabs/genlayer-docs
Length of output: 339
🏁 Script executed:
#!/bin/bash
# Check the full prerequisites structure and on_warn/on_error sections
cat -n ".claude/skills/genlayer-validator-setup/validations.yaml" | grep -A 5 -B 5 "on_warn:\|on_error:"Repository: genlayerlabs/genlayer-docs
Length of output: 351
🏁 Script executed:
#!/bin/bash
# Look at the prerequisites section to find python3-venv-installed location
rg -n "python3-venv-installed" ".claude/skills/genlayer-validator-setup/validations.yaml" -A 5 -B 2Repository: genlayerlabs/genlayer-docs
Length of output: 544
🏁 Script executed:
#!/bin/bash
# Check if PyYAML is mentioned in package.json, requirements.txt, or setup files
fd -e txt -e json -e py -e toml | xargs rg -l "pyyaml|python3-yaml" 2>/dev/null | head -20Repository: genlayerlabs/genlayer-docs
Length of output: 52
🏁 Script executed:
#!/bin/bash
# Get the full prerequisites section to understand structure before python3-venv-installed
cat -n ".claude/skills/genlayer-validator-setup/validations.yaml" | sed -n '60,85p'Repository: genlayerlabs/genlayer-docs
Length of output: 1170
🏁 Script executed:
#!/bin/bash
# Verify the complete on_warn section
cat -n ".claude/skills/genlayer-validator-setup/validations.yaml" | sed -n '245,260p'Repository: genlayerlabs/genlayer-docs
Length of output: 294
🏁 Script executed:
#!/bin/bash
# Double-check if yaml module is used in any shell commands in the file
rg -n "import yaml|yaml\.safe_load" ".claude/skills/genlayer-validator-setup/validations.yaml"Repository: genlayerlabs/genlayer-docs
Length of output: 177
Add PyYAML prerequisite check before YAML validation.
The config-valid-yaml check (line 137) runs python3 -c 'import yaml' but lacks a preceding prerequisite to ensure PyYAML is installed. Without it, missing PyYAML produces a misleading "Configuration file has YAML syntax errors" message instead of clearly indicating the missing dependency.
Proposed fix
- id: python3-venv-installed
name: "python3-venv is installed"
type: command
command: "dpkg -l python3-venv >/dev/null 2>&1 || python3 -m venv --help >/dev/null 2>&1"
expect: "exit 0"
message: "python3-venv is required. Install with: sudo apt install python3-venv"
+
+ - id: pyyaml-installed
+ name: "PyYAML is installed"
+ type: command
+ command: "python3 -c 'import yaml' >/dev/null 2>&1"
+ expect: "exit 0"
+ message: "PyYAML is required for YAML validation. Install with: sudo apt install python3-yaml"
# ============================================================================
# POST-INSTALLATION CHECKS
# ============================================================================And add pyyaml-installed to the on_warn section.
🤖 Prompt for AI Agents
In @.claude/skills/genlayer-validator-setup/validations.yaml around lines 134 -
139, Add a prerequisite check that verifies PyYAML is installed before running
the YAML validation: create a new command check with id "pyyaml-installed" that
runs a short python3 -c 'import yaml' (or equivalent) and add "pyyaml-installed"
to the on_warn list for the existing check with id "config-valid-yaml" (name
"Config file is valid YAML") so missing PyYAML produces a clear dependency
warning instead of a misleading YAML syntax error.
| - id: llm-key-configured | ||
| name: "At least one LLM API key is set" | ||
| type: command | ||
| command: "[ -n \"${HEURISTKEY:-}\" ] || [ -n \"${COMPUT3KEY:-}\" ] || [ -n \"${IOINTELLIGENCE_API_KEY:-}\" ]" | ||
| expect: "exit 0" | ||
| message: "No LLM API key configured. Set HEURISTKEY, COMPUT3KEY, or IOINTELLIGENCE_API_KEY" |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, let's run the suggested verification command
rg -n "KEY=" pages/validators/setup-guide.mdxRepository: genlayerlabs/genlayer-docs
Length of output: 196
🏁 Script executed:
# Also, let's find documentation files related to LLM setup/providers
fd -t f "setup-guide\|provider\|llm" --type f | head -20Repository: genlayerlabs/genlayer-docs
Length of output: 52
🏁 Script executed:
# List files in the repository to understand structure
git ls-files | grep -E "(doc|guide|setup|provider|llm)" | head -30Repository: genlayerlabs/genlayer-docs
Length of output: 1452
🏁 Script executed:
# Read the setup-guide documentation file
cat pages/validators/setup-guide.mdxRepository: genlayerlabs/genlayer-docs
Length of output: 29585
🏁 Script executed:
# Also check the providers documentation
cat pages/developers/intelligent-contracts/tools/genlayer-studio/providers.mdxRepository: genlayerlabs/genlayer-docs
Length of output: 1836
🏁 Script executed:
# Search for all LLM-related environment variable references in the codebase
rg -n "KEY\s*=|ANTHROPIC|GEMINI|OPENAI|COMPUT3|HEURIST" pages/validators/setup-guide.mdxRepository: genlayerlabs/genlayer-docs
Length of output: 523
🏁 Script executed:
# Check for OPENAI references in documentation
rg -i "openai|OPENAIKEY" pages/Repository: genlayerlabs/genlayer-docs
Length of output: 2920
🏁 Script executed:
# Check for LibertAI references
rg -i "libertai|LIBERTAI_API_KEY" pages/Repository: genlayerlabs/genlayer-docs
Length of output: 205
🏁 Script executed:
# Check the actual genvm-module-llm.yaml configuration file
find . -name "genvm-module-llm.yaml" -type fRepository: genlayerlabs/genlayer-docs
Length of output: 52
🏁 Script executed:
# Check the actual validations.yaml file to confirm current state
cat .claude/skills/genlayer-validator-setup/validations.yaml | grep -A 5 "llm-key-configured"Repository: genlayerlabs/genlayer-docs
Length of output: 389
🏁 Script executed:
# Search for LLM provider configuration across the codebase
rg -i "genvm.*llm\|llm.*provider" --type yamlRepository: genlayerlabs/genlayer-docs
Length of output: 52
🏁 Script executed:
# Search for all environment variable names that might be LLM keys
rg -i "KEY\s*=|api_key_env_var" --type yaml | head -30Repository: genlayerlabs/genlayer-docs
Length of output: 52
🏁 Script executed:
# Check the changelog for libertai details
cat pages/validators/changelog.mdx | grep -i libertai -A 3 -B 3Repository: genlayerlabs/genlayer-docs
Length of output: 564
🏁 Script executed:
# Search for all LLM provider environment variables more comprehensively
rg -i "anthropic|gemini|xai|atoma|openai|comput|heurist|iointel|libertai|ollama" --type mdx pages/validators/setup-guide.mdx | grep -i "key\|export\|env"Repository: genlayerlabs/genlayer-docs
Length of output: 97
🏁 Script executed:
# Check the openai provider page for exact env var name
cat pages/_providers/openai.mdxRepository: genlayerlabs/genlayer-docs
Length of output: 1086
🏁 Script executed:
# Search for LibertAI env var name
rg -i "libertai" pages/Repository: genlayerlabs/genlayer-docs
Length of output: 205
🏁 Script executed:
# Check if there's a providers list in documentation
rg -i "provider.*list|supported.*provider" pages/validators/setup-guide.mdx -A 5 -B 5Repository: genlayerlabs/genlayer-docs
Length of output: 52
🏁 Script executed:
# Search for LibertAI environment variable configuration
rg -i "libertai" . --type yaml --type jsonRepository: genlayerlabs/genlayer-docs
Length of output: 52
🏁 Script executed:
# Look at the entire .env example to see all documented env vars
cat .env.example 2>/dev/null || find . -name ".env.example" -o -name "env.example" | xargs catRepository: genlayerlabs/genlayer-docs
Length of output: 52
🏁 Script executed:
# Check if there's documentation about all supported providers
rg -i "provider.*openai|provider.*anthropic|provider.*gemini|provider.*atoma|provider.*libertai" --type=mdx -A 2 -B 2Repository: genlayerlabs/genlayer-docs
Length of output: 97
🏁 Script executed:
# Search for any configuration files that might list all LLM providers
find . -name "*llm*" -o -name "*provider*" | grep -E "\.(yaml|yml|json|mdx)$" | head -15Repository: genlayerlabs/genlayer-docs
Length of output: 471
🏁 Script executed:
# Search for libertai with env variable pattern
rg -i "libertai.*key|libertai.*env|libertai_api" .Repository: genlayerlabs/genlayer-docs
Length of output: 52
🏁 Script executed:
# Check transactions.mdx which showed provider configs
cat pages/understand-genlayer-protocol/core-concepts/transactions.mdx | grep -i "api_key_env_var\|provider" -B 2 -A 2 | head -50Repository: genlayerlabs/genlayer-docs
Length of output: 947
🏁 Script executed:
# Look for all API key environment variables in setup-guide
cat pages/validators/setup-guide.mdx | grep -i "export\|KEY=" | grep -v "^#"Repository: genlayerlabs/genlayer-docs
Length of output: 994
🏁 Script executed:
# Check if there are any provider configuration examples
cat pages/developers/intelligent-contracts/tools/genlayer-studio/providers.mdxRepository: genlayerlabs/genlayer-docs
Length of output: 1836
LLM key validation is incomplete.
The check only accepts three providers (Heurist, Comput3, io.net), but the .env.example and documentation indicate support for additional providers. This causes validation to fail for users on Anthropic, Gemini, XAI, or Atoma.
The .env.example includes templates for ANTHROPICKEY, XAIKEY, GEMINIKEY, and ATOMAKEY. Additionally, OpenAI is documented as a supported provider with the OPENAIKEY environment variable. Update the validation to include these providers:
♻️ Suggested update
- command: "[ -n \"${HEURISTKEY:-}\" ] || [ -n \"${COMPUT3KEY:-}\" ] || [ -n \"${IOINTELLIGENCE_API_KEY:-}\" ]"
+ command: "[ -n \"${HEURISTKEY:-}\" ] || [ -n \"${COMPUT3KEY:-}\" ] || [ -n \"${IOINTELLIGENCE_API_KEY:-}\" ] || [ -n \"${ANTHROPICKEY:-}\" ] || [ -n \"${GEMINIKEY:-}\" ] || [ -n \"${XAIKEY:-}\" ] || [ -n \"${ATOMAKEY:-}\" ] || [ -n \"${OPENAIKEY:-}\" ]"
- message: "No LLM API key configured. Set HEURISTKEY, COMPUT3KEY, or IOINTELLIGENCE_API_KEY"
+ message: "No LLM API key configured. Set one of: HEURISTKEY, COMPUT3KEY, IOINTELLIGENCE_API_KEY, ANTHROPICKEY, GEMINIKEY, XAIKEY, ATOMAKEY, OPENAIKEY"📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - id: llm-key-configured | |
| name: "At least one LLM API key is set" | |
| type: command | |
| command: "[ -n \"${HEURISTKEY:-}\" ] || [ -n \"${COMPUT3KEY:-}\" ] || [ -n \"${IOINTELLIGENCE_API_KEY:-}\" ]" | |
| expect: "exit 0" | |
| message: "No LLM API key configured. Set HEURISTKEY, COMPUT3KEY, or IOINTELLIGENCE_API_KEY" | |
| - id: llm-key-configured | |
| name: "At least one LLM API key is set" | |
| type: command | |
| command: "[ -n \"${HEURISTKEY:-}\" ] || [ -n \"${COMPUT3KEY:-}\" ] || [ -n \"${IOINTELLIGENCE_API_KEY:-}\" ] || [ -n \"${ANTHROPICKEY:-}\" ] || [ -n \"${GEMINIKEY:-}\" ] || [ -n \"${XAIKEY:-}\" ] || [ -n \"${ATOMAKEY:-}\" ] || [ -n \"${OPENAIKEY:-}\" ]" | |
| expect: "exit 0" | |
| message: "No LLM API key configured. Set one of: HEURISTKEY, COMPUT3KEY, IOINTELLIGENCE_API_KEY, ANTHROPICKEY, GEMINIKEY, XAIKEY, ATOMAKEY, OPENAIKEY" |
🤖 Prompt for AI Agents
In @.claude/skills/genlayer-validator-setup/validations.yaml around lines 148 -
153, The llm-key-configured validation currently only checks HEURISTKEY,
COMPUT3KEY, and IOINTELLIGENCE_API_KEY; update the command for the validation
with id "llm-key-configured" to also check for the other documented provider env
vars (ANTHROPICKEY, XAIKEY, GEMINIKEY, ATOMAKEY, OPENAIKEY) so the command
succeeds if any of those are set; keep the validation type/expect/message
unchanged but expand the command's OR conditions to include these additional
environment variable checks.
| - id: rpc-url-reachable | ||
| name: "RPC URL is reachable" | ||
| type: command | ||
| command: "curl -sf -X POST https://genlayer-testnet.rpc.caldera.xyz/http -H 'Content-Type: application/json' -d '{\"jsonrpc\":\"2.0\",\"method\":\"eth_blockNumber\",\"params\":[],\"id\":1}' | grep -q 'result'" | ||
| expect: "exit 0" | ||
| message: "Cannot reach RPC endpoint. Check network connectivity." |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# Find the validation file mentioned in the review
find . -name "validations.yaml" -o -name "validations.yml" 2>/dev/null | head -20Repository: genlayerlabs/genlayer-docs
Length of output: 128
🏁 Script executed:
# Search for .env file patterns and GENLAYERNODE_ROLLUP_GENLAYERCHAINRPCURL references
rg "GENLAYERNODE_ROLLUP_GENLAYERCHAINRPCURL" --type-listRepository: genlayerlabs/genlayer-docs
Length of output: 459
🏁 Script executed:
# Look for .env files and their locations
find . -name ".env*" -type f 2>/dev/null | grep -v node_modules | head -20Repository: genlayerlabs/genlayer-docs
Length of output: 52
🏁 Script executed:
# View the validation file to see the actual content
cat -n ./.claude/skills/genlayer-validator-setup/validations.yaml | head -80Repository: genlayerlabs/genlayer-docs
Length of output: 3567
🏁 Script executed:
# Check the specific lines mentioned in the review (230-235)
sed -n '225,240p' ./.claude/skills/genlayer-validator-setup/validations.yamlRepository: genlayerlabs/genlayer-docs
Length of output: 828
🏁 Script executed:
# Search for GENLAYERNODE_ROLLUP_GENLAYERCHAINRPCURL in the entire repo
rg "GENLAYERNODE_ROLLUP_GENLAYERCHAINRPCURL" --type-list || rg "GENLAYERNODE_ROLLUP_GENLAYERCHAINRPCURL"Repository: genlayerlabs/genlayer-docs
Length of output: 586
🏁 Script executed:
# Search for RPC URL references in validations.yaml
rg "rpc" ./.claude/skills/genlayer-validator-setup/validations.yaml -i -A 2 -B 2Repository: genlayerlabs/genlayer-docs
Length of output: 985
🏁 Script executed:
# Search for .env references in the entire repo
rg "\.env" --type-list || rg "\.env"Repository: genlayerlabs/genlayer-docs
Length of output: 3819
RPC reachability check hardcodes endpoint instead of using configured value.
The rpc-url-reachable validation tests only https://genlayer-testnet.rpc.caldera.xyz/http, ignoring the user's GENLAYERNODE_ROLLUP_GENLAYERCHAINRPCURL from .env. This means the validation can pass even when the user's actual RPC endpoint is unreachable, or fail when it's the Caldera endpoint that's unavailable. Use the configured RPC URL from .env instead of hardcoding it.
🐛 Proposed fix
- command: "curl -sf -X POST https://genlayer-testnet.rpc.caldera.xyz/http -H 'Content-Type: application/json' -d '{\"jsonrpc\":\"2.0\",\"method\":\"eth_blockNumber\",\"params\":[],\"id\":1}' | grep -q 'result'"
+ command: "RPC_URL=$(grep -E '^GENLAYERNODE_ROLLUP_GENLAYERCHAINRPCURL=' /opt/genlayer-node/.env .env 2>/dev/null | tail -n1 | cut -d= -f2-); [ -n \"$RPC_URL\" ] && curl -sf -X POST \"$RPC_URL\" -H 'Content-Type: application/json' -d '{\"jsonrpc\":\"2.0\",\"method\":\"eth_blockNumber\",\"params\":[],\"id\":1}' | grep -q 'result'"🤖 Prompt for AI Agents
In @.claude/skills/genlayer-validator-setup/validations.yaml around lines 230 -
235, The rpc-url-reachable validation currently hardcodes the Caldera RPC URL;
update the rule with id "rpc-url-reachable" to use the configured environment
variable GENLAYERNODE_ROLLUP_GENLAYERCHAINRPCURL instead. Change the command to
reference the env var (e.g. curl -sf -X POST
"$GENLAYERNODE_ROLLUP_GENLAYERCHAINRPCURL" -H 'Content-Type: application/json'
-d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' | grep -q
'result'), ensure the variable is quoted to handle empty/space-containing
values, and adjust the message to indicate it checks the configured RPC URL. If
desired, add a pre-check to fail with a clear message when
GENLAYERNODE_ROLLUP_GENLAYERCHAINRPCURL is unset or empty.
| <Callout type="info" emoji="🤖"> | ||
| **Prefer an Assisted Setup?** | ||
|
|
||
| If you have [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed, you can use an interactive wizard that guides you through the entire setup process. | ||
|
|
||
| **Install the skill:** | ||
| ```bash | ||
| claude | ||
| /plugin marketplace add genlayerlabs/genlayer-docs | ||
| /plugin install genlayer-validator-setup@genlayer-docs | ||
| ``` | ||
|
|
||
| **Run the wizard:** | ||
| ```bash | ||
| # For new installations | ||
| /genlayer-validator-setup install node | ||
|
|
||
| # For upgrading an existing node | ||
| /genlayer-validator-setup upgrade node | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
Claude Code plugin marketplace install command syntax documentation
💡 Result:
Claude Code’s plugin marketplace install command syntax (from the official docs):
-
Add a marketplace (so plugins can be discovered/installed):
/plugin marketplace add <source>where<source>can be:owner/repo(GitHub repo containing.claude-plugin/marketplace.json)- a git URL (e.g.
https://gitlab.com/company/plugins.git) - a local directory or direct path to
marketplace.json - a remote
marketplace.jsonURL [2]
-
Install a plugin from a marketplace:
/plugin install <plugin-name>@<marketplace-name>[2]
Examples shown in the docs:
/plugin marketplace add your-org/claude-plugins[1]/plugin install formatter@your-org[1]/plugin install plugin-name@marketplace-name[2]
Docs pages: Plugins [1], Plugin marketplaces [2].
Sources:
[1] https://docs.claude.com/en/docs/claude-code/plugins
[2] https://docs.claude.com/en/docs/claude-code/plugin-marketplaces
Separate shell invocation from Claude Code commands to prevent copy-paste errors.
The code block mixes claude (shell command) with /plugin marketplace add and /plugin install (Claude Code REPL commands) in a single bash block. Readers who copy the entire block into their shell will fail at the /plugin commands. Move the Claude commands to a separate block and clarify the context.
♻️ Suggested fix
**Install the skill:**
```bash
claude+Then, in the Claude Code prompt:
+text +/plugin marketplace add genlayerlabs/genlayer-docs +/plugin install genlayer-validator-setup@genlayer-docs +
-bash -/plugin marketplace add genlayerlabs/genlayer-docs -/plugin install genlayer-validator-setup@genlayer-docs -
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
In @pages/validators/setup-guide.mdx around lines 9 - 28, The bash code block in
the Callout mixes a shell invocation ("claude") with Claude REPL commands
("/plugin marketplace add" and "/plugin install"), which will break if users
copy-paste into a shell; split the block in the Callout so the first block
remains a bash block containing only the shell command "claude" (and any real
shell steps), and add a second block labeled as text or plain (e.g., "text")
that contains only the REPL commands "/plugin marketplace add
genlayerlabs/genlayer-docs" and "/plugin install
genlayer-validator-setup@genlayer-docs", updating the surrounding explanatory
sentence to say "Then, in the Claude Code prompt:" and removing the duplicated
bash-tagged REPL block.
</details>
<!-- fingerprinting:phantom:poseidon:eagle -->
<!-- This is an auto-generated comment by CodeRabbit -->
AgustinRamiroDiaz
left a comment
AgustinRamiroDiaz
left a comment
There was a problem hiding this comment.
I think the skill has been done using our custom deployment ansible pipeline, thus all the defaults around /opt, using openai and systemctl
I'd suggest you to prompt claude to create the guide from the current docs
| { | ||
| "name": "genlayer-docs", | ||
| "description": "GenLayer validator setup and node management skills", | ||
| "version": "1.3.0", |
There was a problem hiding this comment.
what's this version?
| "name": "genlayer-docs", | ||
| "description": "GenLayer validator setup and node management skills", | ||
| "version": "1.3.0", | ||
| "author": "GenLayer", |
There was a problem hiding this comment.
| "author": "GenLayer", | |
| "author": "GenLayer Labs", |
| ## Phase 1: Current Node Analysis | ||
|
|
||
| ### 1.1 Check Current LLM Configuration | ||
| **Purpose:** Detect if OpenAI is used but not enabled (edge: openai-backend-disabled) |
There was a problem hiding this comment.
| **Purpose:** Detect if OpenAI is used but not enabled (edge: openai-backend-disabled) | |
| **Purpose:** Detect if LLM provider API key is configured |
| # For each non-empty key, check if that provider is enabled | ||
| # Example for OpenAI: | ||
| if grep -q 'OPENAIKEY=' /opt/genlayer-node/.env | grep -v '=$'; then | ||
| grep -A 2 'openai:' /opt/genlayer-node/third_party/genvm/config/genvm-module-llm.yaml | grep 'enabled' | ||
| # If shows "enabled: false" → FLAG FOR FIX | ||
| fi | ||
| ``` | ||
|
|
||
| **Action if detected:** Note that OpenAI will need to be enabled in new version. |
There was a problem hiding this comment.
I think we don't want to encourage using openai
| ### 1.4 Verify Node is Running | ||
| **Purpose:** Confirm we're not stopping a non-running node (edge: high-downtime-update) | ||
|
|
||
| ```bash | ||
| sudo systemctl status genlayer-node --no-pager | ||
| ``` | ||
|
|
||
| **Action if NOT running:** Different procedure - no downtime concern, but check why it's not running. | ||
|
|
There was a problem hiding this comment.
validators may not run with systemctl
They might be using docker, or any other deployment tool
| ### 3.2 Check LLM Config in New Version | ||
| **Purpose:** Proactively fix OpenAI disabled issue BEFORE switching (edge: openai-backend-disabled) | ||
|
|
||
| ```bash | ||
| # If OpenAI key was found in current .env: | ||
| grep -A 2 'openai:' /opt/genlayer-node/${NEW_VERSION}/third_party/genvm/config/genvm-module-llm.yaml | grep 'enabled' | ||
|
|
||
| # If disabled, enable it NOW before switching: | ||
| if [ "$USING_OPENAI" = "true" ]; then | ||
| sed -i '/^ openai:/,/^ / s/enabled: false/enabled: true/' \ | ||
| /opt/genlayer-node/${NEW_VERSION}/third_party/genvm/config/genvm-module-llm.yaml | ||
| fi | ||
| ``` | ||
|
|
||
| **Action:** Fix BEFORE switching versions. |
There was a problem hiding this comment.
again mentioning openai
Summary
Changes
.claude/skills/genlayer-validator-setup/with full installation wizardTest plan
/plugin marketplace add genlayerlabs/genlayer-docs/genlayer-validator-setup install nodeflow/genlayer-validator-setup upgrade nodeflowSummary by CodeRabbit
New Features
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.