docs(skill): remove broken doc references and unused compatibility field#1956
Open
bearomorphism wants to merge 1 commit intomasterfrom
Open
docs(skill): remove broken doc references and unused compatibility field#1956bearomorphism wants to merge 1 commit intomasterfrom
bearomorphism wants to merge 1 commit intomasterfrom
Conversation
The `Suggested references` section listed paths relative to the repo root (e.g. `docs/commands/commit.md`), but per the Agent Skills specification, file references should be relative to the skill root. When the skill folder is installed standalone, those paths do not resolve, so the section was effectively dead pointers. Drop the section and rely on agent inference / the documented `metadata.docs` URL for the canonical docs. Also drop the `compatibility` frontmatter field. The spec notes most skills do not need it, and the previous value did not describe a constraint that would prevent the skill from running. Refs #1936 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
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.
Description
Cleans up
.agents/skills/commitizen/SKILL.mdbased on feedback in #1936 (comment) and the Agent Skills specification.Suggested referencessection. The section listed paths likedocs/commands/commit.mdthat are relative to the repo root, not the skill root. Per the spec, file references in aSKILL.mdshould be relative to the skill root, and skill folders are typically distributed standalone, so those references could not resolve. The canonical docs URL remains discoverable viametadata.docsin the frontmatter.compatibilityfrontmatter field. The spec notes that "most skills do not need" this field, and the previous value (Git repository with Python and Commitizen available...) did not describe a constraint that would actually prevent the skill from running.Checklist
Was generative AI tooling used to co-author this PR?
Generated-by: GitHub Copilot CLI (Claude Opus 4.7) following the guidelines
Code Changes
uv run poe alllocally to ensure this change passes linter check and testsN/A: no code changes; only updates to
.agents/skills/commitizen/SKILL.md. No new test cases needed. SKILL.md frontmatter still validates as YAML and the body still parses as Markdown.Documentation Changes
uv run poe doclocally to ensure the documentation pages renders correctlySKILL.mdis not part of the MkDocs site; it is consumed by Agent Skills clients. The change removes broken links rather than introducing new ones, and themetadata.docsURL was verified to point at the live docs site.Expected Behavior
.agents/skills/commitizen/SKILL.mdno longer see references todocs/...paths that do not exist when the skill folder is installed standalone.metadata.docs(https://commitizen-tools.github.io/commitizen/).Steps to Test This Pull Request
.agents/skills/commitizen/SKILL.md.python -c "import yaml,pathlib,re; t=pathlib.Path('.agents/skills/commitizen/SKILL.md').read_text(); fm=re.match(r'---\n(.*?)\n---', t, re.S).group(1); yaml.safe_load(fm)").compatibility:key and no## Suggested referencessection.nameanddescriptionare present and within length limits).Additional Context
compatibilityis optional and most skills do not need it): https://agentskills.io/specification.md