Repository navigation
docs(skill-evals): fix eval README links that 404 on GitHub - #2157
Conversation
Both linked to ../../skills/, which resolves under tools/skill-evals/. Use ../../../../skills/ like the other eval READMEs. A scan of all tracked Markdown found no other broken relative links or anchors. Generated-by: Claude Code (Opus 5.5)
Generated-by: Claude Code (Opus 5.5)
Generated-by: Claude Code (Opus 5.5)
Kaap10
left a comment
There was a problem hiding this comment.
@KatalKavya96 Thanks for catching and cleaning these up!
Fixing these six eval README links resolves #2156. Navigating through directory symlinks (or pointing at non-existent sibling tools/skill-evals/skills/ paths) leads to immediate 404s in GitHub's web interface.
correctness: plugin alias resolution (tools/skill-evals/evals/*/README.md)
No source rule covers this. It is a path resolution check across plugin family aliases.
Verified the relative paths and directory depth:
tools/skill-evals/evals/<suite>/has directory depth 4, so../../../../correctly returns to the repo root before enteringplugins/.- Crucially, this accurately accounts for shortened plugin folder names where the directory under
plugins/magpie-<family>/skills/differs from the framework symlink alias (e.g.calibrateinstead ofcontributor-calibrate,candidate-screeninstead ofcontributor-candidate-screen,verify-rcinstead ofrelease-verify-rc). - Tested all six target files locally; all exist and resolve cleanly.
Smaller observations
tooling:ci— Lychee / CI blindspot: Good explanation in the PR description regarding why lychee did not catch these:.lychee.tomlexcludestools/skill-evals/evalsto protect test fixtures, and local filesystem link checkers traverse symlinks transparently whereas GitHub's web tree viewer does not.scope— Docs-wide symlink issue: Deferring the ~400 symlink occurrences indocs/to a separate issue/convention discussion is the right call to keep this PR minimal and immediately mergeable.- Grepped across all eval READMEs: there are no remaining broken relative links in
tools/skill-evals/evals/*/README.md.
LGTM!
This review was drafted by an AI-assisted tool and
confirmed by an Apache Magpie maintainer. The findings
below are observations, not blockers; an Apache Magpie
maintainer — a real person — will take the next look at the
PR. If you think a finding is mis-applied, please reply on
the PR and a maintainer will weigh in.More on how Apache Magpie handles maintainer review:
Contributing guide.
Summary
../../skills/…, which resolves undertools/skill-evals/skills/and does not exist (good-first-issue-sweep,skill-reconciler);skills/<name>symlink, which GitHub's web view does not follow (contributor-calibrate,contributor-candidate-screen,contributor-to-committer,release-verify-rc).plugins/magpie-<family>/skills/<alias>/…path, asrelease-announce-draft/README.mdalready does. That path resolves on GitHub, locally, and in lychee.Type of change
.claude/skills/<name>/) — eval fixtures updated belowtools/<system>/*.md)tools/*/withpyproject.toml)docs/,README.md,CONTRIBUTING.md)projects/_template/)prek, workflows, validators)Test plan
prek run --fileson the changed files passesplugins/, and no eval README links throughskills/any more.RFC-AI-0004 compliance
Not applicable (docs-only link fix).
Linked issues
Closes #2156
Notes for reviewers (optional)
.lychee.tomlexcludes all oftools/skill-evals/evals, which is meant for fixtures. It can't catch the symlink 404s either, because it reads the local filesystem, where symlinks resolve.docs/go throughskills/and also 404 on GitHub. That's a convention question (human docs vs agent-read files), so I'll raise it in its own issue rather than change it here.