Skip to content

docs(skill): point install guidance at docs README#1953

Open
bearomorphism wants to merge 1 commit intocommitizen-tools:masterfrom
bearomorphism:docs/skill-install-pipx
Open

docs(skill): point install guidance at docs README#1953
bearomorphism wants to merge 1 commit intocommitizen-tools:masterfrom
bearomorphism:docs/skill-install-pipx

Conversation

@bearomorphism
Copy link
Copy Markdown
Collaborator

Description

Follow-up to #1949 addressing review feedback from @philipp-horstenkamp:

Shouldn't this be pipx or uv?

The merged .agents/skills/commitizen/SKILL.md advertised pip install commitizen as the install command, but docs/README.md recommends pipx install commitizen or uv tool install commitizen for global installs of the cz CLI; pip install -U commitizen is documented only as a project-specific install.

Changes

  • Frontmatter install: updated from pip install commitizen to pipx install commitizen to match the docs' primary recommendation.
  • Replaced the inline install command list in Important domain details (which had the same pip/uv add discrepancy) with a short pointer that defers to docs/README.md's Installation section.
  • Added an Installation: entry under Suggested references, matching the file's existing pattern of referencing docs/...md.

Why a pointer instead of duplicating the matrix

Keeping the full install command list in two places was the root cause of the original review comment: the SKILL.md had drifted from the docs. Pointing at docs/README.md makes the docs the single source of truth. The frontmatter still carries one canonical command because the Agent Skills spec expects a literal command there.

Why not extract a separate docs/installation.md

That was considered, but it expands scope (mkdocs nav + llmstxt config + risk of breaking external links to the README's #installation anchor) beyond the original review concern. It can be a separate proposal if desired.

Checklist

Was generative AI tooling used to co-author this PR?

  • Yes (GitHub Copilot CLI)

Generated-by: GitHub Copilot CLI following the guidelines

Code Changes

  • Add test cases to all the changes you introduce (N/A - docs only)
  • Run uv run poe all locally to ensure this change passes linter check and tests (no Python files touched; pre-commit hooks pass on push)
  • Manually test the changes:
    • Verify the feature/bug fix works as expected in real-world scenarios (verified install commands match docs/README.md lines 62-122)
    • Test edge cases and error conditions
    • Ensure backward compatibility is maintained
  • Update the documentation for the changes

Documentation Changes

  • Run uv run poe doc locally to ensure the documentation pages renders correctly (only .agents/skills/commitizen/SKILL.md changed, not part of the mkdocs site)
  • Check and fix any broken links (internal or external) - verified docs/README.md reference is valid

Steps to Test This Pull Request

  1. Open .agents/skills/commitizen/SKILL.md.
  2. Confirm the frontmatter install: is pipx install commitizen.
  3. Confirm the Important domain details item points to docs/README.md rather than listing install commands inline.
  4. Confirm Suggested references contains an Installation entry pointing to docs/README.md.

Additional Context

Addresses unresolved review feedback from #1949 (already merged).

The SKILL.md install hint advertised `pip install commitizen`, but the
project README recommends a global, isolated install via pipx or uv for
the `cz` CLI; plain pip is documented only for project-specific
installs. Switch to `pipx install commitizen` to match the primary
recommendation in docs/README.md.

Addresses review feedback on commitizen-tools#1949.

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