Fix missing frontmatter (3 skills, 11 commands) + add CLAUDE.md, CI, and validation - #5
Fix missing frontmatter (3 skills, 11 commands) + add CLAUDE.md, CI, and validation#5YoavLax wants to merge 2 commits into
Conversation
eval-harness, project-guidelines-example, and verification-loop were missing the YAML frontmatter (name + description) that Claude Code's Agent Skills format requires for skill discovery. Without it, Claude Code cannot route to these skills at all - they are silently invisible even though the skill content itself is complete and useful. Fixed by adding frontmatter consistent with the other 8 skills in this repo (e.g. tdd-workflow, coding-standards, security-review). Impacted by AI (Agent mode: copilot | Model: claude-sonnet-5 | Prompts: 6 | Tokens: claude-sonnet-5: 5440k in/25k out (5299k cached) +14k reasoning)
Foundation/verification/scoping/tooling gaps found via AgentCompass analysis: - CLAUDE.md: root entry point so Claude Code has project context when working on this repo (previously none existed - ironic for a Claude Code plugin repo). - .github/workflows/ci.yml: runs the existing test suite (node tests/run-all.js) and frontmatter validation on every push/PR. Would have caught the missing SKILL.md frontmatter from the prior commit. - scripts/validate-frontmatter.js: checks required frontmatter across agents/*.md (name, description, tools, model), commands/*.md (description), and skills/**/SKILL.md (name, description). - commands/*.md (11 files): were missing the description frontmatter entirely, inconsistent with the other 4 commands and invisible to the Claude Code command picker. Added descriptions for build-fix, checkpoint, code-review, eval, learn, orchestrate, refactor-clean, test-coverage, update-codemaps, update-docs, verify. - scripts/AGENTS.md: scoped conventions for the cross-platform Node.js scripts directory. - .env.example: documents the 4 env vars actually read by scripts/ (CLAUDE_PACKAGE_MANAGER, CLAUDE_TRANSCRIPT_PATH, CLAUDE_SESSION_ID, COMPACT_THRESHOLD). - .nvmrc: pins Node 20 for the scripts/ toolchain. Verified: node scripts/validate-frontmatter.js and node tests/run-all.js both pass (62/62 tests). Impacted by AI (Prompts: 1)
📝 WalkthroughWalkthroughThe repository now includes frontmatter metadata, validation tooling, environment documentation, repository guidance, and GitHub Actions CI. CI uses Node.js 20, validates metadata, and runs the complete test suite. ChangesRepository setup
Estimated code review effort: 3 (Moderate) | ~20 minutes 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.github/workflows/ci.yml:
- Line 13: Update the actions/checkout@v4 step to set persist-credentials:
false, and declare the job or workflow permissions explicitly with only the
required contents: read access before executing repository-controlled code.
In @.nvmrc:
- Line 1: Update the Node.js version specified in .nvmrc from 20 to a supported
even-numbered LTS release, preferably 22, so CI uses a maintained runtime.
In `@commands/checkpoint.md`:
- Line 2: Use a parser-safe frontmatter contract: quote the full description
value in commands/checkpoint.md:2, commands/eval.md:2, and
commands/orchestrate.md:2. Update scripts/validate-frontmatter.js to parse YAML
before validating field values so malformed YAML is rejected, and update the
CLAUDE.md reference at lines 24-25 to document or invoke this validation before
commits.
In `@scripts/validate-frontmatter.js`:
- Around line 37-40: Update the frontmatter field parsing in the validation
logic around the fields object so required metadata fields are considered
present only when their YAML values are non-empty, rejecting blank values, null,
and empty strings for description, name, tools, and model. Add regression cases
covering each of these invalid value forms while preserving valid metadata
handling.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: bfb4bccb-cbad-4d72-a6e9-47074c18043a
📒 Files selected for processing (20)
.env.example.github/workflows/ci.yml.nvmrcCLAUDE.mdcommands/build-fix.mdcommands/checkpoint.mdcommands/code-review.mdcommands/eval.mdcommands/learn.mdcommands/orchestrate.mdcommands/refactor-clean.mdcommands/test-coverage.mdcommands/update-codemaps.mdcommands/update-docs.mdcommands/verify.mdscripts/AGENTS.mdscripts/validate-frontmatter.jsskills/eval-harness/SKILL.mdskills/project-guidelines-example/SKILL.mdskills/verification-loop/SKILL.md
| test: | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - uses: actions/checkout@v4 |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- workflow files ---'
git ls-files '.github/workflows/*'
printf '%s\n' '--- ci.yml ---'
cat -n .github/workflows/ci.yml
printf '%s\n' '--- checkout, permissions, and event references ---'
rg -n -C 3 'actions/checkout|persist-credentials|permissions:|pull_request|pull_request_target|GITHUB_TOKEN|github\.token' .github/workflows .github 2>/dev/null || trueRepository: WorldFlowAI/everything-claude-code
Length of output: 1957
🌐 Web query:
WorldFlowAI/everything-claude-code .github/workflows/ci.yml actions/checkout pull_request
💡 Result:
Everything Claude Code (often abbreviated as ECC) is a toolkit for Claude Code that provides agents, commands, skills, rules, and hooks designed to enhance AI-assisted development [1][2]. The project is primarily maintained at the GitHub repository affaan-m/everything-claude-code, which also operates under the short name ECC [2][3]. Regarding your query about.github/workflows/ci.yml, actions/checkout, and pull_request in this context: While the core project documentation focuses on installation via Claude Code plugins and manual configuration of agents, rules, and commands [1][4], repositories like these often include CI/CD pipelines to ensure the stability of the toolkit components [5]. If you are examining or setting up a CI/CD pipeline for this project (or a similar project), a standard.github/workflows/ci.yml file typically includes the actions/checkout action to pull the repository code and uses the pull_request trigger to run automated tests whenever changes are proposed [5][6]. For example, the project's documentation includes examples of E2E (End-to-End) CI/CD integration, which may be defined in files like.github/workflows/e2e.yml, utilizing standard GitHub Actions to install dependencies and execute tests [5][6]. To get started with the toolkit: 1. Installation: The recommended method is to install it as a Claude Code plugin [1][4]. - Add the marketplace: /plugin marketplace add affaan-m/everything-claude-code - Install the plugin: /plugin install everything-claude-code@everything-claude-code 2. Manual Installation: You can clone the repository and manually copy agents, rules, commands, and skills into your ~/.claude/ configuration directory if you require more granular control [1][4]. 3. Updates and Support: The project supports multiple languages (JavaScript, TypeScript, Python, etc.) [3] and provides updates via /plugin update [3]. Note: Be aware that there have been various repositories using the name "WorldFlowAI/everything-claude-code," but the primary, actively maintained development is found at affaan-m/everything-claude-code [1][2]. Ensure you are using the verified repository to avoid unofficial or unmaintained versions [2].
Citations:
- 1: https://github.com/WorldFlowAI/everything-claude-code
- 2: https://github.com/affaan-m/everything-claude-code?tab=readme-ov-file
- 3: 🚀 v1.2.0 Released - Unified Commands & Skills + Python/Django Support affaan-m/ECC#143
- 4: https://github.com/WorldFlowAI/everything-claude-code/blob/main/README.md
- 5: https://github.com/worldflowai/everything-claude-code/blob/main/commands/e2e.md
- 6: https://www.claudepluginhub.com/commands/worldflowai-everything-claude-code/commands/e2e
🌐 Web query:
https://raw.githubusercontent.com/WorldFlowAI/everything-claude-code/main/.github/workflows/ci.yml
💡 Result:
The URL provided points to a GitHub workflow configuration file (ci.yml) within the WorldFlowAI/everything-claude-code repository [1][2]. The WorldFlowAI/everything-claude-code repository is a toolkit for Claude Code, designed to enhance AI-assisted development through a collection of agents, commands, skills, rules, and hooks [1][3]. It is billed as a "complete collection of Claude Code configs" and includes production-ready configurations that have been evolved through extensive use in real-world product development [1][4]. Key details about the repository and its usage include: - Purpose: Provides structured components (agents, skills, commands, rules, hooks) to streamline development workflows, such as code generation, test-driven development, and automated reviews [5][3]. - Installation: Users can install it as a Claude Code plugin via the command line (e.g., /plugin marketplace add) or by manually copying the components into their local Claude configuration directories [1][3]. - Cross-Platform Compatibility: Scripts are implemented in Node.js to support Windows, macOS, and Linux, and the toolkit automatically detects and configures package managers like npm, pnpm, yarn, and bun [3]. The specific file you linked is part of the repository's continuous integration (CI) infrastructure, which automates testing and verification processes for these configurations [1][2].
Citations:
- 1: https://github.com/WorldFlowAI/everything-claude-code
- 2: https://github.com/WorldFlowAI/everything-claude-code/blob/main/README.md
- 3: https://www.sourcepulse.org/projects/31898874
- 4: https://github.com/worldflowai/everything-claude-code
- 5: https://www.claudepluginhub.com/plugins/worldflowai-everything-claude-code
🏁 Script executed:
#!/bin/bash
set -eu
url='https://api.github.com/repos/WorldFlowAI/everything-claude-code/contents/.github/workflows/ci.yml'
curl -fsSL "$url" |
python3 -c 'import json,sys,base64; d=json.load(sys.stdin); print(base64.b64decode(d["content"]).decode())'Repository: WorldFlowAI/everything-claude-code
Length of output: 1957
Disable checkout credential persistence for pull-request code.
Set persist-credentials: false on actions/checkout@v4. Declare only the permissions required by the job, such as contents: read, before running repository-controlled code.
🧰 Tools
🪛 zizmor (1.29.0)
[warning] 13-13: credential persistence through GitHub Actions artifacts (artipacked): does not set persist-credentials: false
(artipacked)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.github/workflows/ci.yml at line 13, Update the actions/checkout@v4 step to
set persist-credentials: false, and declare the job or workflow permissions
explicitly with only the required contents: read access before executing
repository-controlled code.
Sources: MCP tools, Linters/SAST tools
| @@ -0,0 +1 @@ | |||
| 20 | |||
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | 💤 Low value
🧩 Analysis chain
🌐 Web query:
Node.js release schedule support Node 20 end of life April 2026
💡 Result:
Node.js 20 (codename "Iron") reached its official end-of-life (EOL) on April 30, 2026 [1][2]. As of today, August 6, 2026, Node.js 20 is no longer maintained and does not receive updates, including security patches [3][2]. Users still running applications on this version are encouraged to migrate to a currently supported release to avoid potential security vulnerabilities [3][2].
Citations:
- 1: https://github.com/nodejs/Release/
- 2: https://endoflife.ai/nodejs/20
- 3: https://nodejs.org/en/about/eol
Move CI off Node.js 20.
Node.js 20 reached end of life on April 30, 2026 and no longer receives maintenance or security updates. Update .nvmrc to a supported even-numbered LTS line, such as Node.js 22, before running CI.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.nvmrc at line 1, Update the Node.js version specified in .nvmrc from 20 to
a supported even-numbered LTS release, preferably 22, so CI uses a maintained
runtime.
Source: MCP tools
| @@ -1,3 +1,7 @@ | |||
| --- | |||
| description: Create, verify, or list workflow checkpoints. Usage: /checkpoint [create|verify|list] [name]. | |||
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== files =="
git ls-files | rg '(^commands/(checkpoint|eval|orchestrate)\.md$|^CLAUDE\.md$|^scripts/validate-frontmatter\.js$)' || true
echo
echo "== command frontmatter excerpts =="
for f in commands/checkpoint.md commands/eval.md commands/orchestrate.md; do
echo "--- $f ---"
sed -n '1,8p' "$f"
done
echo
echo "== CLAUDE excerpt =="
sed -n '20,28p' CLAUDE.md
echo
echo "== validator outline/search =="
if [ -f scripts/validate-frontmatter.js ]; then
wc -l scripts/validate-frontmatter.js
rg -n "frontmatter|description|Usage|yaml|parse|readFile|front-matter|js-yaml|yaml-safe|try" scripts/validate-frontmatter.js
fi
echo
echo "== validator file relevant sections =="
if [ -f scripts/validate-frontmatter.js ]; then
sed -n '1,220p' scripts/validate-frontmatter.js
fi
echo
echo "== deterministic frontmatter YAML parse probe =="
python3 - <<'PY'
from pathlib import Path
try:
import yaml
except Exception as e:
print("pyyaml_unavailable:", repr(e))
yaml = None
for path in ["commands/checkpoint.md", "commands/eval.md", "commands/orchestrate.md"]:
text = Path(path).read_text()
print(f"-- {path} --")
print(text.splitlines()[0:3])
try:
# Emulate simple YAML frontmatter extraction then parse as plain YAML scalar.
if text.startswith("---\n") and "---\n" in text[4:]:
body = text.split("---\n", 1)[1]
end = body.index("---")
fm = body[:end]
else:
fm = ""
parsed = yaml.safe_load(fm) if yaml else None
print("yaml_safe_load_description:", repr(parsed.get("description")) if parsed else "no yaml")
except Exception as e:
print("yaml_parse_error:", repr(e))
PYRepository: WorldFlowAI/everything-claude-code
Length of output: 1957
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== files =="
git ls-files | rg '(^commands/(checkpoint|eval|orchestrate)\.md$|^CLAUDE\.md$|^scripts/validate-frontmatter\.js$)' || true
echo
echo "== command frontmatter excerpts =="
for f in commands/checkpoint.md commands/eval.md commands/orchestrate.md; do
echo "--- $f ---"
sed -n '1,8p' "$f"
done
echo
echo "== CLAUDE excerpt =="
sed -n '20,28p' CLAUDE.md
echo
echo "== validator outline/search =="
if [ -f scripts/validate-frontmatter.js ]; then
wc -l scripts/validate-frontmatter.js
rg -n "frontmatter|description|Usage|yaml|parse|readFile|front-matter|js-yaml|yaml-safe|try" scripts/validate-frontmatter.js
fi
echo
echo "== validator file relevant sections =="
if [ -f scripts/validate-frontmatter.js ]; then
sed -n '1,220p' scripts/validate-frontmatter.js
fi
echo
echo "== deterministic frontmatter YAML parse probe =="
python3 - <<'PY'
from pathlib import Path
try:
import yaml
except Exception as e:
print("pyyaml_unavailable:", repr(e))
yaml = None
for path in ["commands/checkpoint.md", "commands/eval.md", "commands/orchestrate.md"]:
text = Path(path).read_text()
print(f"-- {path} --")
print(text.splitlines()[0:3])
try:
if text.startswith("---\n") and "---\n" in text[4:]:
body = text.split("---\n", 1)[1]
end = body.index("---")
fm = body[:end]
else:
fm = ""
parsed = yaml.safe_load(fm) if yaml else None
print("yaml_safe_load_description:", repr(parsed.get("description")) if parsed else "no yaml")
except Exception as e:
print("yaml_parse_error:", repr(e))
PYRepository: WorldFlowAI/everything-claude-code
Length of output: 1957
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== repo files present? =="
git rev-parse --show-toplevel 2>/dev/null || true
git ls-files | rg '(^commands/(checkpoint|eval|orchestrate)\.md$|^CLAUDE\.md$|^scripts/validate-frontmatter\.js$)' || true
echo
echo "== command frontmatter excerpts =="
for f in commands/checkpoint.md commands/eval.md commands/orchestrate.md; do
echo "--- $f ---"
sed -n '1,8p' "$f" 2>/dev/null || echo "missing: $f"
done
echo
echo "== CLAUDE excerpt =="
sed -n '20,28p' CLAUDE.md 2>/dev/null || true
echo
echo "== parser probe =="
python3 - <<'PY'
try:
import yaml
except Exception as e:
print("py_yaml_unavailable:", str(e))
yaml = None
for path in ["commands/checkpoint.md", "commands/eval.md", "commands/orchestrate.md"]:
try:
text = path.read_text() if hasattr(path, "read_text") else open(path, encoding="utf-8").read()
except Exception as e:
print(f"-- {path} missing/unreadable: {e}")
continue
body = text.split("---\n", 1)[1] if text.startswith("---\n") else ""
end = body.index("---") if "---\n" in body else len(body)
fm = body[:end].rstrip()
desc = None
err = None
if yaml:
try:
doc = yaml.safe_load(fm)
desc = doc.get("description") if isinstance(doc, dict) else None
except Exception as e:
err = str(e)
print(f"-- {path} --")
print(f"frontmatter:{repr(fm[:200])}")
print(f"yaml_safe_load_desc:{repr(desc)}")
print(f"yaml_safe_load_err:{err}")
PY
echo
echo "== validator relevant inspection =="
if [ -f scripts/validate-frontmatter.js ]; then
wc -l scripts/validate-frontmatter.js
rg -n "frontmatter|description|Usage|yaml|parse|findFiles|readFile|require|import|front-matter|js-yaml|yaml" scripts/validate-frontmatter.js
sed -n '1,260p' scripts/validate-frontmatter.js
else
echo "scripts/validate-frontmatter.js missing"
fiRepository: WorldFlowAI/everything-claude-code
Length of output: 1957
Use one parser-safe frontmatter contract.
The command descriptions include Usage: in unquoted YAML scalars, which YAML parsers can read as a nested object instead of a description string. Quote the full description value in each command file and make the frontmatter validator parse YAML before checking values, not only field names.
- Quote
descriptionincommands/checkpoint.md,commands/eval.md, andcommands/orchestrate.md. - Update
scripts/validate-frontmatter.jsand theCLAUDE.mdreference so bad YAML is caught before commit.
📍 Affects 4 files
commands/checkpoint.md#L2-L2(this comment)commands/eval.md#L2-L2commands/orchestrate.md#L2-L2CLAUDE.md#L24-L25
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@commands/checkpoint.md` at line 2, Use a parser-safe frontmatter contract:
quote the full description value in commands/checkpoint.md:2,
commands/eval.md:2, and commands/orchestrate.md:2. Update
scripts/validate-frontmatter.js to parse YAML before validating field values so
malformed YAML is rejected, and update the CLAUDE.md reference at lines 24-25 to
document or invoke this validation before commits.
Source: Coding guidelines
| const fields = {}; | ||
| for (const line of match[1].split(/\r?\n/)) { | ||
| const fieldMatch = line.match(/^([A-Za-z_-]+):/); | ||
| if (fieldMatch) fields[fieldMatch[1]] = true; |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Reject empty or null required values.
Lines 39-40 mark description:, name:, tools:, or model: null as present. The validator can then report success while Claude Code cannot discover or use the metadata. Parse the YAML values and require non-empty values for required fields. Add regression cases for blank, null, and empty-string values.
Suggested validation change
- const fieldMatch = line.match(/^([A-Za-z_-]+):/);
- if (fieldMatch) fields[fieldMatch[1]] = true;
+ const fieldMatch = line.match(/^([A-Za-z_-]+):\s*(.*)$/);
+ const value = fieldMatch?.[2].trim();
+ if (fieldMatch && value && value !== 'null' && value !== '~') {
+ fields[fieldMatch[1]] = value;
+ }🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@scripts/validate-frontmatter.js` around lines 37 - 40, Update the frontmatter
field parsing in the validation logic around the fields object so required
metadata fields are considered present only when their YAML values are
non-empty, rejecting blank values, null, and empty strings for description,
name, tools, and model. Add regression cases covering each of these invalid
value forms while preserving valid metadata handling.
1 participant
Fixes #6
What
Fixes 14 files with missing/broken Claude Code frontmatter and closes several
structural gaps (no project entry point, no CI, no scoped instructions)
found by running this repo through AgentCompass — an open-source,
deterministic static analyzer that scores how ready a repo is for AI coding
agents (GitHub Copilot / Claude Code). Live tool:
https://agentcompass.ashymeadow-b5411f47.eastus.azurecontainerapps.io/?repo=WorldFlowAI%2Feverything-claude-code
(project: https://github.com/YoavLax/agent-compass)
Score
You can reproduce the "after" number yourself by pointing the live tool at
this branch:
?repo=YoavLax/everything-claude-code&ref=fix/skill-frontmatter.Why these specific changes
1. Missing skill frontmatter (the original bug that triggered this PR)
skills/eval-harness/SKILL.md,skills/project-guidelines-example/SKILL.md,and
skills/verification-loop/SKILL.mdhad no YAML frontmatter at all.Per the Claude Code Agent Skills format,
name+descriptionfrontmatter is what Claude uses to discover and routeto a skill — without it, these 3 skills are silently invisible even though
their content is complete and useful. Fixed to match the pattern already
used by the other 8 skills (
tdd-workflow,coding-standards, etc).2. Missing command frontmatter (11 files)
commands/build-fix.md,checkpoint.md,code-review.md,eval.md,learn.md,orchestrate.md,refactor-clean.md,test-coverage.md,update-codemaps.md,update-docs.md, andverify.mdhad nodescriptionfield, inconsistent with the other 4 commands (
tdd.md,plan.md,e2e.md,setup-pm.md) and invisible in the Claude Code/command picker. Added aone-line description to each based on the command's existing body.
3. No project entry point (
CLAUDE.md)This is a Claude Code plugin repo with no root
CLAUDE.md— Claude Codestarts every session here with zero project context. Added one covering the
repo's structure, contribution conventions (frontmatter requirements for
agents/commands/skills), and the test command.
4. No CI (
.github/workflows/ci.yml)The repo already has a real test suite (
tests/run-all.js, 62 tests) butnothing ran it automatically. Added a workflow that runs it on every push/PR,
plus a new
scripts/validate-frontmatter.jslint step that checks requiredfrontmatter across
agents/*.md,commands/*.md, andskills/**/SKILL.md—this would have caught issues #1 and #2 automatically.
5. No scoped instructions (
scripts/AGENTS.md)Added a nested
AGENTS.mddocumenting conventions specific to thecross-platform Node.js
scripts/directory (package-manager detection, hookimplementations, test pairing).
6. Tooling gaps (
.env.example,.nvmrc).gitignoreexcludes.envbut nothing documented the variables actuallyread by
scripts/(CLAUDE_PACKAGE_MANAGER,CLAUDE_TRANSCRIPT_PATH,CLAUDE_SESSION_ID,COMPACT_THRESHOLD). Added.env.exampledocumentingthem, and
.nvmrcpinning Node 20 for the scripts toolchain.Verification
No existing files were removed or restructured — every change is additive
(new file) or a frontmatter addition to an existing file's existing content.