Repository navigation
docs: host the agent skill's references as docs pages - #298
Merged
Merged
Conversation
Codex Review Summary: ✅ CompletedThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
The docs site serves only SKILL.md of the agent skill (at /.well-known/skills/ and as an MCP resource), so its links to references/*.md returned 404 there. Symlink the references into docs/ as hidden pages (the deploy step's `cp -rL` copies them) and redirect /.well-known/skills/simulating-circuits-with-tsim/references/:slug to them, so the skill's relative links resolve on the site. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
rafaelha
force-pushed
the
docs/skill-absolute-links
branch
from
November 12, 2026 22:51
aa75643 to
04f372f
Compare
rafaelha
changed the title
Contributor
☂️ Code Coverage
Overall Coverage
New FilesNo new covered files... Modified FilesNo covered modified files...
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
The docs site publishes the agent skill at
/.well-known/skills/simulating-circuits-with-tsim/SKILL.mdand as the MCP resourcemintlify://skills/simulating-circuits-with-tsim, but Mintlify serves onlySKILL.md:.well-known/skills/index.jsonlists"files": ["SKILL.md"].references/qec-experiments.md,references/decoders.mdandreferences/porting.mdreturn 404 under/.well-known/skills/simulating-circuits-with-tsim/.So the skill's links to its references are broken for agents that get it from the site.
Fix
docs/skill-references: a symlink toskills/simulating-circuits-with-tsim/references. Mintlify serves the three files as hidden pages, not in the navigation:/tsim/skill-references/<name>and the Markdown at/tsim/skill-references/<name>.md. The deploy step already copiesdocs/withcp -rL, so the files land ondocs-siteas real files, the same way the skill does.docs/docs.json: redirect/.well-known/skills/simulating-circuits-with-tsim/references/:slugto/skill-references/:slug, so the skill's relative links (references/decoders.md) resolve to those pages.SKILL.mdis unchanged, and installed copies keep reading their local files.Verification
mint dev,/skill-references/decodersreturns the page and/skill-references/decoders.mdreturns the Markdown, with a short Mintlify index note at the top. Links between the references resolve.mint validateandmint broken-links --check-anchors --check-redirects --check-snippetspass, ondocs/and on acp -rLcopy like the deploy step's.uv run tsim-dev test test/unit/test_skills.py: 9 passed. pre-commit passes.Not verified: the redirect.
mint devapplies nodocs.jsonredirects (it 404s even on a test redirect between ordinary paths) and does not serve/.well-known/, so it can only be checked on the deployed site with:The pages are hidden, so they may not appear in the MCP server's search or its docs filesystem, which lists only pages in the navigation.
No changelog entry: the skill itself is still unreleased.
🤖 Generated with Claude Code