Skip to content

docs(skill): remove broken doc references and unused compatibility field#1956

Open
bearomorphism wants to merge 1 commit intomasterfrom
docs/skill-md-cleanup
Open

docs(skill): remove broken doc references and unused compatibility field#1956
bearomorphism wants to merge 1 commit intomasterfrom
docs/skill-md-cleanup

Conversation

@bearomorphism
Copy link
Copy Markdown
Collaborator

@bearomorphism bearomorphism commented May 9, 2026

Description

Cleans up .agents/skills/commitizen/SKILL.md based on feedback in #1936 (comment) and the Agent Skills specification.

  • Remove the Suggested references section. The section listed paths like docs/commands/commit.md that are relative to the repo root, not the skill root. Per the spec, file references in a SKILL.md should 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 via metadata.docs in the frontmatter.
  • Drop the compatibility frontmatter 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?

  • Yes (please specify the tool below)

Generated-by: GitHub Copilot CLI (Claude Opus 4.7) following the guidelines

Code Changes

  • Add test cases to all the changes you introduce
  • Run uv run poe all locally to ensure this change passes linter check and tests
  • Manually test the changes:
    • Verify the feature/bug fix works as expected in real-world scenarios
    • Test edge cases and error conditions
    • Ensure backward compatibility is maintained
    • Document any manual testing steps performed
  • Update the documentation for the changes

N/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

  • Run uv run poe doc locally to ensure the documentation pages renders correctly
  • Check and fix any broken links (internal or external)

SKILL.md is not part of the MkDocs site; it is consumed by Agent Skills clients. The change removes broken links rather than introducing new ones, and the metadata.docs URL was verified to point at the live docs site.

Expected Behavior

  • Agent Skills clients that load .agents/skills/commitizen/SKILL.md no longer see references to docs/... paths that do not exist when the skill folder is installed standalone.
  • The frontmatter remains spec-valid (no required fields removed), so existing clients continue to discover and activate the skill.
  • Agents looking for canonical documentation can still find it via metadata.docs (https://commitizen-tools.github.io/commitizen/).

Steps to Test This Pull Request

  1. Check out this branch and open .agents/skills/commitizen/SKILL.md.
  2. Confirm the YAML frontmatter parses (e.g. 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)").
  3. Confirm there is no compatibility: key and no ## Suggested references section.
  4. Validate against the spec rules in https://agentskills.io/specification.md (required name and description are present and within length limits).

Additional Context

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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant