chore: restructure .claude/skills into per-skill directories#9146
Conversation
- Replace flat pr-description.md / release-notes.md with per-skill folders - Add new branch-name and translate skills - Update release-notes skill to match the GitHub Releases format (v1.2.0)
📝 WalkthroughWalkthroughThis PR adds four new Claude AI skill definitions to streamline development workflows: branch naming convention, pull request creation, release notes generation, and i18n translation. The branch and PR skills enable consistent naming and template-compliant PRs. The release-notes skill provides structured commit filtering and categorization for GitHub Releases. The translate skill establishes comprehensive i18n standards across multiple locales with glossaries, locale-specific rules, and hallucination safeguards. ChangesClaude Workflow Skills
i18n Translation Framework
🎯 2 (Simple) | ⏱️ ~12 minutes
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Pull request overview
Restructures the repository’s Claude skill definitions under .claude/skills/ from flat markdown files into per-skill directories, and updates/adds skills to better support PR creation, branch naming, release-note generation, and i18n translation workflows.
Changes:
- Migrate legacy flat skills (
pr-description.md,release-notes.md) into per-skill folders withSKILL.md. - Add new
branch-nameandtranslateskills. - Update the
release-notesskill to produce GitHub Releases-style sections (matching the referenced v1.2.0 format).
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| .claude/skills/translate/SKILL.md | New, comprehensive i18n translation workflow + glossary + CLDR guidance. |
| .claude/skills/release-notes/SKILL.md | New release-notes skill targeting GitHub Releases formatting and cloud/EE repo flows. |
| .claude/skills/release-notes.md | Removes the old flat release-notes skill file. |
| .claude/skills/pr-description.md | Removes the old flat PR-description skill file. |
| .claude/skills/create-pull-request/SKILL.md | New consolidated skill for drafting PRs from the repo template and branch context. |
| .claude/skills/branch-name/SKILL.md | New skill defining branch naming conventions for work-item-driven branches. |
| `user_invocable: true` is advisory and follows the same convention as the existing | ||
| `pr-description.md` and `release-notes.md` skills in this repo. No harness behavior | ||
| in this codebase keys off the field today; it documents intent for the Claude Code | ||
| skill registry. The skill is invoked via the slash command (`/translate`) registered | ||
| in `.claude/commands/translate.md`, or by name when an agent infers relevance. |
|
|
||
| Register: | ||
|
|
||
| - **System and error messages** → 합니다체 (high-formal: 합니다, 됩니다, 입니다). Existing files in this register today: `ko/auth.json`, `ko/error/*.json`. |
|
|
||
| ``` | ||
| en: "Welcome, {name}! You have {count} new work items." | ||
| fr: "Bienvenue, {name} ! Vous avez {count} nouveaux work items." |
| | Locale | Required keywords | Example mapping | | ||
| | -------------------------------------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | ||
| | en, es, de, tr-TR, vi-VN, id, ja, ko, zh-CN, zh-TW | `one, other` (single-form locales may use `other` alone, but **always emit `other`**) | 1 → one; 2+ → other | | ||
| | fr | `one, many, other` | 0, 1 → one; 1 000 000 → many; else other | | ||
| | it | `one, many, other` | 1 → one; 1 000 000 → many; else other | | ||
| | pt-BR | `one, many, other` | 0, 1 → one; 1 000 000 → many; else other | | ||
| | ro | `one, few, other` | 1 → one; 0, 2–19 → few; 20+ → other | |
| > **Note on the consolidated row.** CLDR itself only requires `other` for `tr-TR`, `vi-VN`, `id`, `ja`, `ko`, `zh-CN`, `zh-TW` (single-form locales). Emitting both `one` and `other` with identical content is a **project convention** — it keeps tooling and linters consistent across the codebase. It is not a CLDR requirement, and `Intl.PluralRules` will return only `"other"` for these locales at runtime. | ||
|
|
| **Body**: Fill in every section from the PR template based on the actual diff: | ||
| - **Description** — Clear, concise summary of what the PR does and why. Focus on the "what" and "why", not line-by-line changes. Mention important implementation decisions. | ||
| - **Type of Change** — Check the appropriate box(es): Bug fix, Feature, Improvement, Code refactoring, Performance improvements, Documentation update. | ||
| - **Screenshots and Media** — Leave a placeholder: `<!-- Add screenshots here -->` |
| Output follows the GitHub Releases convention — `###` for section headers, with two spaces between the emoji and the label for ✨ / ⬆️ / 🐞 (matches `v1.2.0`). | ||
|
|
||
| ```markdown | ||
| ### ✨ Features | ||
|
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 7
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.claude/skills/branch-name/SKILL.md:
- Around line 13-15: Update the fenced code blocks in SKILL.md to include
language identifiers so markdownlint and tooling recognize them: replace the
bare fences around the template string
"<type>/<work-item-id>-<short-description>" with ```text, change the git branch
example fence that contains "git checkout -b
<type>/<work-item-id-lowercased>-<short-description>" to ```bash, and ensure the
multi-line example block listing sample branch names (e.g.,
"fix/silo-1146-relative-config-urls", "feat/web-1234-app-tile-visibility", etc.)
is fenced as ```text; apply the same additions to the other mentioned blocks
(the ones containing the same template and examples).
- Line 3: Update the cross-skill reference in the branch-name skill description:
replace the incorrect `create-pr` token with the actual skill identifier
`create-pull-request` so the description and any prompt-based discovery use the
real skill name (look for the `description:` line in SKILL.md for this skill).
In @.claude/skills/create-pull-request/SKILL.md:
- Around line 49-51: The fenced code block in
.claude/skills/create-pull-request/SKILL.md containing the example commit
message lacks a language tag and triggers markdownlint MD040; update the opening
fence from ``` to ```text (and keep the closing ``` intact) so the example
becomes a properly tagged block—locate the block around the string "[SILO-1146]
fix: allow relative URLs for configuration_url and improve app tile visibility"
and add the "text" language tag to the opening fence.
- Line 21: The code currently only reads `.github/pull_request_template.md`,
which breaks when repos place `pull_request_template.md` at the repo root;
update the lookup to try `.github/pull_request_template.md` first and fall back
to `pull_request_template.md` at the repo root (i.e., implement a two-path
lookup/try-read sequence where the code that reads the PR template first
attempts `.github/pull_request_template.md` and if not found attempts
`pull_request_template.md`), and ensure the fallback is used by the
create-pull-request skill logic that constructs the PR body.
In @.claude/skills/release-notes/SKILL.md:
- Around line 92-96: The spec is inconsistent about spacing after the emoji for
the ✨/⬆️/🐞 headings—enforce the rule "two spaces between the emoji and the
label" everywhere by updating the primary format example and all headings to
match the snippet "### ✨ Features" (and the equivalent for ⬆️ and 🐞) so the
quick-reference and examples use two spaces consistently; change any occurrences
of "### ✨ Features" or similar to "### ✨ Features" and ensure the doc text that
describes "✨ / ⬆️ / 🐞" explicitly states "two spaces" to keep the format spec
consistent.
- Around line 71-73: The fenced code block containing the MCP command
mcp__plane__retrieve_work_item_by_identifier(project_identifier="WEB",
issue_identifier=6874) lacks a language identifier and triggers MD040; update
the fence to include a language (e.g., "text") so the block becomes a fenced
code block with a language specifier, ensuring the command stays unchanged and
only the opening fence (``` -> ```text) is modified.
In @.claude/skills/translate/SKILL.md:
- Around line 145-159: Three fenced code blocks in SKILL.md (the block starting
with '✅ "Créer un Cycle" ...', the block starting with '✅ "使用 GitHub 登录" ...',
and the localization block starting with 'en: "Welcome, {name}! ..."') are
missing language identifiers and trigger markdownlint MD040; add an appropriate
language tag (e.g., ```text for plain examples or ```json/```md if more
suitable) to each opening fence to silence the lint and improve readability,
keeping the block contents unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 89997ca9-600a-47d3-828b-32af6c168065
📒 Files selected for processing (6)
.claude/skills/branch-name/SKILL.md.claude/skills/create-pull-request/SKILL.md.claude/skills/pr-description.md.claude/skills/release-notes.md.claude/skills/release-notes/SKILL.md.claude/skills/translate/SKILL.md
💤 Files with no reviewable changes (2)
- .claude/skills/pr-description.md
- .claude/skills/release-notes.md
| @@ -0,0 +1,67 @@ | |||
| --- | |||
| name: branch-name | |||
| description: Use when starting a new branch or renaming an existing one — produces a branch name in the format `<type>/<work-item-id>-<short-description>` that's compatible with the create-pr skill's work item ID extraction. | |||
There was a problem hiding this comment.
Align cross-skill reference with the actual skill name.
Line 3 says create-pr, but the defined skill is create-pull-request. This can confuse invocation/discovery in prompts and docs.
Proposed fix
-description: Use when starting a new branch or renaming an existing one — produces a branch name in the format `<type>/<work-item-id>-<short-description>` that's compatible with the create-pr skill's work item ID extraction.
+description: Use when starting a new branch or renaming an existing one — produces a branch name in the format `<type>/<work-item-id>-<short-description>` that's compatible with the create-pull-request skill's work item ID extraction.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.claude/skills/branch-name/SKILL.md at line 3, Update the cross-skill
reference in the branch-name skill description: replace the incorrect
`create-pr` token with the actual skill identifier `create-pull-request` so the
description and any prompt-based discovery use the real skill name (look for the
`description:` line in SKILL.md for this skill).
| ``` | ||
| <type>/<work-item-id>-<short-description> | ||
| ``` |
There was a problem hiding this comment.
Add language identifiers to fenced code blocks.
These fences are missing language tags, which triggers markdownlint and reduces tooling support.
Proposed fix
-```
+```text
<type>/<work-item-id>-<short-description>- +bash
git checkout -b /-
-```
+```text
fix/silo-1146-relative-config-urls
feat/web-1234-app-tile-visibility
chore/web-2201-bump-eslint
refactor/silo-980-extract-auth-middleware
docs/web-1500-pr-template-update
perf/silo-1310-cache-workspace-lookup
</details>
Also applies to: 43-45, 51-58
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.22.1)</summary>
[warning] 13-13: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.claude/skills/branch-name/SKILL.md around lines 13 - 15, Update the fenced
code blocks in SKILL.md to include language identifiers so markdownlint and
tooling recognize them: replace the bare fences around the template string
"/-" with text, change the git branch example fence that contains "git checkout -b <type>/<work-item-id-lowercased>-<short-description>" to bash, and ensure the
multi-line example block listing sample branch names (e.g.,
"fix/silo-1146-relative-config-urls", "feat/web-1234-app-tile-visibility", etc.)
is fenced as ```text; apply the same additions to the other mentioned blocks
(the ones containing the same template and examples).
</details>
<!-- fingerprinting:phantom:triton:hawk -->
<!-- This is an auto-generated comment by CodeRabbit -->
| - `git log <base>...HEAD --oneline` — all commits on the branch | ||
| - `git diff <base>...HEAD --no-color` — full diff for understanding changes (if very large, focus on the most important files first) | ||
| - `git rev-parse --abbrev-ref --symbolic-full-name @{u}` — check if branch tracks a remote | ||
| - Read `.github/pull_request_template.md` from the repo root |
There was a problem hiding this comment.
Handle both common PR template locations.
Limiting to .github/pull_request_template.md can fail in repos that keep pull_request_template.md at root. Add fallback lookup order to avoid workflow breaks.
Proposed fix
- - Read `.github/pull_request_template.md` from the repo root
+ - Read PR template from the repo root using fallback order:
+ 1. `.github/pull_request_template.md`
+ 2. `pull_request_template.md`
+ - If neither exists, ask the user before drafting📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - Read `.github/pull_request_template.md` from the repo root | |
| - Read PR template from the repo root using fallback order: | |
| 1. `.github/pull_request_template.md` | |
| 2. `pull_request_template.md` | |
| - If neither exists, ask the user before drafting |
🧰 Tools
🪛 LanguageTool
[uncategorized] ~21-~21: The official name of this software platform is spelled with a capital “H”.
Context: ...eck if branch tracks a remote - Read .github/pull_request_template.md from the repo...
(GITHUB)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.claude/skills/create-pull-request/SKILL.md at line 21, The code currently
only reads `.github/pull_request_template.md`, which breaks when repos place
`pull_request_template.md` at the repo root; update the lookup to try
`.github/pull_request_template.md` first and fall back to
`pull_request_template.md` at the repo root (i.e., implement a two-path
lookup/try-read sequence where the code that reads the PR template first
attempts `.github/pull_request_template.md` and if not found attempts
`pull_request_template.md`), and ensure the fallback is used by the
create-pull-request skill logic that constructs the PR body.
| ``` | ||
| [SILO-1146] fix: allow relative URLs for configuration_url and improve app tile visibility | ||
| ``` |
There was a problem hiding this comment.
Add a language tag to the example code fence.
This currently violates markdownlint MD040.
Proposed fix
-```
+```text
[SILO-1146] fix: allow relative URLs for configuration_url and improve app tile visibility</details>
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.22.1)</summary>
[warning] 49-49: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.claude/skills/create-pull-request/SKILL.md around lines 49 - 51, The fenced
code block in .claude/skills/create-pull-request/SKILL.md containing the example
commit message lacks a language tag and triggers markdownlint MD040; update the
opening fence from totext (and keep the closing ``` intact) so the
example becomes a properly tagged block—locate the block around the string
"[SILO-1146] fix: allow relative URLs for configuration_url and improve app tile
visibility" and add the "text" language tag to the opening fence.
</details>
<!-- fingerprinting:phantom:triton:hawk -->
<!-- This is an auto-generated comment by CodeRabbit -->
| ``` | ||
| mcp__plane__retrieve_work_item_by_identifier(project_identifier="WEB", issue_identifier=6874) | ||
| ``` |
There was a problem hiding this comment.
Add language to the MCP command fence.
This fence is missing a language identifier (MD040).
Proposed fix
-```
+```text
mcp__plane__retrieve_work_item_by_identifier(project_identifier="WEB", issue_identifier=6874)</details>
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.22.1)</summary>
[warning] 71-71: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.claude/skills/release-notes/SKILL.md around lines 71 - 73, The fenced code
block containing the MCP command
mcp__plane__retrieve_work_item_by_identifier(project_identifier="WEB",
issue_identifier=6874) lacks a language identifier and triggers MD040; update
the fence to include a language (e.g., "text") so the block becomes a fenced
code block with a language specifier, ensuring the command stays unchanged and
only the opening fence (->text) is modified.
</details>
<!-- fingerprinting:phantom:triton:hawk -->
<!-- This is an auto-generated comment by CodeRabbit -->
| Output follows the GitHub Releases convention — `###` for section headers, with two spaces between the emoji and the label for ✨ / ⬆️ / 🐞 (matches `v1.2.0`). | ||
|
|
||
| ```markdown | ||
| ### ✨ Features | ||
|
|
There was a problem hiding this comment.
Resolve heading-spacing inconsistency in the format spec.
The doc gives conflicting guidance: line 92 requires two spaces for ✨/⬆️/🐞, but the primary format example uses one space while quick-reference uses two. This ambiguity can produce incorrect release-note formatting.
Proposed fix
-### ✨ Features
+### ✨ Features
...
-### ⬆️ Enhancements
+### ⬆️ Enhancements
...
-### 🐞 Bug fixes
+### 🐞 Bug fixesAlso applies to: 108-114, 154-165
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.claude/skills/release-notes/SKILL.md around lines 92 - 96, The spec is
inconsistent about spacing after the emoji for the ✨/⬆️/🐞 headings—enforce the
rule "two spaces between the emoji and the label" everywhere by updating the
primary format example and all headings to match the snippet "### ✨ Features"
(and the equivalent for ⬆️ and 🐞) so the quick-reference and examples use two
spaces consistently; change any occurrences of "### ✨ Features" or similar to
"### ✨ Features" and ensure the doc text that describes "✨ / ⬆️ / 🐞"
explicitly states "two spaces" to keep the format spec consistent.
| ``` | ||
| ✅ "Créer un Cycle" (fr — natural cognate from glossary, identical to English) | ||
| ✅ "Crear un nuevo Ciclo" (es — natural Spanish cognate from glossary) | ||
| ✅ "Archiviare questo Modulo" (it — natural Italian cognate from glossary) | ||
| ✅ "Nueva Epic" (es — Epic has no clean cognate; stays Latin per glossary) | ||
| ✅ "Archivieren Sie diesen Zyklus" (de — natural German form from glossary) | ||
| ✅ "Buat Siklus baru" (id — natural Indonesian form from glossary) | ||
| ✅ "Buat Sticky baru" (id — Sticky is a Plane brand mark, stays Latin) | ||
| ✅ "Wechseln Sie zum Pro-Plan" (de — Pro is a plan tier name, stays Latin) | ||
| ❌ "Créer un Cycle" WRONG when the locale should be `Zyklus` (de). Always use the glossary form. | ||
| ❌ "Archivieren Sie diesen Cycle" (de — feature noun was left in Latin; use Zyklus per glossary) | ||
| ❌ "Créer un Cercle" (fr — invented translation; use the glossary form) | ||
| ❌ "Nueva Saga" (es — translated "Epic" with the wrong cognate) | ||
| ❌ "Buat Catatan Tempel" (id — translated "Sticky" which is a brand mark; keep Latin) | ||
| ``` |
There was a problem hiding this comment.
Add language identifiers to fenced code blocks.
Three fenced examples are missing language tags, which triggers markdownlint (MD040). Please annotate them (e.g., text, json, or md) to keep docs lint-clean and improve readability.
Suggested patch
-```
+```text
✅ "Créer un Cycle" (fr — natural cognate from glossary, identical to English)
...
❌ "Buat Catatan Tempel" (id — translated "Sticky" which is a brand mark; keep Latin)- +text
✅ "使用 GitHub 登录" (Latin brand → half-width spaces around)
...
❌ "创建赛克" (invented transliteration of Cycle — use the glossary's 周期)
-```
+```text
en: "Welcome, {name}! You have {count} new work items."
fr: "Bienvenue, {name} ! Vous avez {count} nouveaux work items."
ja: "{name}さん、ようこそ。{count}件の新しい作業項目があります。"
</details>
Also applies to: 202-214, 316-320
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.22.1)</summary>
[warning] 145-145: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.claude/skills/translate/SKILL.md around lines 145 - 159, Three fenced code
blocks in SKILL.md (the block starting with '✅ "Créer un Cycle" ...', the block
starting with '✅ "使用 GitHub 登录" ...', and the localization block starting with
'en: "Welcome, {name}! ..."') are missing language identifiers and trigger
markdownlint MD040; add an appropriate language tag (e.g., text for plain examples or json/```md if more suitable) to each opening fence to silence the
lint and improve readability, keeping the block contents unchanged.
</details>
<!-- fingerprinting:phantom:triton:hawk -->
<!-- This is an auto-generated comment by CodeRabbit -->
Description
Restructures the
.claude/skills/directory from flat single-file skills to per-skill folders, and updates the release-notes skill to match the GitHub Releases format used ongithub.com/makeplane/plane/releases.Changes:
pr-description.md→create-pull-request/SKILL.mdrelease-notes.md→release-notes/SKILL.mdbranch-name/SKILL.mdskill for producing branch names in the<type>/<work-item-id>-<short-description>formattranslate/SKILL.mdskill for managing keys inpackages/i18n/src/localesrelease-notes/SKILL.mdto produce notes matching the v1.2.0 format:### ✨ Features/### ⬆️ Enhancements/### 🐞 Bug fixes/### 🛡️ Security, with#### **Feature Name**subsections and product-voice paragraphs. Drops work item IDs and PR numbers from output, drops the Chores section, drops the# Release vX.Y.Zheading.Type of Change
Screenshots and Media (if applicable)
Test Scenarios
/release-noteson a recentrelease: vYY.MM.DD-Ncloud PR and confirm the generated body matches the v1.2.0 structure (section headings, no work item IDs, no version heading, no images)./release-noteson arelease: vX.Y.ZEE PR and confirm the same format applies./branch-nameand verify it produces a<type>/<work-item-id>-<short-description>slug./create-pull-requeston a feature branch and confirm it picks up the work item ID from the branch name and fills out the repo's PR template./translatewhile editing a key underpackages/i18n/src/localesand confirm the do-not-translate / placeholder rules are loaded.References
Summary by CodeRabbit