docs: add Agent Skills SKILL.md

[bearomorphism]

Description

Add a SKILL.md following the Agent Skills spec at .agents/skills/commitizen/SKILL.md, so AI agents working in this repo can auto-discover Commitizen's capabilities.

The file provides concise guidance on command selection, configuration discovery, versioning, changelog generation, CI workflows, and exit-code handling.

Checklist

• I have read the contributing guidelines

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
• 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

Documentation Changes

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

Expected Behavior

Agents supporting the Agent Skills format (Claude Code, VS Code/Copilot, Cursor, Gemini CLI, OpenAI Codex, etc.) can auto-discover the skill at .agents/skills/commitizen/SKILL.md when working in this repo.

Steps to Test This Pull Request

1. Verify .agents/skills/commitizen/SKILL.md exists
2. Check YAML frontmatter includes required name and description fields
3. Verify directory name (commitizen) matches the name field in frontmatter

Additional Context

Part of #1936. The llms.txt portion is addressed in PR #1948.

Moved from repo root to .agents/skills/commitizen/ based on research showing that compliant agents scan .agents/skills/<name>/ directories, not the repo root. See PR comment for full research findings.

[Copilot]

Pull request overview

Adds a root-level SKILL.md documenting Commitizen usage for agentic workflows (command selection, config discovery, bump/changelog safety, CI considerations) in the Agent Skills format.

Changes:

• Introduces SKILL.md with YAML frontmatter (name, description, etc.) and Commitizen-oriented guidance.
• Documents config discovery order, safe/read-only command patterns, and bump/changelog operational cautions.
• Adds curated links to existing command/config/CI/exit-code documentation plus a few CLI examples.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[bearomorphism]

Validation

Verified that all review comments have been addressed:

• Install syntax: Changed pip install commitizen | uv add commitizen to pip install commitizen (quoted string, no ambiguous pipe) ✅
• PR scope: Changed 'Closes Provide a skill for agentic coding #1936' to 'Part of Provide a skill for agentic coding #1936' since this PR only covers SKILL.md; llms.txt is in PR docs: add llms.txt via mkdocs-llmstxt plugin #1948 ✅
• Agent Skills spec: Frontmatter includes required name and description fields ✅
• Command accuracy: All commands and flags verified against commitizen/cli.py ✅
• Doc references: All referenced doc paths exist in the repo ✅
• Safety guidance: Warns about destructive cz bump operations ✅

Currently researching whether SKILL.md at the repo root follows the intended Agent Skills discovery pattern. Will update with findings.

[bearomorphism]

Research Findings on Agent Skills Discovery

After researching the Agent Skills spec and how agents actually discover skills:

SKILL.md at the repo root will NOT be auto-discovered by any agent. The spec requires skills to live in a named subdirectory within a skills folder:

Scope	Scan path
Project	<project>/.agents/skills//SKILL.md\
User	~/.agents/skills//SKILL.md\
Client-specific	<project>/./skills//SKILL.md\

35 agents support this format (Claude Code, VS Code/Copilot, Cursor, Gemini CLI, OpenAI Codex, etc.), but they all scan these specific directories — not the repo root.

Recommendation: Move \SKILL.md\ to .agents/skills/commitizen/SKILL.md\ so agents working within this repo can discover it automatically. This also satisfies the spec constraint that the directory name must match the
ame\ field in frontmatter.

Note: No other major Python CLI tool (ruff, black, pytest, pre-commit) has adopted SKILL.md yet — commitizen would be an early adopter.