Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 77be19e

Browse files
jabrenacodex
jabrena
and
codex
authored
docs(readme): add ClaudSkills link and normalize Chinese suffix (#797)
* docs(readme): add ClaudSkills author link * docs(i18n): rename Chinese files to ZH suffix * docs(contributing): require AI coauthor attribution Regenerate the published website after updating site content. Co-authored-by: Codex <[email protected]> * docs(contributing): enforce website source synchronization Require site sources and generated docs to ship together, and document how to trace pre-existing generated-output drift. Co-authored-by: Codex <[email protected]> --------- Co-authored-by: Codex <[email protected]>
1 parent 52f9ba2 commit 77be19e

12 files changed

Lines changed: 40 additions & 19 deletions

File tree

‎AGENTS.md‎

Lines changed: 23 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -48,10 +48,10 @@ This project uses **OpenSpec** for structured change management and planning:
4848
- `documentation/guides/` – Contributor and user guides, including getting-started docs, inventories, and third-party references (WRITE)
4949
- `documentation/openspec/` – OpenSpec change management (proposals, specs, tasks) (WRITE)
5050
- `documentation/adr/` – Architecture Decision Records (WRITE)
51-
- `site-generator/content/` – Blog posts, courses, documentation (WRITE here to update website)
52-
- `docs/` – Generated static website for GitHub Pages (READ only)
53-
- `README.md` – Default project README (WRITE); keep `README_ES.md` and `README_CN.md` in sync when it changes
54-
- `documentation/guides/GETTING-STARTED-*.md` – Getting-started documentation; English files are the master source, so keep matching `_ES.md` and `_CN.md` versions in sync when localized counterparts exist
51+
- `site-generator/content/` – Blog posts, courses, documentation (WRITE here to update website; regenerate `docs/` in the same change)
52+
- `docs/` – Generated static website for GitHub Pages (READ only; update only through the `site-update` Maven profile)
53+
- `README.md` – Default project README (WRITE); keep `README_ES.md` and `README_ZH.md` in sync when it changes
54+
- `documentation/guides/GETTING-STARTED-*.md` – Getting-started documentation; English files are the master source, so keep matching `_ES.md` and `_ZH.md` versions in sync when localized counterparts exist
5555

5656
## Commands
5757

@@ -96,6 +96,14 @@ openspec archive <change-name> # Archive a completed change
9696

9797
```
9898

99+
## Website generation workflow
100+
101+
1. Edit website sources under `site-generator/content/`, `site-generator/templates/`, or `site-generator/assets/`; never edit `docs/` directly.
102+
2. Run `./mvnw clean generate-resources -pl site-generator -P site-update` in the same change whenever website sources change.
103+
3. Review every generated `docs/` diff and verify it corresponds to a current source, template, or asset change.
104+
4. If regeneration reveals output drift from a source change committed earlier, trace it with `git log` or `git blame`, retain the generated correction, and explain that provenance in the commit or pull request.
105+
5. Commit the website source and generated `docs/` output together so GitHub Pages never lags behind its source.
106+
99107
## Git workflow
100108

101109
- **Conventional Commits**: Use conventional commit format for all commit messages
@@ -117,6 +125,16 @@ openspec archive <change-name> # Archive a completed change
117125

118126
The [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) spec allows other types if your team agrees. **This repository’s commit-msg hook** accepts the types in the table above and requires a **scope** (see [`.pre-commit-config.yaml`](.pre-commit-config.yaml)).
119127

128+
### AI-assisted commits
129+
130+
When Cursor, Claude, Codex, or another AI tool authors or materially contributes to a commit, include a `Co-authored-by` trailer using the tool's documented Git identity:
131+
132+
```text
133+
Co-authored-by: <tool-name> <tool-email>
134+
```
135+
136+
Place the trailer after a blank line at the end of the commit message. Do not add an AI co-author when the tool only provided incidental assistance and did not contribute to the committed change.
137+
120138
### Pre-commit hooks (recommended)
121139

122140
This repository includes [pre-commit](https://pre-commit.com/) configuration at [`.pre-commit-config.yaml`](.pre-commit-config.yaml): YAML checks and a **commit-msg** hook that enforces the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) rules above (including a required **scope**).
@@ -137,6 +155,6 @@ pre-commit run conventional-pre-commit --hook-stage commit-msg --commit-msg-file
137155

138156
## Boundaries
139157

140-
- ✅ **Always do:** Edit XML in `skills-generator/src/main/resources/` (`skill-references/`, `skills/`) to change rules and skills, validate edited XML with `xmllint --noout <path-to-edited-file.xml>`, and run `./mvnw clean verify` before promoting changes. For local skill regeneration, use `./mvnw clean install -pl skills-generator` and test the generated output from `.agents/skills`; do not refresh `skills/` unless preparing an intentional release. For release skill changes, run `./mvnw clean install -pl skills-generator -P release`, then validate `skills/` with `npx skill-check@latest skills --no-security-scan --format github` and `skill-scanner scan-all ./skills --recursive --use-behavioral --policy strict --fail-on-severity high` when the scanner is available. When editing XML, follow PML Schema: [https://jabrena.github.io/pml/schemas/0.7.0/pml.xsd](https://jabrena.github.io/pml/schemas/0.7.0/pml.xsd). For complex changes, create OpenSpec proposals first. When you change `README.md`, update the translated READMEs (`README_ES.md`, `README_CN.md`) in the same change. When you change an English `documentation/guides/GETTING-STARTED-*.md` file, update the matching `_ES.md` and `_CN.md` files in the same change when they exist.
158+
- ✅ **Always do:** Edit XML in `skills-generator/src/main/resources/` (`skill-references/`, `skills/`) to change rules and skills, validate edited XML with `xmllint --noout <path-to-edited-file.xml>`, and run `./mvnw clean verify` before promoting changes. For local skill regeneration, use `./mvnw clean install -pl skills-generator` and test the generated output from `.agents/skills`; do not refresh `skills/` unless preparing an intentional release. For release skill changes, run `./mvnw clean install -pl skills-generator -P release`, then validate `skills/` with `npx skill-check@latest skills --no-security-scan --format github` and `skill-scanner scan-all ./skills --recursive --use-behavioral --policy strict --fail-on-severity high` when the scanner is available. When editing XML, follow PML Schema: [https://jabrena.github.io/pml/schemas/0.7.0/pml.xsd](https://jabrena.github.io/pml/schemas/0.7.0/pml.xsd). For complex changes, create OpenSpec proposals first. When website sources change, regenerate and review `docs/`, then commit source and output together. When you change `README.md`, update the translated READMEs (`README_ES.md`, `README_ZH.md`) in the same change. When you change an English `documentation/guides/GETTING-STARTED-*.md` file, update the matching `_ES.md` and `_ZH.md` files in the same change when they exist.
141159
- ⚠️ **Ask first:** Adding new XML rule files, modifying the XSLT stylesheet, changing site templates, architectural changes (use OpenSpec for planning)
142160
- 🚫 **Never do:** Edit `.cursor/rules/` or `docs/` directly, commit secrets, skip tests before promoting, bypass OpenSpec for major changes

‎CHANGELOG.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
3636

3737
- **Documentation:**
3838
- Improved project usage guidance in `README.md` and skills documentation (#732, #733)
39-
- Added localized README translations (`README_ES.md`, `README_CN.md`) with a language switcher in `README.md`, refreshed the Goal statement, and documented sync requirements in `AGENTS.md`
39+
- Added localized README translations (`README_ES.md`, `README_ZH.md`) with a language switcher in `README.md`, refreshed the Goal statement, and documented sync requirements in `AGENTS.md`
4040
- Third-party tools and links documented in `documentation/THIRD-PARTIES.md` (#734)
4141

4242
## [0.14.0] 2026-04-12

‎README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66

77
[![CI Builds](https://github.com/jabrena/cursor-rules-java/actions/workflows/maven.yaml/badge.svg)](https://github.com/jabrena/cursor-rules-java/actions/workflows/maven.yaml)
88

9-
> **Languages:** [Español](./README_ES.md) · [中文](./README_CN.md)
9+
> **Languages:** [Español](./README_ES.md) · [中文](./README_ZH.md)
1010
>
1111
> **Website:** https://jabrena.github.io/cursor-rules-java/
1212
>
@@ -159,6 +159,7 @@ Java uses JEPs (JDK Enhancement Proposals) to describe new language and platform
159159
- [https://openspec.dev/](https://openspec.dev/)
160160
- [https://skills.sh/jabrena/cursor-rules-java](https://skills.sh/jabrena/cursor-rules-java)
161161
- [https://tessl.io/registry/skills/github/jabrena/cursor-rules-java](https://tessl.io/registry/skills/github/jabrena/cursor-rules-java)
162+
- https://claudskills.com/author/jabrena/
162163
- https://agent-skills.cc/zh/skills/jabrena-cursor-rules-java
163164
- https://shyft.ai/skills/cursor-rules-java
164165
- https://lobehub.com/skills?q=cursor-rules-java

‎README_ES.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66

77
[![CI Builds](https://github.com/jabrena/cursor-rules-java/actions/workflows/maven.yaml/badge.svg)](https://github.com/jabrena/cursor-rules-java/actions/workflows/maven.yaml)
88

9-
> **Idiomas:** [English](./README.md) · [中文](./README_CN.md)
9+
> **Idiomas:** [English](./README.md) · [中文](./README_ZH.md)
1010
>
1111
> **Website:** https://jabrena.github.io/cursor-rules-java/
1212
>
@@ -159,6 +159,7 @@ Java usa JEPs (JDK Enhancement Proposals) para describir nuevas características
159159
- [https://openspec.dev/](https://openspec.dev/)
160160
- [https://skills.sh/jabrena/cursor-rules-java](https://skills.sh/jabrena/cursor-rules-java)
161161
- [https://tessl.io/registry/skills/github/jabrena/cursor-rules-java](https://tessl.io/registry/skills/github/jabrena/cursor-rules-java)
162+
- https://claudskills.com/author/jabrena/
162163
- https://agent-skills.cc/zh/skills/jabrena-cursor-rules-java
163164
- https://shyft.ai/skills/cursor-rules-java
164165
- https://lobehub.com/skills?q=cursor-rules-java

README_CN.md renamed to README_ZH.md

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -30,8 +30,8 @@
3030
| | 分析 / 设计 | 实现 | 运维 |
3131
| ------------- | ----------------- | -------------- | --------- |
3232
| Commands | [`/update-issue-description`](./.cursor/commands/update-issue-description.md) | [`/create-feature-branch`](./.cursor/commands/create-feature-branch.md) · [`/implement`](./.cursor/commands/implement.md) | [`/verify`](./.cursor/commands/verify.md) · [`/kill-port`](./.cursor/commands/kill-port.md) |
33-
| [Agents](./documentation/guides/GETTING-STARTED-AGENTS_CN.md) | `@robot-business-analyst` | `@robot-coordinator` · `@robot-java-coder` · `@robot-spring-boot-coder` · `@robot-quarkus-coder` · `@robot-micronaut-coder` | |
34-
| [Skills](./documentation/guides/GETTING-STARTED-SKILLS_CN.md) | [014-agile-user-story](https://www.skills.sh/jabrena/cursor-rules-java/014-agile-user-story) · [030-architecture-adr-general](https://www.skills.sh/jabrena/cursor-rules-java/030-architecture-adr-general) · [031-architecture-adr-functional-requirements](https://www.skills.sh/jabrena/cursor-rules-java/031-architecture-adr-functional-requirements) · [033-architecture-diagrams](https://www.skills.sh/jabrena/cursor-rules-java/033-architecture-diagrams) · [041-planning-plan-mode](https://www.skills.sh/jabrena/cursor-rules-java/041-planning-plan-mode) | [110-java-maven-best-practices](https://www.skills.sh/jabrena/cursor-rules-java/110-java-maven-best-practices) · [121-java-object-oriented-design](https://www.skills.sh/jabrena/cursor-rules-java/121-java-object-oriented-design) · [124-java-secure-coding](https://www.skills.sh/jabrena/cursor-rules-java/124-java-secure-coding) · [111-java-maven-dependencies](https://www.skills.sh/jabrena/cursor-rules-java/111-java-maven-dependencies) · [143-java-functional-exception-handling](https://www.skills.sh/jabrena/cursor-rules-java/143-java-functional-exception-handling) | [151-java-performance-jmeter](https://www.skills.sh/jabrena/cursor-rules-java/151-java-performance-jmeter) · [162-java-profiling-analyze](https://www.skills.sh/jabrena/cursor-rules-java/162-java-profiling-analyze) · [161-java-profiling-detect](https://www.skills.sh/jabrena/cursor-rules-java/161-java-profiling-detect) · [163-java-profiling-refactor](https://www.skills.sh/jabrena/cursor-rules-java/163-java-profiling-refactor) · [164-java-profiling-verify](https://www.skills.sh/jabrena/cursor-rules-java/164-java-profiling-verify) |
33+
| [Agents](./documentation/guides/GETTING-STARTED-AGENTS_ZH.md) | `@robot-business-analyst` | `@robot-coordinator` · `@robot-java-coder` · `@robot-spring-boot-coder` · `@robot-quarkus-coder` · `@robot-micronaut-coder` | |
34+
| [Skills](./documentation/guides/GETTING-STARTED-SKILLS_ZH.md) | [014-agile-user-story](https://www.skills.sh/jabrena/cursor-rules-java/014-agile-user-story) · [030-architecture-adr-general](https://www.skills.sh/jabrena/cursor-rules-java/030-architecture-adr-general) · [031-architecture-adr-functional-requirements](https://www.skills.sh/jabrena/cursor-rules-java/031-architecture-adr-functional-requirements) · [033-architecture-diagrams](https://www.skills.sh/jabrena/cursor-rules-java/033-architecture-diagrams) · [041-planning-plan-mode](https://www.skills.sh/jabrena/cursor-rules-java/041-planning-plan-mode) | [110-java-maven-best-practices](https://www.skills.sh/jabrena/cursor-rules-java/110-java-maven-best-practices) · [121-java-object-oriented-design](https://www.skills.sh/jabrena/cursor-rules-java/121-java-object-oriented-design) · [124-java-secure-coding](https://www.skills.sh/jabrena/cursor-rules-java/124-java-secure-coding) · [111-java-maven-dependencies](https://www.skills.sh/jabrena/cursor-rules-java/111-java-maven-dependencies) · [143-java-functional-exception-handling](https://www.skills.sh/jabrena/cursor-rules-java/143-java-functional-exception-handling) | [151-java-performance-jmeter](https://www.skills.sh/jabrena/cursor-rules-java/151-java-performance-jmeter) · [162-java-profiling-analyze](https://www.skills.sh/jabrena/cursor-rules-java/162-java-profiling-analyze) · [161-java-profiling-detect](https://www.skills.sh/jabrena/cursor-rules-java/161-java-profiling-detect) · [163-java-profiling-refactor](https://www.skills.sh/jabrena/cursor-rules-java/163-java-profiling-refactor) · [164-java-profiling-verify](https://www.skills.sh/jabrena/cursor-rules-java/164-java-profiling-verify) |
3535
| [MCP Servers](./documentation/guides/THIRD-PARTIES.md) | [JDBC](https://github.com/quarkiverse/quarkus-mcp-servers/blob/main/jdbc/README.md) | [JavaDocs](https://www.javadocs.dev/mcp) · [Serena](https://oraios.github.io/serena/01-about/000_intro.html) | [Graphana](https://grafana.com/docs/grafana/latest/developer-resources/mcp/) |
3636

3737
## 交付物
@@ -41,8 +41,8 @@
4141
| 清单 | 安装 | 快速入门 |
4242
| --------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
4343
| 1. [Commands](./documentation/guides/INVENTORY-COMMANDS-JAVA.md) | `@004-commands-installation` 在项目中安装 Commands | [`Commands`](./documentation/guides/COMMANDS.md) |
44-
| 2. [Agents](./documentation/guides/INVENTORY-AGENTS-JAVA.md) | `@005-agents-installation` 在 Cursor/Claude 中安装 Agents | [`Agents`](./documentation/guides/GETTING-STARTED-AGENTS_CN.md) |
45-
| 3. [Skills](./documentation/guides/INVENTORY-SKILLS-JAVA.md) | `npx skills add jabrena/cursor-rules-java --all --agent cursor` | [`Skills`](./documentation/guides/GETTING-STARTED-SKILLS_CN.md) |
44+
| 2. [Agents](./documentation/guides/INVENTORY-AGENTS-JAVA.md) | `@005-agents-installation` 在 Cursor/Claude 中安装 Agents | [`Agents`](./documentation/guides/GETTING-STARTED-AGENTS_ZH.md) |
45+
| 3. [Skills](./documentation/guides/INVENTORY-SKILLS-JAVA.md) | `npx skills add jabrena/cursor-rules-java --all --agent cursor` | [`Skills`](./documentation/guides/GETTING-STARTED-SKILLS_ZH.md) |
4646

4747
**⚠️ 注意：** 若你仍在使用本项目的 System prompts/rules，请阅读[相关文章](https://jabrena.github.io/cursor-rules-java/blog/2026/04/release-0.14.0.html)。当前的 `System prompts/rules` 将在下一版本（v0.16.0）中移除。
4848

@@ -72,7 +72,7 @@
7272

7373
![](./documentation/images/workflow-pipelines.png)
7474

75-
更多信息见[此处](./documentation/guides/GETTING-STARTED-PIPELINES_CN.md)。
75+
更多信息见[此处](./documentation/guides/GETTING-STARTED-PIPELINES_ZH.md)。
7676

7777
## 局限性
7878

@@ -159,6 +159,7 @@ Java 使用 JEP（JDK Enhancement Proposals）描述新的语言与平台特性
159159
- [https://openspec.dev/](https://openspec.dev/)
160160
- [https://skills.sh/jabrena/cursor-rules-java](https://skills.sh/jabrena/cursor-rules-java)
161161
- [https://tessl.io/registry/skills/github/jabrena/cursor-rules-java](https://tessl.io/registry/skills/github/jabrena/cursor-rules-java)
162+
- https://claudskills.com/author/jabrena/
162163
- https://agent-skills.cc/zh/skills/jabrena-cursor-rules-java
163164
- https://shyft.ai/skills/cursor-rules-java
164165
- https://lobehub.com/skills?q=cursor-rules-java

‎docs/blog/2026/04/release-0.14.0.html‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -199,8 +199,8 @@ <h3>Skill inventory</h3>
199199
npx skills add jabrena/cursor-rules-java --all --agent claude-code
200200
</code></pre>
201201
<p>Once you have the skills installed, you can install the <code>Agents</code> with:</p>
202-
<pre><code>@003-agents-installation Install Agents in Cursor
203-
@003-agents-installation Install Agents in Claude
202+
<pre><code>@005-agents-installation Install Agents in Cursor
203+
@005-agents-installation Install Agents in Claude
204204
</code></pre>
205205
<h2>Evolution of this project in Vercel's Skills registry</h2>
206206
<p>The ecosystem is large, so you will need your own criteria beyond whether this project fits your preferences.</p>

‎docs/blog/2026/06/release-0.15.0.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -157,7 +157,7 @@ <h3>Better documentation</h3>
157157
<p>The project now provides documentation in three languages:</p>
158158
<ul>
159159
<li><a href="https://github.com/jabrena/cursor-rules-java/blob/main/README.md"><code>English</code></a></li>
160-
<li><a href="https://github.com/jabrena/cursor-rules-java/blob/main/README_CN.md"><code>Chinese</code></a></li>
160+
<li><a href="https://github.com/jabrena/cursor-rules-java/blob/main/README_ZH.md"><code>Chinese</code></a></li>
161161
<li><a href="https://github.com/jabrena/cursor-rules-java/blob/main/README_ES.md"><code>Spanish</code></a></li>
162162
</ul>
163163
<h2>Evolution of this project in Vercel's Skills registry</h2>

‎docs/feed.xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
<feed xmlns='http://www.w3.org/2005/Atom' xml:lang='en'>
33
<id>https://jabrena.github.io/cursor-rules-java/</id>
44
<title>Skills & Agents for Java</title>
5-
<updated>2026-05-31T17:44:31+0200</updated>
5+
<updated>2026-06-06T12:20:37+0200</updated>
66
<link rel="alternate" type="text/html" href="https://jabrena.github.io/cursor-rules-java/" />
77
<link rel='self' type='application/atom+xml' href='https://jabrena.github.io/cursor-rules-java//feed.xml' />
88
<entry>

documentation/guides/GETTING-STARTED-AGENTS_CN.md renamed to documentation/guides/GETTING-STARTED-AGENTS_ZH.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818

1919
### 对 Skills 和 System prompts 的依赖
2020

21-
这些智能体假设你可以附加 **Skills**（见 [Java Skills 快速入门](GETTING-STARTED-SKILLS_CN.md)）和/或 **Cursor rules**（见 [Getting started for System prompts for Java](GETTING-STARTED-SYSTEM-PROMPTS.md)），这样聊天中的 `@...` 引用才能解析。实现智能体会明确命名具体的 skill 前缀（例如 `@322-frameworks-spring-boot-testing-integration-tests`）。
21+
这些智能体假设你可以附加 **Skills**（见 [Java Skills 快速入门](GETTING-STARTED-SKILLS_ZH.md)）和/或 **Cursor rules**（见 [Getting started for System prompts for Java](GETTING-STARTED-SYSTEM-PROMPTS.md)），这样聊天中的 `@...` 引用才能解析。实现智能体会明确命名具体的 skill 前缀（例如 `@322-frameworks-spring-boot-testing-integration-tests`）。
2222

2323
## 如何安装 Agents？
2424

documentation/guides/GETTING-STARTED-PIPELINES_CN.md renamed to documentation/guides/GETTING-STARTED-PIPELINES_ZH.md

File renamed without changes.

0 commit comments

Comments
 (0)