conventional-git 1.2.0__tar.gz → 2.1.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (182) hide show
  1. {conventional_git-1.2.0 → conventional_git-2.1.1}/.claude-plugin/plugin.json +1 -1
  2. {conventional_git-1.2.0 → conventional_git-2.1.1}/.gitignore +3 -0
  3. {conventional_git-1.2.0 → conventional_git-2.1.1}/.pre-commit-config.yaml +7 -0
  4. conventional_git-2.1.1/AGENTS.md +115 -0
  5. {conventional_git-1.2.0 → conventional_git-2.1.1}/CONTRIBUTING.md +4 -1
  6. {conventional_git-1.2.0 → conventional_git-2.1.1}/Makefile +31 -2
  7. {conventional_git-1.2.0 → conventional_git-2.1.1}/PKG-INFO +33 -21
  8. {conventional_git-1.2.0 → conventional_git-2.1.1}/README.md +32 -20
  9. {conventional_git-1.2.0 → conventional_git-2.1.1}/dictionary.txt +2 -0
  10. conventional_git-2.1.1/docs/agents/agent-skills-format.md +68 -0
  11. conventional_git-2.1.1/docs/agents/claude-code-install-scopes.md +50 -0
  12. conventional_git-2.1.1/docs/agents/claude-code-marketplace-install.md +67 -0
  13. conventional_git-2.1.1/docs/agents/claude-code-plugin-updates.md +71 -0
  14. conventional_git-2.1.1/docs/agents/claude-code-shell-install.md +58 -0
  15. conventional_git-2.1.1/docs/agents/claude-code-skill-invocation.md +52 -0
  16. conventional_git-2.1.1/docs/agents/index.md +50 -0
  17. conventional_git-2.1.1/docs/agents/install-channels.md +65 -0
  18. conventional_git-2.1.1/docs/agents/npx-skills-install.md +65 -0
  19. conventional_git-2.1.1/docs/agents/npx-skills-manage.md +58 -0
  20. conventional_git-2.1.1/docs/agents/opencode-mcp-config.md +83 -0
  21. conventional_git-2.1.1/docs/agents/opencode-mcp-server.md +68 -0
  22. conventional_git-2.1.1/docs/agents/opencode-skill-discovery.md +50 -0
  23. conventional_git-2.1.1/docs/agents/opencode-skill-permissions.md +48 -0
  24. conventional_git-2.1.1/docs/agents/plugin-identity.md +73 -0
  25. conventional_git-2.1.1/docs/conventions/claude-md-check.md +21 -0
  26. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/conventions/commits-check.md +12 -3
  27. conventional_git-2.1.1/docs/conventions/help-check.md +22 -0
  28. conventional_git-2.1.1/docs/conventions/index.md +17 -0
  29. conventional_git-2.1.1/docs/conventions/tag-vocabulary.md +28 -0
  30. conventional_git-2.1.1/docs/conventions/versioning.md +47 -0
  31. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/enforcement/attribution-trailers.md +3 -2
  32. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/enforcement/git-hooks.md +1 -1
  33. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/enforcement/hook-install-path.md +1 -1
  34. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/enforcement/pre-commit-framework.md +1 -1
  35. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/enforcement/pre-commit-local-hooks.md +3 -3
  36. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/gitlint/install.md +1 -1
  37. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/index.md +5 -0
  38. conventional_git-2.1.1/docs/log.md +126 -0
  39. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/mcp/index.md +7 -0
  40. conventional_git-2.1.1/docs/mcp/no-auth-tools.md +23 -0
  41. conventional_git-2.1.1/docs/mcp/out-of-band-auth.md +39 -0
  42. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/mcp/plugin-bundled-server.md +9 -0
  43. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/mcp/suggest-commit-message.md +29 -0
  44. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/python/interpreter-source.md +1 -1
  45. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/toolchain/index.md +4 -0
  46. conventional_git-2.1.1/docs/toolchain/layering-rule.md +28 -0
  47. conventional_git-2.1.1/docs/toolchain/retag-notes.md +29 -0
  48. conventional_git-2.1.1/docs/toolchain/sh-uid-unused.md +23 -0
  49. {conventional_git-1.2.0 → conventional_git-2.1.1}/mk/python.mk +10 -3
  50. conventional_git-2.1.1/okf-base.yaml +42 -0
  51. {conventional_git-1.2.0 → conventional_git-2.1.1}/package.json +2 -2
  52. {conventional_git-1.2.0 → conventional_git-2.1.1}/pnpm-lock.yaml +120 -120
  53. {conventional_git-1.2.0 → conventional_git-2.1.1}/pyproject.toml +4 -3
  54. conventional_git-2.1.1/skills/conventional-auth/SKILL.md +67 -0
  55. {conventional_git-1.2.0 → conventional_git-2.1.1}/skills/conventional-branch/SKILL.md +1 -3
  56. {conventional_git-1.2.0 → conventional_git-2.1.1}/skills/conventional-commit/SKILL.md +8 -9
  57. conventional_git-2.1.1/skills/conventional-suggest/SKILL.md +86 -0
  58. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/adapters/gitlint_rules.py +6 -3
  59. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/cli/check.py +1 -0
  60. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/cli/create.py +13 -14
  61. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/commit/rules.py +3 -1
  62. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/commit/vocabulary.py +2 -0
  63. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/config.py +2 -0
  64. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/helpers.py +3 -0
  65. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/mcp/server.py +1 -0
  66. {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_cli_smoke.py +53 -4
  67. {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_commit_rules.py +18 -0
  68. {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_commit_vocabulary.py +15 -0
  69. {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_config.py +20 -0
  70. {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_gitlint_rules.py +19 -0
  71. {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_helpers.py +16 -0
  72. conventional_git-2.1.1/tests/test_sh_uid_unused.py +39 -0
  73. conventional_git-2.1.1/tools/docs-retag.py +141 -0
  74. {conventional_git-1.2.0 → conventional_git-2.1.1}/uv.lock +12 -12
  75. conventional_git-1.2.0/AGENTS.md +0 -80
  76. conventional_git-1.2.0/docs/conventions/index.md +0 -9
  77. conventional_git-1.2.0/docs/log.md +0 -70
  78. conventional_git-1.2.0/docs/toolchain/layering-rule.md +0 -35
  79. {conventional_git-1.2.0 → conventional_git-2.1.1}/.claude-plugin/marketplace.json +0 -0
  80. {conventional_git-1.2.0 → conventional_git-2.1.1}/.editorconfig +0 -0
  81. {conventional_git-1.2.0 → conventional_git-2.1.1}/.github/dependabot.yml +2 -2
  82. {conventional_git-1.2.0 → conventional_git-2.1.1}/.github/workflows/ci.yml +0 -0
  83. {conventional_git-1.2.0 → conventional_git-2.1.1}/.github/workflows/publish.yml +0 -0
  84. {conventional_git-1.2.0 → conventional_git-2.1.1}/.github/workflows/python.yml +0 -0
  85. {conventional_git-1.2.0 → conventional_git-2.1.1}/.markdownlint-cli2.jsonc +0 -0
  86. {conventional_git-1.2.0 → conventional_git-2.1.1}/.markdownlint.yaml +0 -0
  87. {conventional_git-1.2.0 → conventional_git-2.1.1}/.mcp.json +0 -0
  88. {conventional_git-1.2.0 → conventional_git-2.1.1}/.pre-commit-hooks.yaml +0 -0
  89. {conventional_git-1.2.0 → conventional_git-2.1.1}/LICENSE +0 -0
  90. {conventional_git-1.2.0 → conventional_git-2.1.1}/checkmake.ini +0 -0
  91. {conventional_git-1.2.0 → conventional_git-2.1.1}/cspell.config.yaml +0 -0
  92. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/architecture/index.md +0 -0
  93. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/architecture/optional-extras.md +0 -0
  94. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/architecture/three-layers.md +0 -0
  95. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/architecture/validation-vs-generation.md +0 -0
  96. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/architecture/violation-contract.md +0 -0
  97. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/architecture/vocabulary-as-data.md +0 -0
  98. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/conventions/commits-and-branches.md +0 -0
  99. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/enforcement/branch-name-gap.md +0 -0
  100. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/enforcement/ci-recipe.md +0 -0
  101. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/enforcement/commitizen-adapter.md +0 -0
  102. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/enforcement/house-rules.md +0 -0
  103. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/enforcement/index.md +0 -0
  104. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/enforcement/skill-vocabulary-copies.md +0 -0
  105. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/gitlint/behavior-vs-cli.md +0 -0
  106. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/gitlint/extra-path.md +0 -0
  107. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/gitlint/index.md +0 -0
  108. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/gitlint/recommended-config.md +0 -0
  109. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/gitlint/when-to-use.md +0 -0
  110. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/gitlint/wiring.md +0 -0
  111. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/mcp/describe-convention.md +0 -0
  112. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/mcp/self-correction-loop.md +0 -0
  113. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/mcp/server-install.md +0 -0
  114. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/mcp/validate-tools.md +0 -0
  115. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/python/index.md +0 -0
  116. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/python/pyproject-defaults.md +0 -0
  117. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/release/index.md +0 -0
  118. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/release/pypi-trusted-publishing.md +0 -0
  119. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/suggestions/apply-does-not-commit.md +0 -0
  120. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/suggestions/data-egress.md +0 -0
  121. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/suggestions/index.md +0 -0
  122. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/suggestions/keyring-scope.md +0 -0
  123. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/suggestions/llm-extra-install.md +0 -0
  124. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/suggestions/provider-fallback.md +0 -0
  125. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/suggestions/providers-and-credentials.md +0 -0
  126. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/toolchain/extras-self-reference.md +0 -0
  127. {conventional_git-1.2.0 → conventional_git-2.1.1}/docs/toolchain/rejected-install-backends.md +0 -0
  128. {conventional_git-1.2.0 → conventional_git-2.1.1}/mise.toml +0 -0
  129. {conventional_git-1.2.0 → conventional_git-2.1.1}/mk/.gitkeep +0 -0
  130. {conventional_git-1.2.0 → conventional_git-2.1.1}/mk/conventional-git.mk +0 -0
  131. {conventional_git-1.2.0 → conventional_git-2.1.1}/pnpm-workspace.yaml +0 -0
  132. {conventional_git-1.2.0 → conventional_git-2.1.1}/skills/conventional-branch/references/branch-types.csv +0 -0
  133. {conventional_git-1.2.0 → conventional_git-2.1.1}/skills/conventional-commit/references/commit-types.csv +0 -0
  134. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/__init__.py +0 -0
  135. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/adapters/__init__.py +0 -0
  136. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/adapters/commitizen_config.py +0 -0
  137. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/branch/__init__.py +0 -0
  138. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/branch/grammar.py +0 -0
  139. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/branch/rules.py +0 -0
  140. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/branch/vocabulary.py +0 -0
  141. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/cli/__init__.py +0 -0
  142. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/cli/app.py +0 -0
  143. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/cli/auth.py +0 -0
  144. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/cli/capabilities.py +0 -0
  145. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/cli/hook.py +0 -0
  146. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/cli/mcp.py +0 -0
  147. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/commit/__init__.py +0 -0
  148. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/commit/compose.py +0 -0
  149. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/commit/grammar.py +0 -0
  150. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/csv_columns.py +0 -0
  151. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/data/__init__.py +0 -0
  152. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/data/branch-exempt-prefixes.csv +0 -0
  153. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/data/branch-trunks.csv +0 -0
  154. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/data/branch-types.csv +0 -0
  155. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/data/commit-attribution.csv +0 -0
  156. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/data/commit-types.csv +0 -0
  157. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/generation/__init__.py +0 -0
  158. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/generation/credentials.py +0 -0
  159. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/generation/diff.py +0 -0
  160. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/generation/heuristic.py +0 -0
  161. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/generation/protocol.py +0 -0
  162. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/generation/typesafe.py +0 -0
  163. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/mcp/__init__.py +0 -0
  164. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/py.typed +0 -0
  165. {conventional_git-1.2.0 → conventional_git-2.1.1}/src/conventional_git/violations.py +0 -0
  166. {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/__init__.py +0 -0
  167. {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_branch_rules.py +0 -0
  168. {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_branch_vocabulary.py +0 -0
  169. {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_cli_auth.py +0 -0
  170. {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_cli_capabilities.py +0 -0
  171. {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_cli_hook.py +0 -0
  172. {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_commit_compose.py +0 -0
  173. {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_credentials.py +0 -0
  174. {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_diff.py +0 -0
  175. {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_generation_suggest.py +0 -0
  176. {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_heuristic.py +0 -0
  177. {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_mcp_server.py +0 -0
  178. {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_plugin_version.py +0 -0
  179. {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_skill_vocabularies.py +0 -0
  180. {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_typesafe_client_factory.py +0 -0
  181. {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_typesafe_provider.py +0 -0
  182. {conventional_git-1.2.0 → conventional_git-2.1.1}/tests/test_violation_code_coverage.py +0 -0
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "conventional-git",
3
- "version": "1.2.0",
3
+ "version": "2.1.1",
4
4
  "description": "Conventional Commits and Conventional Branch skills for Claude Code",
5
5
  "author": {
6
6
  "name": "G.A.JAGUAR",
@@ -7,6 +7,9 @@ mise.local.toml
7
7
  # Obsidian vault metadata (docs/ is opened directly as a vault)
8
8
  .obsidian/
9
9
 
10
+ # Answers and batches of `make docs-retag`
11
+ .cache/
12
+
10
13
  # Created by https://www.toptal.com/developers/gitignore/api/linux,macos,jetbrains+all,visualstudiocode,node,python
11
14
  # Edit at https://www.toptal.com/developers/gitignore?templates=linux,macos,jetbrains+all,visualstudiocode,node,python
12
15
 
@@ -27,6 +27,13 @@ repos:
27
27
  language: system
28
28
  pass_filenames: false
29
29
 
30
+ - id: docs-lint
31
+ name: okflint
32
+ entry: make docs-lint
33
+ language: system
34
+ files: ^(docs/.*\.md|okf-base\.yaml)$
35
+ pass_filenames: false
36
+
30
37
  - id: conventional-commit-msg
31
38
  name: conventional-git commit message
32
39
  entry: uvx conventional-git@latest check commit --file
@@ -0,0 +1,115 @@
1
+ # AGENTS.md
2
+
3
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
4
+ "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
5
+ interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
6
+
7
+ ## Agent instructions
8
+
9
+ - `AGENTS.md` is the only agent instructions file; put project rules here. The
10
+ repository MUST NOT contain a `CLAUDE.md` or any other tool-specific copy,
11
+ because a second copy drifts from this one; `make claude-md-check` fails on
12
+ one.
13
+
14
+ ## Command surface
15
+
16
+ - Run the `Makefile` targets (`make check`, `make fix`, `make test`, ...)
17
+ instead of the underlying tools, so the agent and CI use the same options.
18
+ `make help` lists them.
19
+ - Give every new target a `##` help line; `make help` prints it and
20
+ `make help-check` fails on a target without one.
21
+
22
+ ## Gate
23
+
24
+ - `make check` and `make test` MUST pass before any commit.
25
+ - Run `make fix` first for findings it can repair, then edit by hand.
26
+
27
+ ## Commits and branches
28
+
29
+ - Write commit messages as
30
+ [Conventional Commits](https://www.conventionalcommits.org/) and branch
31
+ names as [Conventional Branch](https://conventionalbranch.org/)
32
+ (`<type>/<description>`, e.g. `feat/add-enforcement`,
33
+ `fix/normalize-description-grammar`). A pre-commit hook and
34
+ `make commits-check` enforce both; see
35
+ [`docs/conventions/commits-check.md`](docs/conventions/commits-check.md).
36
+ - Name a documentation or dependency branch `chore/...`: a branch type is not
37
+ a commit type, and `docs/` is not one.
38
+
39
+ ## Pull requests
40
+
41
+ Once a pull request is open, the agent MUST:
42
+
43
+ 1. Wait for CI; while it fails, fix the cause, push to the same branch and
44
+ wait again until it passes.
45
+ 2. Squash-merge a pull request with exactly one commit and use a regular merge
46
+ commit otherwise (`gh pr view --json commits` gives the count).
47
+ 3. Delete the branch on the remote and locally.
48
+ 4. Switch back to the base branch, pull it and run `git fetch --prune`.
49
+
50
+ ## Versioning and releases
51
+
52
+ - Decide every version bump, tag and release as
53
+ [`docs/conventions/versioning.md`](docs/conventions/versioning.md) defines;
54
+ it is the only place those rules live.
55
+
56
+ ## Documentation
57
+
58
+ - Follow the organization's shared documentation-writing guide, kept in one
59
+ place rather than copied into this repository so it cannot drift from other
60
+ projects that follow the same guide.
61
+ - Add a new `docs/` note to its directory's `index.md` and, by file name, to
62
+ [`docs/log.md`](docs/log.md); `make docs-lint` fails on a missing field or a
63
+ broken link.
64
+ - Cover exactly one concept per note.
65
+ - Write a note only when it explains something a reader cannot already get
66
+ from `make help`, a linter's own message, or the configuration it comes
67
+ from.
68
+
69
+ ## Dependencies
70
+
71
+ - Add a new tool to the ecosystem manager that owns it (`package.json` for
72
+ Node, `pyproject.toml` `[dependency-groups].dev` for Python); use
73
+ `mise.toml` only for a tool that bootstraps an ecosystem or has no manager
74
+ in this repository.
75
+ - Declare a tool in one layer only: two pins can drift and the gate would no
76
+ longer cover both. See
77
+ [`docs/toolchain/layering-rule.md`](docs/toolchain/layering-rule.md).
78
+
79
+ ## Layering
80
+
81
+ The codebase is intentionally three layers; the agent MUST NOT cross the
82
+ boundaries below.
83
+
84
+ 1. **Spec core** — `conventional_git.commit.*` and `conventional_git.branch.*`.
85
+ Pure functions, no git calls, no `SystemExit`, no I/O. Validation returns
86
+ a `Report` of `Violation`s. This is the only layer that holds rules.
87
+ 2. **Adapters** — `conventional_git.adapters.*` (gitlint rules, commitizen
88
+ schema emitter). Translate `Violation` into the consumer tool's error
89
+ type. The adapter is the only place that imports the consumer SDK.
90
+ 3. **Front-ends** — `conventional_git.cli.*` and `conventional_git.mcp.*`.
91
+ Map user input into core calls and core output into user output. These
92
+ are the only layers that may call `SystemExit`.
93
+
94
+ A new rule MUST land in the core; an adapter that hardcodes the rule
95
+ duplicates it. A new vocabulary entry MUST land in
96
+ `data/{commit,branch}-types.csv`; a regex inside the core is a bug, not a
97
+ feature.
98
+
99
+ ## Python
100
+
101
+ - Write no docstrings on functions, methods or classes; add a comment only
102
+ where the *why* is not obvious from the code. `pylint-gajaguar`'s
103
+ `gajaguar-no-docstrings` fails `make check` on any docstring.
104
+ - Enable the plugin with `enable = ["gajaguar"]` in `pyproject.toml`'s
105
+ `[tool.pylint."messages control"]`, not with a list of rules, so a rule
106
+ added by a `pylint-gajaguar` upgrade runs without a config change.
107
+ - Keep `pyproject.toml` to settings that differ from the tool's default, and
108
+ keep a `lint.per-file-ignores` entry only while it matches a current
109
+ violation; see
110
+ [`docs/python/pyproject-defaults.md`](docs/python/pyproject-defaults.md).
111
+ - Keep the spec core free of `git` imports and `SystemExit`. Returning a
112
+ `Report` is the contract; only front-ends turn violations into exit codes.
113
+ - Tag a minor or major bump with `make release-tag` after its pull request
114
+ merges, as [`docs/conventions/versioning.md`](docs/conventions/versioning.md)
115
+ describes; the target tags the base branch as `v<project.version>`.
@@ -33,7 +33,10 @@ This repository dogfoods its own rules:
33
33
  [Conventional Commits](https://www.conventionalcommits.org/).
34
34
  - Branch names MUST follow
35
35
  [Conventional Branch](https://conventionalbranch.org/)
36
- (`<type>/<description>`, e.g. `fix/normalize-branch-name`).
36
+ (`<type>/<description>`, e.g. `fix/normalize-branch-name`). The branch
37
+ type is one of `feat` (or `feature`), `fix` (or `bugfix`), `hotfix`,
38
+ `release`, or `chore`; documentation and dependency work uses `chore/`,
39
+ because `docs/` is not a branch type.
37
40
  - Commit messages MUST NOT carry an attribution trailer (`Co-Authored-By:`,
38
41
  "Generated with …", a 🤖 marker); the project's own commit-msg hook
39
42
  rejects them — see
@@ -13,6 +13,11 @@ FILES ?=
13
13
  # docs/conventions/commits-check.md.
14
14
  BASE ?= origin/main
15
15
  CONVENTIONAL_GIT ?= uvx conventional-git@latest
16
+ # Pinned, not @latest: a linter's verdict changes between versions. See
17
+ # docs/toolchain/okflint.md and docs/documentation/retag-notes.md.
18
+ OKFLINT ?= uvx okflint@0.4.1
19
+ TYPESAFE ?= uvx --from typesafe-unofficial-cli@1.1.0 typesafe
20
+ DOCS_RETAG := uv run --script tools/docs-retag.py
16
21
  BRANCH ?= $(or $(GITHUB_HEAD_REF),$(shell git branch --show-current))
17
22
 
18
23
  .DEFAULT_GOAL := help
@@ -73,9 +78,20 @@ commits-check: ## Validate the commit range and branch name against Conventional
73
78
  done
74
79
  @$(CONVENTIONAL_GIT) check branch --name "$(BRANCH)"
75
80
 
76
- check: makefile-lint md-lint spell commits-check $(LANG_CHECK_TARGETS) ## Run the full read-only validation gate
81
+ help-check: ## Fail if a Makefile target lacks its ## help line — see docs/conventions/help-check.md
82
+ @missing=$$(grep -HnE '^[a-zA-Z][a-zA-Z0-9_-]*[[:space:]]*:([^=]|$$)' Makefile mk/*.mk 2>/dev/null | grep -v '##' || true); \
83
+ test -z "$$missing" || { echo "target without a ## help line:" >&2; echo "$$missing" >&2; exit 1; }
77
84
 
78
- .PHONY: makefile-lint md-lint spell commits-check check
85
+ claude-md-check: ## Fail if a CLAUDE.md exists, since AGENTS.md is the only agent file — see docs/conventions/claude-md-check.md
86
+ @found=$$(git ls-files --cached --others --exclude-standard | grep -E '(^|/)CLAUDE\.md$$' || true); \
87
+ test -z "$$found" || { echo "CLAUDE.md found; fold it into AGENTS.md and delete it:" >&2; echo "$$found" >&2; exit 1; }
88
+
89
+ docs-lint: ## Validate docs/ as an OKF bundle with okflint — see docs/toolchain/okflint.md
90
+ @$(OKFLINT) validate
91
+
92
+ check: makefile-lint md-lint spell docs-lint commits-check help-check claude-md-check $(LANG_CHECK_TARGETS) ## Run the full read-only validation gate
93
+
94
+ .PHONY: makefile-lint md-lint spell docs-lint commits-check help-check claude-md-check check
79
95
 
80
96
  ##@ Writable fixes (mutate files in place)
81
97
 
@@ -106,3 +122,16 @@ fix-unsafe: _md-fix-scoped $(LANG_FIX_UNSAFE_TARGETS) ## Apply all auto-fixes, i
106
122
  test: $(LANG_TEST_TARGETS) ## Run the test suite
107
123
 
108
124
  .PHONY: test
125
+
126
+ ##@ Docs tagging (optional, billed — not part of check)
127
+
128
+ docs-retag: ## Ask TypeSafe which tags each docs/ note carries, then show a dry run — one billed request per note
129
+ @$(DOCS_RETAG) build
130
+ @$(TYPESAFE) -o jsonl ask --states-file .cache/docs-retag/states.jsonl --questions-file .cache/docs-retag/questions.json --concurrency 4 > .cache/docs-retag/answers.jsonl
131
+ @$(DOCS_RETAG) apply
132
+
133
+ docs-retag-apply: ## Write the tags from the last docs-retag run into the notes, then validate docs/
134
+ @$(DOCS_RETAG) apply --write
135
+ @$(MAKE) docs-lint
136
+
137
+ .PHONY: docs-retag docs-retag-apply
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: conventional-git
3
- Version: 1.2.0
3
+ Version: 2.1.1
4
4
  Summary: Conventional Commits and Conventional Branch enforcement, validation, and generation
5
5
  Project-URL: Repository, https://github.com/gajaguar/conventional-git
6
6
  Project-URL: Issues, https://github.com/gajaguar/conventional-git/issues
@@ -146,9 +146,6 @@ conventional-git create branch --type feature --description "add login"
146
146
  # feature/add-login
147
147
  ```
148
148
 
149
- Use `--dry-run` when you need the generated value without taking further
150
- action. The current implementation prints the value in either mode.
151
-
152
149
  ### Enforce
153
150
 
154
151
  Install `commit-msg`, `pre-commit`, and `pre-push` hooks in a repository:
@@ -170,8 +167,9 @@ credential, `create suggest` always falls back to the built-in heuristic
170
167
  provider and prints a notice; it never fails the command:
171
168
 
172
169
  ```bash
173
- git diff --cached | conventional-git create suggest --diff-file -
170
+ conventional-git create suggest
174
171
  conventional-git create suggest --diff-file changes.diff --apply
172
+ git diff main... | conventional-git create suggest --diff-file -
175
173
  ```
176
174
 
177
175
  With the `llm` extra installed and a credential available, `create suggest`
@@ -218,33 +216,45 @@ uvx --from 'conventional-git[mcp]' conventional-git-mcp
218
216
  ```
219
217
 
220
218
  The server exposes `validate_commit_message`, `validate_branch_name`,
221
- `describe_convention`, and `suggest_commit_message`. See
219
+ `describe_convention`, and `suggest_commit_message`. The server has no auth
220
+ tools: for `suggest_commit_message` to use `jev`, run
221
+ `conventional-git auth login` first and launch it with the `llm` extra (see
222
+ [`docs/mcp/out-of-band-auth.md`](docs/mcp/out-of-band-auth.md)). See
222
223
  [`docs/mcp/index.md`](docs/mcp/index.md).
223
224
 
224
225
  ## Agents
225
226
 
226
227
  The repository is both a Claude Code plugin and an
227
228
  [Agent Skills](https://agentskills.io/specification)-compliant `skills/`
228
- directory.
229
+ directory. See [`docs/agents/index.md`](docs/agents/index.md) for the full
230
+ install guide; one command per channel.
229
231
 
230
- **Claude Code** — add the marketplace, then install the plugin (it bundles
231
- `conventional-commit`, `conventional-branch`, and the MCP server):
232
+ **Claude Code**: add the marketplace, then install the plugin. It bundles
233
+ `conventional-commit`, `conventional-branch`, `conventional-suggest`,
234
+ `conventional-auth`, and the MCP server:
232
235
 
233
236
  ```text
234
237
  /plugin marketplace add gajaguar/conventional-git
235
238
  /plugin install conventional-git@conventional-git-skills
239
+ /reload-plugins
236
240
  ```
237
241
 
238
242
  See [`docs/mcp/plugin-bundled-server.md`](docs/mcp/plugin-bundled-server.md)
239
243
  for how the bundled `.mcp.json` launches the server.
240
244
 
241
245
  **Any other agent that supports Agent Skills** (Codex, Cursor, Gemini CLI,
242
- Copilot, ...):
246
+ Copilot, and others):
243
247
 
244
248
  ```bash
245
249
  npx skills add gajaguar/conventional-git
246
250
  ```
247
251
 
252
+ **opencode**:
253
+
254
+ ```bash
255
+ npx skills add gajaguar/conventional-git -a opencode -y
256
+ ```
257
+
248
258
  Skills call `conventional-git capabilities --json` before drafting, so they
249
259
  only offer `create suggest` (see [Suggest](#suggest)) when the `llm` extra
250
260
  and a credential are both present, and never send a diff to a third party
@@ -259,8 +269,8 @@ return `1`.
259
269
  | :------------- | ---------------------------------------------------------------------------------------- | ------------: |
260
270
  | check commit | `-m, --message`; `-f, --file`; `--types-csv` | 0 or 1 |
261
271
  | check branch | `-n, --name`; `--types-csv` | 0 or 1 |
262
- | create commit | `--type`; `--description`; `--scope`; `--body`; `--breaking`; `--types-csv`; `--dry-run` | 0 or 1 |
263
- | create branch | `--type`; `--description`; `--types-csv`; `--dry-run` | 0 or 1 |
272
+ | create commit | `--type`; `--description`; `--scope`; `--body`; `--breaking`; `--types-csv` | 0 or 1 |
273
+ | create branch | `--type`; `--description`; `--types-csv` | 0 or 1 |
264
274
  | create suggest | `--diff-file`; `--provider`; `--apply` | 0 or 1 |
265
275
  | hook install | `--target`; `--force` | 0 or 1 |
266
276
  | hook uninstall | `--target` | 0 |
@@ -276,13 +286,14 @@ Use `conventional-git <command> --help` for the full option descriptions.
276
286
 
277
287
  Create `.conventional-git.toml` in the current repository:
278
288
 
279
- | Key | Default | Purpose |
280
- | :--------------------------------- | ------------- | -------------------------- |
281
- | `[commit] attribution_patterns` | built-in list | Extra attribution regexes |
282
- | `[commit] type_overrides` | `[]` | Extra commit types |
283
- | `[branch] type_overrides` | `[]` | Extra branch types |
284
- | `[branch] trunk_overrides` | `[]` | Extra trunk branch names |
285
- | `[branch] exempt_prefix_overrides` | `[]` | Extra exempt name prefixes |
289
+ | Key | Default | Purpose |
290
+ | :---------------------------------------------- | ------------- | ---------------------------------- |
291
+ | `[commit] attribution_patterns` | built-in list | Extra attribution regexes |
292
+ | `[commit] disable_default_attribution_patterns` | `false` | Skip the built-in attribution list |
293
+ | `[commit] type_overrides` | `[]` | Extra commit types |
294
+ | `[branch] type_overrides` | `[]` | Extra branch types |
295
+ | `[branch] trunk_overrides` | `[]` | Extra trunk branch names |
296
+ | `[branch] exempt_prefix_overrides` | `[]` | Extra exempt name prefixes |
286
297
 
287
298
  Relative CSV paths in `type_overrides` / `trunk_overrides` /
288
299
  `exempt_prefix_overrides` are resolved
@@ -290,7 +301,8 @@ against the directory containing `.conventional-git.toml`, not the process's
290
301
  current directory. Every consumer that loads the file — the CLI, the MCP
291
302
  server, and the gitlint adapter — honors it. See
292
303
  [`docs/enforcement/attribution-trailers.md`](docs/enforcement/attribution-trailers.md)
293
- for what `attribution_patterns` extends.
304
+ for what `attribution_patterns` extends and how
305
+ `disable_default_attribution_patterns` turns the built-in list off.
294
306
 
295
307
  The `--types-csv` option extends the default vocabulary; it does not replace
296
308
  it. Vocabulary files live in `data/{commit,branch}-types.csv`.
@@ -327,7 +339,7 @@ and render its output. See [`docs/architecture/index.md`](docs/architecture/inde
327
339
  │ ├── adapters/{gitlint_rules,commitizen_config}.py
328
340
  │ ├── cli/{app,auth,check,create,hook,mcp}.py
329
341
  │ └── mcp/server.py
330
- ├── skills/conventional-{commit,branch}/SKILL.md
342
+ ├── skills/conventional-{commit,branch,suggest,auth}/SKILL.md
331
343
  └── tests/
332
344
  ```
333
345
 
@@ -125,9 +125,6 @@ conventional-git create branch --type feature --description "add login"
125
125
  # feature/add-login
126
126
  ```
127
127
 
128
- Use `--dry-run` when you need the generated value without taking further
129
- action. The current implementation prints the value in either mode.
130
-
131
128
  ### Enforce
132
129
 
133
130
  Install `commit-msg`, `pre-commit`, and `pre-push` hooks in a repository:
@@ -149,8 +146,9 @@ credential, `create suggest` always falls back to the built-in heuristic
149
146
  provider and prints a notice; it never fails the command:
150
147
 
151
148
  ```bash
152
- git diff --cached | conventional-git create suggest --diff-file -
149
+ conventional-git create suggest
153
150
  conventional-git create suggest --diff-file changes.diff --apply
151
+ git diff main... | conventional-git create suggest --diff-file -
154
152
  ```
155
153
 
156
154
  With the `llm` extra installed and a credential available, `create suggest`
@@ -197,33 +195,45 @@ uvx --from 'conventional-git[mcp]' conventional-git-mcp
197
195
  ```
198
196
 
199
197
  The server exposes `validate_commit_message`, `validate_branch_name`,
200
- `describe_convention`, and `suggest_commit_message`. See
198
+ `describe_convention`, and `suggest_commit_message`. The server has no auth
199
+ tools: for `suggest_commit_message` to use `jev`, run
200
+ `conventional-git auth login` first and launch it with the `llm` extra (see
201
+ [`docs/mcp/out-of-band-auth.md`](docs/mcp/out-of-band-auth.md)). See
201
202
  [`docs/mcp/index.md`](docs/mcp/index.md).
202
203
 
203
204
  ## Agents
204
205
 
205
206
  The repository is both a Claude Code plugin and an
206
207
  [Agent Skills](https://agentskills.io/specification)-compliant `skills/`
207
- directory.
208
+ directory. See [`docs/agents/index.md`](docs/agents/index.md) for the full
209
+ install guide; one command per channel.
208
210
 
209
- **Claude Code** — add the marketplace, then install the plugin (it bundles
210
- `conventional-commit`, `conventional-branch`, and the MCP server):
211
+ **Claude Code**: add the marketplace, then install the plugin. It bundles
212
+ `conventional-commit`, `conventional-branch`, `conventional-suggest`,
213
+ `conventional-auth`, and the MCP server:
211
214
 
212
215
  ```text
213
216
  /plugin marketplace add gajaguar/conventional-git
214
217
  /plugin install conventional-git@conventional-git-skills
218
+ /reload-plugins
215
219
  ```
216
220
 
217
221
  See [`docs/mcp/plugin-bundled-server.md`](docs/mcp/plugin-bundled-server.md)
218
222
  for how the bundled `.mcp.json` launches the server.
219
223
 
220
224
  **Any other agent that supports Agent Skills** (Codex, Cursor, Gemini CLI,
221
- Copilot, ...):
225
+ Copilot, and others):
222
226
 
223
227
  ```bash
224
228
  npx skills add gajaguar/conventional-git
225
229
  ```
226
230
 
231
+ **opencode**:
232
+
233
+ ```bash
234
+ npx skills add gajaguar/conventional-git -a opencode -y
235
+ ```
236
+
227
237
  Skills call `conventional-git capabilities --json` before drafting, so they
228
238
  only offer `create suggest` (see [Suggest](#suggest)) when the `llm` extra
229
239
  and a credential are both present, and never send a diff to a third party
@@ -238,8 +248,8 @@ return `1`.
238
248
  | :------------- | ---------------------------------------------------------------------------------------- | ------------: |
239
249
  | check commit | `-m, --message`; `-f, --file`; `--types-csv` | 0 or 1 |
240
250
  | check branch | `-n, --name`; `--types-csv` | 0 or 1 |
241
- | create commit | `--type`; `--description`; `--scope`; `--body`; `--breaking`; `--types-csv`; `--dry-run` | 0 or 1 |
242
- | create branch | `--type`; `--description`; `--types-csv`; `--dry-run` | 0 or 1 |
251
+ | create commit | `--type`; `--description`; `--scope`; `--body`; `--breaking`; `--types-csv` | 0 or 1 |
252
+ | create branch | `--type`; `--description`; `--types-csv` | 0 or 1 |
243
253
  | create suggest | `--diff-file`; `--provider`; `--apply` | 0 or 1 |
244
254
  | hook install | `--target`; `--force` | 0 or 1 |
245
255
  | hook uninstall | `--target` | 0 |
@@ -255,13 +265,14 @@ Use `conventional-git <command> --help` for the full option descriptions.
255
265
 
256
266
  Create `.conventional-git.toml` in the current repository:
257
267
 
258
- | Key | Default | Purpose |
259
- | :--------------------------------- | ------------- | -------------------------- |
260
- | `[commit] attribution_patterns` | built-in list | Extra attribution regexes |
261
- | `[commit] type_overrides` | `[]` | Extra commit types |
262
- | `[branch] type_overrides` | `[]` | Extra branch types |
263
- | `[branch] trunk_overrides` | `[]` | Extra trunk branch names |
264
- | `[branch] exempt_prefix_overrides` | `[]` | Extra exempt name prefixes |
268
+ | Key | Default | Purpose |
269
+ | :---------------------------------------------- | ------------- | ---------------------------------- |
270
+ | `[commit] attribution_patterns` | built-in list | Extra attribution regexes |
271
+ | `[commit] disable_default_attribution_patterns` | `false` | Skip the built-in attribution list |
272
+ | `[commit] type_overrides` | `[]` | Extra commit types |
273
+ | `[branch] type_overrides` | `[]` | Extra branch types |
274
+ | `[branch] trunk_overrides` | `[]` | Extra trunk branch names |
275
+ | `[branch] exempt_prefix_overrides` | `[]` | Extra exempt name prefixes |
265
276
 
266
277
  Relative CSV paths in `type_overrides` / `trunk_overrides` /
267
278
  `exempt_prefix_overrides` are resolved
@@ -269,7 +280,8 @@ against the directory containing `.conventional-git.toml`, not the process's
269
280
  current directory. Every consumer that loads the file — the CLI, the MCP
270
281
  server, and the gitlint adapter — honors it. See
271
282
  [`docs/enforcement/attribution-trailers.md`](docs/enforcement/attribution-trailers.md)
272
- for what `attribution_patterns` extends.
283
+ for what `attribution_patterns` extends and how
284
+ `disable_default_attribution_patterns` turns the built-in list off.
273
285
 
274
286
  The `--types-csv` option extends the default vocabulary; it does not replace
275
287
  it. Vocabulary files live in `data/{commit,branch}-types.csv`.
@@ -306,7 +318,7 @@ and render its output. See [`docs/architecture/index.md`](docs/architecture/inde
306
318
  │ ├── adapters/{gitlint_rules,commitizen_config}.py
307
319
  │ ├── cli/{app,auth,check,create,hook,mcp}.py
308
320
  │ └── mcp/server.py
309
- ├── skills/conventional-{commit,branch}/SKILL.md
321
+ ├── skills/conventional-{commit,branch,suggest,auth}/SKILL.md
310
322
  └── tests/
311
323
  ```
312
324
 
@@ -42,3 +42,5 @@ unbypassable
42
42
  uv
43
43
  venv
44
44
  vocabulary
45
+ okflint
46
+ retag
@@ -0,0 +1,68 @@
1
+ ---
2
+ type: reference
3
+ title: Agent Skills format
4
+ description: SKILL.md frontmatter fields and their constraints, progressive disclosure, and the optional references/ subdirectory.
5
+ tags: [agents, skills, documentation]
6
+ status: stable
7
+ stale_after: 2027-03-29
8
+ sources:
9
+ - id: agentskills-spec
10
+ resource: https://agentskills.io/specification
11
+ title: Agent Skills specification
12
+ author: team:agentskills
13
+ ---
14
+
15
+ # Agent Skills format
16
+
17
+ An Agent Skill is a directory that contains a `SKILL.md` file: YAML
18
+ frontmatter followed by Markdown instructions. Agents load the `name`
19
+ and `description` at startup to decide when a skill applies.[^agentskills-spec]
20
+
21
+ | Field | Required | Purpose |
22
+ | :-------------- | :------- | :------------------------------------------ |
23
+ | `name` | Yes | Skill identifier |
24
+ | `description` | Yes | What the skill does and when to use it |
25
+ | `license` | No | License name or bundled license file |
26
+ | `compatibility` | No | Environment requirements |
27
+ | `metadata` | No | String-to-string map of extra properties |
28
+ | `allowed-tools` | No | Pre-approved tools (experimental) |
29
+
30
+ Constraints from the specification:[^agentskills-spec]
31
+
32
+ * `name`: 1-64 characters; lowercase letters, digits, and hyphens only;
33
+ no leading, trailing, or consecutive hyphens; must match the parent
34
+ directory name.
35
+ * `description`: 1-1024 characters; say what the skill does and when to
36
+ use it.
37
+ * `license`: a license name or a reference to a bundled license file;
38
+ keep it short.
39
+ * `compatibility`: 1-500 characters; for example the intended product,
40
+ system packages, or network access.
41
+ * `metadata`: a map from string keys to string values; use reasonably
42
+ unique key names.
43
+ * `allowed-tools`: a space-separated string of pre-approved tools.
44
+ Experimental, so support varies between agents.
45
+
46
+ ## Progressive disclosure
47
+
48
+ Agents load a skill in three steps:[^agentskills-spec]
49
+
50
+ 1. **Metadata** (about 100 tokens): `name` and `description`, loaded
51
+ at startup for every skill.
52
+ 2. **Instructions** (under 5000 tokens recommended): the full
53
+ `SKILL.md` body, loaded when the skill activates.
54
+ 3. **Resources**: files under `scripts/`, `references/`, or `assets/`,
55
+ loaded only when needed.
56
+
57
+ Keep `SKILL.md` under 500 lines and move detailed material into
58
+ separate files.
59
+
60
+ ## `references/` subdirectory
61
+
62
+ A skill may put additional documentation under `references/` (for
63
+ example `REFERENCE.md` or a domain-specific file) and link to it with a
64
+ relative path from the skill root. Agents read these files on demand, so
65
+ keep each one focused. Keep references one level deep from
66
+ `SKILL.md`.[^agentskills-spec]
67
+
68
+ [^agentskills-spec]: Agent Skills specification
@@ -0,0 +1,50 @@
1
+ ---
2
+ type: reference
3
+ title: Claude Code install scopes
4
+ description: user, project, and local scopes — which settings file each writes to, the precedence order, and when each is the right choice.
5
+ tags: [agents, claude-code]
6
+ status: stable
7
+ stale_after: 2027-03-29
8
+ sources:
9
+ - id: claude-discover-plugins
10
+ resource: https://code.claude.com/docs/en/discover-plugins
11
+ title: Discover and install Claude Code plugins
12
+ author: team:anthropic
13
+ - id: claude-loading
14
+ resource: https://code.claude.com/docs/en/plugins/loading
15
+ title: How Claude Code loads plugins
16
+ author: team:anthropic
17
+ ---
18
+
19
+ # Claude Code install scopes
20
+
21
+ Every install, by `/plugin install` or `claude plugin install`, is
22
+ recorded in a settings file under one of three scopes.[^claude-discover-plugins]
23
+
24
+ | Scope | Settings file | Reaches |
25
+ | :-------- | :----------------------------------- | :-------------------------------------- |
26
+ | `user` | `~/.claude/settings.json` | You, in every project on this machine |
27
+ | `project` | `.claude/settings.json` (committed) | Everyone who works in the repository |
28
+ | `local` | `.claude/settings.local.json` | You, in this repository only |
29
+
30
+ The entry is written under `enabledPlugins` in that file.
31
+
32
+ ## Which scope to pick
33
+
34
+ * **`user`**: the default for `claude plugin install`. Use it for
35
+ plugins you want in every project.
36
+ * **`project`**: the entry lives in the committed `.claude/settings.json`.
37
+ Use it when the repository itself depends on the plugin. Committing the
38
+ entry enables the plugin for collaborators but does not download it, so
39
+ each collaborator runs
40
+ `claude plugin install <plugin>@<marketplace> --scope project` once.[^claude-loading]
41
+ * **`local`**: the entry lives in `.claude/settings.local.json`. Use it
42
+ for a personal setup in one repository.
43
+
44
+ ## Precedence
45
+
46
+ When the same plugin is set at several scopes, `local` overrides
47
+ `project`, and `project` overrides `user`.[^claude-loading]
48
+
49
+ [^claude-discover-plugins]: Discover and install Claude Code plugins
50
+ [^claude-loading]: How Claude Code loads plugins
@@ -0,0 +1,67 @@
1
+ ---
2
+ type: playbook
3
+ title: Installing through the Claude Code marketplace
4
+ description: Add a marketplace and install a plugin from it inside a Claude Code session, including the one-step form and the reload.
5
+ tags: [agents, claude-code]
6
+ status: stable
7
+ stale_after: 2027-03-29
8
+ sources:
9
+ - id: claude-discover-plugins
10
+ resource: https://code.claude.com/docs/en/discover-plugins
11
+ title: Discover and install Claude Code plugins
12
+ author: team:anthropic
13
+ ---
14
+
15
+ # Installing through the Claude Code marketplace
16
+
17
+ Use the `/plugin` slash commands inside a Claude Code session to add a
18
+ marketplace and install a plugin from it.[^claude-discover-plugins]
19
+
20
+ ## Two commands
21
+
22
+ ```text
23
+ /plugin marketplace add <owner>/<repo>[#ref]
24
+ /plugin install <plugin>@<marketplace>
25
+ ```
26
+
27
+ Add `#ref` to pin a branch or tag. `<marketplace>` is the name the
28
+ marketplace registered under, and `<plugin>` is the plugin's name. Both
29
+ names are listed in [`plugin-identity.md`](plugin-identity.md).
30
+
31
+ In a session, `/plugin install` does not install right away. It opens
32
+ the `/plugin` panel on the plugin's details so you can review it and
33
+ pick a scope: user, project (all collaborators on the repository), or
34
+ local (you, this repository only).
35
+
36
+ ## One-step form
37
+
38
+ To add a marketplace and install from it in one command, pass
39
+ `--marketplace` with the marketplace source. This form requires Claude
40
+ Code v2.1.275 or later.
41
+
42
+ ```text
43
+ /plugin install <plugin> --marketplace <owner>/<repo>
44
+ ```
45
+
46
+ Give the plugin name by itself, without an `@<marketplace>` suffix. If
47
+ the marketplace is not added yet, Claude Code shows the source it
48
+ resolved and asks you to confirm before adding it.
49
+
50
+ ## Scope
51
+
52
+ You choose the scope in the panel, not with a flag. The `--scope` flag
53
+ belongs to the shell command; see
54
+ [`claude-code-shell-install.md`](claude-code-shell-install.md). For what
55
+ each scope writes, see
56
+ [`claude-code-install-scopes.md`](claude-code-install-scopes.md).
57
+
58
+ ## Reload
59
+
60
+ The install summary ends with one of two outcomes: `Plugin is now
61
+ active.`, or `Run /reload-plugins to activate.` In the second case, the
62
+ panel closes and Claude Code runs the reload for you. If the reload
63
+ would invalidate the prompt cache, Claude Code warns and leaves the
64
+ plugin pending; run `/reload-plugins --force` to activate it
65
+ anyway.[^claude-discover-plugins]
66
+
67
+ [^claude-discover-plugins]: Discover and install Claude Code plugins