From d58c2f764285c0d0d24d59df21071d22e0390770 Mon Sep 17 00:00:00 2001 From: Decebal Suiu Date: Fri, 28 Aug 2026 23:32:52 +0300 Subject: [PATCH 1/4] refactor: move skills to skills/ with a compatibility symlink The Agent Plugins standard expects skills under skills/ at the repository root. Ours were under .claude/skills/, a path named after one client, which sits badly with a project that describes itself by the open format it follows. .claude/skills stays as a symlink, so links people already made keep resolving. Git records the move as a rename, so history survives, and a symlink to a symlink resolves, so anyone who ran link-skills.sh notices nothing. This commit only moves files. Nothing inside them changes, which is the easiest kind of change for a fork to merge. --- .claude/skills | 1 + {.claude/skills => skills}/README.md | 0 {.claude/skills => skills}/api-contract-review/README.md | 0 {.claude/skills => skills}/api-contract-review/SKILL.md | 0 {.claude/skills => skills}/architecture-review/README.md | 0 {.claude/skills => skills}/architecture-review/SKILL.md | 0 {.claude/skills => skills}/changelog-generator/README.md | 0 {.claude/skills => skills}/changelog-generator/SKILL.md | 0 {.claude/skills => skills}/clean-code/README.md | 0 {.claude/skills => skills}/clean-code/SKILL.md | 0 {.claude/skills => skills}/concurrency-review/README.md | 0 {.claude/skills => skills}/concurrency-review/SKILL.md | 0 {.claude/skills => skills}/design-patterns/README.md | 0 {.claude/skills => skills}/design-patterns/SKILL.md | 0 {.claude/skills => skills}/git-commit/README.md | 0 {.claude/skills => skills}/git-commit/SKILL.md | 0 {.claude/skills => skills}/issue-triage/README.md | 0 {.claude/skills => skills}/issue-triage/SKILL.md | 0 {.claude/skills => skills}/java-code-review/README.md | 0 {.claude/skills => skills}/java-code-review/SKILL.md | 0 {.claude/skills => skills}/java-migration/README.md | 0 {.claude/skills => skills}/java-migration/SKILL.md | 0 {.claude/skills => skills}/jpa-patterns/README.md | 0 {.claude/skills => skills}/jpa-patterns/SKILL.md | 0 {.claude/skills => skills}/logging-patterns/README.md | 0 {.claude/skills => skills}/logging-patterns/SKILL.md | 0 {.claude/skills => skills}/maven-dependency-audit/README.md | 0 {.claude/skills => skills}/maven-dependency-audit/SKILL.md | 0 {.claude/skills => skills}/performance-smell-detection/README.md | 0 {.claude/skills => skills}/performance-smell-detection/SKILL.md | 0 {.claude/skills => skills}/security-audit/README.md | 0 {.claude/skills => skills}/security-audit/SKILL.md | 0 {.claude/skills => skills}/solid-principles/README.md | 0 {.claude/skills => skills}/solid-principles/SKILL.md | 0 {.claude/skills => skills}/spring-boot-patterns/README.md | 0 {.claude/skills => skills}/spring-boot-patterns/SKILL.md | 0 {.claude/skills => skills}/test-quality/README.md | 0 {.claude/skills => skills}/test-quality/SKILL.md | 0 38 files changed, 1 insertion(+) create mode 120000 .claude/skills rename {.claude/skills => skills}/README.md (100%) rename {.claude/skills => skills}/api-contract-review/README.md (100%) rename {.claude/skills => skills}/api-contract-review/SKILL.md (100%) rename {.claude/skills => skills}/architecture-review/README.md (100%) rename {.claude/skills => skills}/architecture-review/SKILL.md (100%) rename {.claude/skills => skills}/changelog-generator/README.md (100%) rename {.claude/skills => skills}/changelog-generator/SKILL.md (100%) rename {.claude/skills => skills}/clean-code/README.md (100%) rename {.claude/skills => skills}/clean-code/SKILL.md (100%) rename {.claude/skills => skills}/concurrency-review/README.md (100%) rename {.claude/skills => skills}/concurrency-review/SKILL.md (100%) rename {.claude/skills => skills}/design-patterns/README.md (100%) rename {.claude/skills => skills}/design-patterns/SKILL.md (100%) rename {.claude/skills => skills}/git-commit/README.md (100%) rename {.claude/skills => skills}/git-commit/SKILL.md (100%) rename {.claude/skills => skills}/issue-triage/README.md (100%) rename {.claude/skills => skills}/issue-triage/SKILL.md (100%) rename {.claude/skills => skills}/java-code-review/README.md (100%) rename {.claude/skills => skills}/java-code-review/SKILL.md (100%) rename {.claude/skills => skills}/java-migration/README.md (100%) rename {.claude/skills => skills}/java-migration/SKILL.md (100%) rename {.claude/skills => skills}/jpa-patterns/README.md (100%) rename {.claude/skills => skills}/jpa-patterns/SKILL.md (100%) rename {.claude/skills => skills}/logging-patterns/README.md (100%) rename {.claude/skills => skills}/logging-patterns/SKILL.md (100%) rename {.claude/skills => skills}/maven-dependency-audit/README.md (100%) rename {.claude/skills => skills}/maven-dependency-audit/SKILL.md (100%) rename {.claude/skills => skills}/performance-smell-detection/README.md (100%) rename {.claude/skills => skills}/performance-smell-detection/SKILL.md (100%) rename {.claude/skills => skills}/security-audit/README.md (100%) rename {.claude/skills => skills}/security-audit/SKILL.md (100%) rename {.claude/skills => skills}/solid-principles/README.md (100%) rename {.claude/skills => skills}/solid-principles/SKILL.md (100%) rename {.claude/skills => skills}/spring-boot-patterns/README.md (100%) rename {.claude/skills => skills}/spring-boot-patterns/SKILL.md (100%) rename {.claude/skills => skills}/test-quality/README.md (100%) rename {.claude/skills => skills}/test-quality/SKILL.md (100%) diff --git a/.claude/skills b/.claude/skills new file mode 120000 index 0000000..42c5394 --- /dev/null +++ b/.claude/skills @@ -0,0 +1 @@ +../skills \ No newline at end of file diff --git a/.claude/skills/README.md b/skills/README.md similarity index 100% rename from .claude/skills/README.md rename to skills/README.md diff --git a/.claude/skills/api-contract-review/README.md b/skills/api-contract-review/README.md similarity index 100% rename from .claude/skills/api-contract-review/README.md rename to skills/api-contract-review/README.md diff --git a/.claude/skills/api-contract-review/SKILL.md b/skills/api-contract-review/SKILL.md similarity index 100% rename from .claude/skills/api-contract-review/SKILL.md rename to skills/api-contract-review/SKILL.md diff --git a/.claude/skills/architecture-review/README.md b/skills/architecture-review/README.md similarity index 100% rename from .claude/skills/architecture-review/README.md rename to skills/architecture-review/README.md diff --git a/.claude/skills/architecture-review/SKILL.md b/skills/architecture-review/SKILL.md similarity index 100% rename from .claude/skills/architecture-review/SKILL.md rename to skills/architecture-review/SKILL.md diff --git a/.claude/skills/changelog-generator/README.md b/skills/changelog-generator/README.md similarity index 100% rename from .claude/skills/changelog-generator/README.md rename to skills/changelog-generator/README.md diff --git a/.claude/skills/changelog-generator/SKILL.md b/skills/changelog-generator/SKILL.md similarity index 100% rename from .claude/skills/changelog-generator/SKILL.md rename to skills/changelog-generator/SKILL.md diff --git a/.claude/skills/clean-code/README.md b/skills/clean-code/README.md similarity index 100% rename from .claude/skills/clean-code/README.md rename to skills/clean-code/README.md diff --git a/.claude/skills/clean-code/SKILL.md b/skills/clean-code/SKILL.md similarity index 100% rename from .claude/skills/clean-code/SKILL.md rename to skills/clean-code/SKILL.md diff --git a/.claude/skills/concurrency-review/README.md b/skills/concurrency-review/README.md similarity index 100% rename from .claude/skills/concurrency-review/README.md rename to skills/concurrency-review/README.md diff --git a/.claude/skills/concurrency-review/SKILL.md b/skills/concurrency-review/SKILL.md similarity index 100% rename from .claude/skills/concurrency-review/SKILL.md rename to skills/concurrency-review/SKILL.md diff --git a/.claude/skills/design-patterns/README.md b/skills/design-patterns/README.md similarity index 100% rename from .claude/skills/design-patterns/README.md rename to skills/design-patterns/README.md diff --git a/.claude/skills/design-patterns/SKILL.md b/skills/design-patterns/SKILL.md similarity index 100% rename from .claude/skills/design-patterns/SKILL.md rename to skills/design-patterns/SKILL.md diff --git a/.claude/skills/git-commit/README.md b/skills/git-commit/README.md similarity index 100% rename from .claude/skills/git-commit/README.md rename to skills/git-commit/README.md diff --git a/.claude/skills/git-commit/SKILL.md b/skills/git-commit/SKILL.md similarity index 100% rename from .claude/skills/git-commit/SKILL.md rename to skills/git-commit/SKILL.md diff --git a/.claude/skills/issue-triage/README.md b/skills/issue-triage/README.md similarity index 100% rename from .claude/skills/issue-triage/README.md rename to skills/issue-triage/README.md diff --git a/.claude/skills/issue-triage/SKILL.md b/skills/issue-triage/SKILL.md similarity index 100% rename from .claude/skills/issue-triage/SKILL.md rename to skills/issue-triage/SKILL.md diff --git a/.claude/skills/java-code-review/README.md b/skills/java-code-review/README.md similarity index 100% rename from .claude/skills/java-code-review/README.md rename to skills/java-code-review/README.md diff --git a/.claude/skills/java-code-review/SKILL.md b/skills/java-code-review/SKILL.md similarity index 100% rename from .claude/skills/java-code-review/SKILL.md rename to skills/java-code-review/SKILL.md diff --git a/.claude/skills/java-migration/README.md b/skills/java-migration/README.md similarity index 100% rename from .claude/skills/java-migration/README.md rename to skills/java-migration/README.md diff --git a/.claude/skills/java-migration/SKILL.md b/skills/java-migration/SKILL.md similarity index 100% rename from .claude/skills/java-migration/SKILL.md rename to skills/java-migration/SKILL.md diff --git a/.claude/skills/jpa-patterns/README.md b/skills/jpa-patterns/README.md similarity index 100% rename from .claude/skills/jpa-patterns/README.md rename to skills/jpa-patterns/README.md diff --git a/.claude/skills/jpa-patterns/SKILL.md b/skills/jpa-patterns/SKILL.md similarity index 100% rename from .claude/skills/jpa-patterns/SKILL.md rename to skills/jpa-patterns/SKILL.md diff --git a/.claude/skills/logging-patterns/README.md b/skills/logging-patterns/README.md similarity index 100% rename from .claude/skills/logging-patterns/README.md rename to skills/logging-patterns/README.md diff --git a/.claude/skills/logging-patterns/SKILL.md b/skills/logging-patterns/SKILL.md similarity index 100% rename from .claude/skills/logging-patterns/SKILL.md rename to skills/logging-patterns/SKILL.md diff --git a/.claude/skills/maven-dependency-audit/README.md b/skills/maven-dependency-audit/README.md similarity index 100% rename from .claude/skills/maven-dependency-audit/README.md rename to skills/maven-dependency-audit/README.md diff --git a/.claude/skills/maven-dependency-audit/SKILL.md b/skills/maven-dependency-audit/SKILL.md similarity index 100% rename from .claude/skills/maven-dependency-audit/SKILL.md rename to skills/maven-dependency-audit/SKILL.md diff --git a/.claude/skills/performance-smell-detection/README.md b/skills/performance-smell-detection/README.md similarity index 100% rename from .claude/skills/performance-smell-detection/README.md rename to skills/performance-smell-detection/README.md diff --git a/.claude/skills/performance-smell-detection/SKILL.md b/skills/performance-smell-detection/SKILL.md similarity index 100% rename from .claude/skills/performance-smell-detection/SKILL.md rename to skills/performance-smell-detection/SKILL.md diff --git a/.claude/skills/security-audit/README.md b/skills/security-audit/README.md similarity index 100% rename from .claude/skills/security-audit/README.md rename to skills/security-audit/README.md diff --git a/.claude/skills/security-audit/SKILL.md b/skills/security-audit/SKILL.md similarity index 100% rename from .claude/skills/security-audit/SKILL.md rename to skills/security-audit/SKILL.md diff --git a/.claude/skills/solid-principles/README.md b/skills/solid-principles/README.md similarity index 100% rename from .claude/skills/solid-principles/README.md rename to skills/solid-principles/README.md diff --git a/.claude/skills/solid-principles/SKILL.md b/skills/solid-principles/SKILL.md similarity index 100% rename from .claude/skills/solid-principles/SKILL.md rename to skills/solid-principles/SKILL.md diff --git a/.claude/skills/spring-boot-patterns/README.md b/skills/spring-boot-patterns/README.md similarity index 100% rename from .claude/skills/spring-boot-patterns/README.md rename to skills/spring-boot-patterns/README.md diff --git a/.claude/skills/spring-boot-patterns/SKILL.md b/skills/spring-boot-patterns/SKILL.md similarity index 100% rename from .claude/skills/spring-boot-patterns/SKILL.md rename to skills/spring-boot-patterns/SKILL.md diff --git a/.claude/skills/test-quality/README.md b/skills/test-quality/README.md similarity index 100% rename from .claude/skills/test-quality/README.md rename to skills/test-quality/README.md diff --git a/.claude/skills/test-quality/SKILL.md b/skills/test-quality/SKILL.md similarity index 100% rename from .claude/skills/test-quality/SKILL.md rename to skills/test-quality/SKILL.md From 6c751d7bc9402c42d58d230854ebeab3d88fcd39 Mon Sep 17 00:00:00 2001 From: Decebal Suiu Date: Fri, 28 Aug 2026 23:33:37 +0300 Subject: [PATCH 2/4] refactor: point the repo's own paths at skills/ link-skills.sh now links skills/ into a project, still as .claude/skills on the receiving side, which is where a client looks. The workflow path filters, the documentation and the README tables follow the new location. Paths that describe a consumer's project rather than this repository are left alone. In a project set up by link-skills.sh the skills are still at .claude/skills, so the templates and the per-skill READMEs are already correct. --- .github/workflows/skill-review.yml | 4 +-- .github/workflows/test.yml | 4 +-- README.md | 42 +++++++++++++++--------------- docs/SKILL_GUIDELINES.md | 6 ++--- scripts/link-skills.sh | 4 +-- scripts/test-all.sh | 2 +- skills/README.md | 2 +- 7 files changed, 32 insertions(+), 32 deletions(-) diff --git a/.github/workflows/skill-review.yml b/.github/workflows/skill-review.yml index c6a61a0..203c446 100644 --- a/.github/workflows/skill-review.yml +++ b/.github/workflows/skill-review.yml @@ -4,7 +4,7 @@ on: pull_request: types: [opened, synchronize] paths: - - '.claude/skills/**' + - 'skills/**' jobs: review: @@ -35,7 +35,7 @@ jobs: STEP 1: Run `gh pr diff ${{ github.event.pull_request.number }}` to see exactly what changed. STEP 2: Read docs/SKILL_GUIDELINES.md to understand validation criteria. - STEP 3: Read .claude/skills/README.md to check for overlap with existing skills. + STEP 3: Read skills/README.md to check for overlap with existing skills. STEP 4: Validate ONLY the changed files against these criteria: Structure and spec conformance are already checked by diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index d1875a1..d7c8943 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -33,7 +33,7 @@ jobs: - name: Validate every skill run: | fail=0 - for d in .claude/skills/*/; do + for d in skills/*/; do if ! out=$(agentskills validate "$d" 2>&1); then fail=1 echo "::error file=${d}SKILL.md::$(echo "$out" | tr '\n' ' ')" @@ -41,5 +41,5 @@ jobs: echo "$out" | sed 's/^/ /' fi done - echo "Validated $(ls -d .claude/skills/*/ | wc -l) skills." + echo "Validated $(ls -d skills/*/ | wc -l) skills." exit $fail diff --git a/README.md b/README.md index 764d844..4f91dba 100644 --- a/README.md +++ b/README.md @@ -46,10 +46,10 @@ This creates `.claude/` with symlinked skills, generates `CLAUDE.md`, and config mkdir -p your-project/.claude/skills # Copy specific skills -cp -r ~/projects/claude-code-java/.claude/skills/java-code-review your-project/.claude/skills/ +cp -r ~/projects/claude-code-java/skills/java-code-review your-project/.claude/skills/ # Or symlink all skills -ln -s ~/projects/claude-code-java/.claude/skills/* your-project/.claude/skills/ +ln -s ~/projects/claude-code-java/skills/* your-project/.claude/skills/ ``` ### 3. Use with Claude Code @@ -69,38 +69,38 @@ Skills are automatically loaded by Claude Code based on context. ### Workflow | Skill | Trigger Examples | |-------|------------------| -| [**git-commit**](.claude/skills/git-commit/) | "commit these changes", "create commit" | -| [**changelog-generator**](.claude/skills/changelog-generator/) | "generate changelog", "what changed since release" | -| [**issue-triage**](.claude/skills/issue-triage/) | "triage issues", "check open issues" | +| [**git-commit**](skills/git-commit/) | "commit these changes", "create commit" | +| [**changelog-generator**](skills/changelog-generator/) | "generate changelog", "what changed since release" | +| [**issue-triage**](skills/issue-triage/) | "triage issues", "check open issues" | ### Code Quality | Skill | Trigger Examples | |-------|------------------| -| [**java-code-review**](.claude/skills/java-code-review/) | "review this code", "check this PR" | -| [**api-contract-review**](.claude/skills/api-contract-review/) | "review API", "check REST endpoints" | -| [**concurrency-review**](.claude/skills/concurrency-review/) | "check thread safety", "review async code" | -| [**performance-smell-detection**](.claude/skills/performance-smell-detection/) | "check performance", "find slow code" | -| [**test-quality**](.claude/skills/test-quality/) | "add tests", "improve coverage" | -| [**maven-dependency-audit**](.claude/skills/maven-dependency-audit/) | "check dependencies", "audit deps" | -| [**security-audit**](.claude/skills/security-audit/) | "security review", "check OWASP", "vulnerabilities" | +| [**java-code-review**](skills/java-code-review/) | "review this code", "check this PR" | +| [**api-contract-review**](skills/api-contract-review/) | "review API", "check REST endpoints" | +| [**concurrency-review**](skills/concurrency-review/) | "check thread safety", "review async code" | +| [**performance-smell-detection**](skills/performance-smell-detection/) | "check performance", "find slow code" | +| [**test-quality**](skills/test-quality/) | "add tests", "improve coverage" | +| [**maven-dependency-audit**](skills/maven-dependency-audit/) | "check dependencies", "audit deps" | +| [**security-audit**](skills/security-audit/) | "security review", "check OWASP", "vulnerabilities" | ### Architecture & Design | Skill | Trigger Examples | |-------|------------------| -| [**architecture-review**](.claude/skills/architecture-review/) | "review architecture", "check package structure" | -| [**solid-principles**](.claude/skills/solid-principles/) | "check SOLID", "single responsibility" | -| [**design-patterns**](.claude/skills/design-patterns/) | "use factory pattern", "implement strategy" | -| [**clean-code**](.claude/skills/clean-code/) | "clean this code", "refactor" | +| [**architecture-review**](skills/architecture-review/) | "review architecture", "check package structure" | +| [**solid-principles**](skills/solid-principles/) | "check SOLID", "single responsibility" | +| [**design-patterns**](skills/design-patterns/) | "use factory pattern", "implement strategy" | +| [**clean-code**](skills/clean-code/) | "clean this code", "refactor" | ### Framework & Data | Skill | Trigger Examples | |-------|------------------| -| [**spring-boot-patterns**](.claude/skills/spring-boot-patterns/) | "create controller", "Spring Boot help" | -| [**java-migration**](.claude/skills/java-migration/) | "upgrade to Java 21", "migrate from Java 8" | -| [**jpa-patterns**](.claude/skills/jpa-patterns/) | "N+1 problem", "LazyInitializationException" | -| [**logging-patterns**](.claude/skills/logging-patterns/) | "add logging", "debug this flow", "analyze logs" | +| [**spring-boot-patterns**](skills/spring-boot-patterns/) | "create controller", "Spring Boot help" | +| [**java-migration**](skills/java-migration/) | "upgrade to Java 21", "migrate from Java 8" | +| [**jpa-patterns**](skills/jpa-patterns/) | "N+1 problem", "LazyInitializationException" | +| [**logging-patterns**](skills/logging-patterns/) | "add logging", "debug this flow", "analyze logs" | -See [.claude/skills/README.md](.claude/skills/README.md) for full documentation and [docs/SCRIPTS.md](docs/SCRIPTS.md) for setup script options. +See [skills/README.md](skills/README.md) for full documentation and [docs/SCRIPTS.md](docs/SCRIPTS.md) for setup script options. ## Project Structure diff --git a/docs/SKILL_GUIDELINES.md b/docs/SKILL_GUIDELINES.md index 127ff1d..8edc28c 100644 --- a/docs/SKILL_GUIDELINES.md +++ b/docs/SKILL_GUIDELINES.md @@ -104,7 +104,7 @@ A skill should be completable in one session. Signs it's too broad: Every skill has two files: ``` -.claude/skills// +skills// ├── SKILL.md # Instructions for the agent (the AI reads this) └── README.md # Documentation for humans ``` @@ -252,7 +252,7 @@ Before committing: ### Automated Review -PRs that modify `.claude/skills/` are automatically reviewed against these guidelines. +PRs that modify `skills/` are automatically reviewed against these guidelines. The review checks: - **Structure**: frontmatter, required files, folder convention - **Overlap**: comparison with existing skills @@ -373,7 +373,7 @@ A skill is mature when: Consider adding to your skill folder: ``` -.claude/skills// +skills// ├── SKILL.md ├── README.md └── CHANGELOG.md # Optional: track refinements diff --git a/scripts/link-skills.sh b/scripts/link-skills.sh index 2903b0e..a123718 100755 --- a/scripts/link-skills.sh +++ b/scripts/link-skills.sh @@ -21,7 +21,7 @@ success() { echo -e "${GREEN}✅ $1${NC}"; } info() { echo -e "${BLUE}ℹ️ $1${NC}"; } # Check dirs -[ ! -d "$WORKSPACE_DIR/.claude/skills" ] && error "Skills not found at $WORKSPACE_DIR/.claude/skills" +[ ! -d "$WORKSPACE_DIR/skills" ] && error "Skills not found at $WORKSPACE_DIR/skills" [ ! -d "$PROJECT_DIR" ] && error "Project dir not found: $PROJECT_DIR" # Create .claude if missing @@ -33,7 +33,7 @@ if [ -L "$PROJECT_DIR/.claude/skills" ]; then elif [ -d "$PROJECT_DIR/.claude/skills" ]; then echo -e "${YELLOW}⚠️ .claude/skills exists but is not a symlink. Backup/remove manually.${NC}" else - ln -sf "$WORKSPACE_DIR/.claude/skills" "$PROJECT_DIR/.claude/skills" + ln -sf "$WORKSPACE_DIR/skills" "$PROJECT_DIR/.claude/skills" success "Linked skills to project" fi diff --git a/scripts/test-all.sh b/scripts/test-all.sh index 80ebc07..d18e1a5 100755 --- a/scripts/test-all.sh +++ b/scripts/test-all.sh @@ -35,7 +35,7 @@ echo "Testing link-skills.sh..." check ".claude directory created" [ -d "$TEST_DIR/.claude" ] check "skills symlink created" [ -L "$TEST_DIR/.claude/skills" ] LINK_TARGET=$(readlink "$TEST_DIR/.claude/skills" 2>/dev/null || echo "") -check "symlink points to workspace" [ "$LINK_TARGET" = "$WORKSPACE_DIR/.claude/skills" ] +check "symlink points to workspace" [ "$LINK_TARGET" = "$WORKSPACE_DIR/skills" ] echo "" # Test 2: generate-claude-md.sh diff --git a/skills/README.md b/skills/README.md index f91d99e..5c5477a 100644 --- a/skills/README.md +++ b/skills/README.md @@ -64,7 +64,7 @@ Validate your skill idea against existing skills: ### Implementation Steps -1. Create folder: `.claude/skills//`. The folder name must be lowercase alphanumeric with single hyphens, and the `name` in the frontmatter must match it. +1. Create folder: `skills//`. The folder name must be lowercase alphanumeric with single hyphens, and the `name` in the frontmatter must match it. 2. Create `SKILL.md` with instructions for the agent. Required frontmatter is `name` and `description`; `license`, `compatibility`, `metadata` and `allowed-tools` are optional and no other top-level field is allowed. 3. Create `README.md` with human documentation (use existing READMEs as template) 4. Update this table From 6c4de854e5223a42e94f100a055ffe14722665b4 Mon Sep 17 00:00:00 2001 From: Decebal Suiu Date: Fri, 28 Aug 2026 23:33:37 +0300 Subject: [PATCH 3/4] feat: declare the repository as an Agent Plugin plugin.json validates against the 1.0.0 schema. With skills/ in place, a client that reads the manifest finds them where the standard says they are. The manifest is named java-agent-skills rather than after the repository. What a client shows in its plugin list should say what the thing is, and the repository keeps the name people search for. The version now lives in plugin.json, since clients read it from there. The changelog carries the same number, and validate-skills.sh fails when the two disagree, so one cannot be bumped without the other. It also checks that the .claude/skills compatibility path still resolves, which a checkout without symlink support breaks silently. --- docs/RELEASING.md | 20 +++++++++----------- docs/SCRIPTS.md | 4 ++++ plugin.json | 14 ++++++++++++++ scripts/validate-skills.sh | 26 +++++++++++++++++++++++++- 4 files changed, 52 insertions(+), 12 deletions(-) create mode 100644 plugin.json diff --git a/docs/RELEASING.md b/docs/RELEASING.md index defb44b..fd89822 100644 --- a/docs/RELEASING.md +++ b/docs/RELEASING.md @@ -10,23 +10,21 @@ minor release; renaming or moving one waits for a major. ## Where the version lives -In `CHANGELOG.md`. The top `## [x.y.z]` heading is the released version: +In `plugin.json`, the Agent Plugins manifest. Clients read the version from there, so it +has to be right, which makes it the anchor. -```bash -grep -m1 -oP '^## \[\K[0-9]+\.[0-9]+\.[0-9]+' CHANGELOG.md -``` - -There is no build here, so a separate version file would exist only to be bumped and would -eventually drift from the changelog. The changelog has to be edited at release time anyway, -which makes it the one place that cannot fall behind. +`CHANGELOG.md` carries the same version in its top `## [x.y.z]` heading, because a release +note without a version is useless. Two files holding one number would normally drift, so +`validate-skills.sh` fails the build when they disagree. Bump both, or neither. ## Cutting a release 1. `./scripts/test-all.sh` passes and CI is green on `main`. 2. Move the entries under `[Unreleased]` into a new `## [x.y.z] - YYYY-MM-DD` section and update the link definitions at the bottom of the file. -3. Commit, tag `vx.y.z`, push the tag. -4. Create the GitHub release from the tag, using that changelog section as the body. +3. Set the same version in `plugin.json` and run `./scripts/validate-skills.sh`. +4. Commit, tag `vx.y.z`, push the tag. +5. Create the GitHub release from the tag, using that changelog section as the body. -Steps 3 and 4 are deliberately manual. Automating them can wait until doing it by hand +Steps 4 and 5 are deliberately manual. Automating them can wait until doing it by hand starts to feel like a chore. diff --git a/docs/SCRIPTS.md b/docs/SCRIPTS.md index 7cbee53..d67455e 100644 --- a/docs/SCRIPTS.md +++ b/docs/SCRIPTS.md @@ -54,6 +54,10 @@ cd /path/to/claude-code-java Errors fail the run, recommendations are reported as warnings. +Beyond the spec, it checks two things specific to this repository: that the `.claude/skills` +compatibility symlink still resolves to `skills/`, which a checkout without symlink support +silently breaks, and that `plugin.json` and `CHANGELOG.md` carry the same version. + #### Why two validators CI runs this script alongside [`skills-ref`](https://pypi.org/project/skills-ref/), the diff --git a/plugin.json b/plugin.json new file mode 100644 index 0000000..8765107 --- /dev/null +++ b/plugin.json @@ -0,0 +1,14 @@ +{ + "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", + "name": "java-agent-skills", + "version": "1.0.0", + "description": "Agent Skills for Java development: code review, testing, architecture, Spring Boot, JPA, concurrency, security and release workflows.", + "author": { + "name": "Decebal Suiu", + "url": "https://github.com/decebals" + }, + "homepage": "https://github.com/decebals/claude-code-java", + "repository": "https://github.com/decebals/claude-code-java", + "license": "MIT", + "keywords": ["agent-skills", "java", "maven", "spring-boot", "jpa", "code-review", "testing"] +} diff --git a/scripts/validate-skills.sh b/scripts/validate-skills.sh index 433e765..59169f8 100755 --- a/scripts/validate-skills.sh +++ b/scripts/validate-skills.sh @@ -16,7 +16,7 @@ set -uo pipefail SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" WORKSPACE_DIR="$(dirname "$SCRIPT_DIR")" -SKILLS_DIR="$(cd "${1:-$WORKSPACE_DIR/.claude/skills}" && pwd)" +SKILLS_DIR="$(cd "${1:-$WORKSPACE_DIR/skills}" && pwd)" # Frontmatter fields the spec allows. Anything else is rejected. ALLOWED_FIELDS="name description license compatibility metadata allowed-tools" @@ -30,6 +30,18 @@ warn() { echo "⚠️ $1"; WARNINGS=$((WARNINGS + 1)); } [ ! -d "$SKILLS_DIR" ] && echo "❌ Skills directory not found: $SKILLS_DIR" && exit 1 +# The canonical location is skills/. .claude/skills is a symlink kept for anyone who +# linked or copied the old path. A checkout without symlink support turns it into a text +# file, and the failure is silent, so check that it still resolves to the same place. +COMPAT_LINK="$WORKSPACE_DIR/.claude/skills" +if [ -e "$COMPAT_LINK" ] || [ -L "$COMPAT_LINK" ]; then + if [ ! -d "$COMPAT_LINK" ]; then + fail "compatibility path .claude/skills does not resolve to a directory" + elif [ "$(cd "$COMPAT_LINK" && pwd -P)" != "$(cd "$WORKSPACE_DIR/skills" && pwd -P)" ]; then + fail "compatibility path .claude/skills resolves somewhere other than skills/" + fi +fi + # Prints the frontmatter block of $1, without the --- delimiters. # Requires the closing --- on a line of its own. frontmatter() { @@ -125,6 +137,18 @@ for dir in "$SKILLS_DIR"/*/; do [ "$lines" -le 500 ] || warn "$name: SKILL.md is $lines lines, the spec recommends under 500" done +# One version, two files that must agree. plugin.json is the anchor; the changelog's +# top released heading has to match it, so a release cannot half-happen. +MANIFEST="$WORKSPACE_DIR/plugin.json" +CHANGELOG="$WORKSPACE_DIR/CHANGELOG.md" +if [ -f "$MANIFEST" ] && [ -f "$CHANGELOG" ]; then + manifest_version="$(grep -oE '"version"[ ]*:[ ]*"[^"]+"' "$MANIFEST" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+')" + changelog_version="$(grep -m1 -oE '^## \[[0-9]+\.[0-9]+\.[0-9]+\]' "$CHANGELOG" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+')" + if [ "$manifest_version" != "$changelog_version" ]; then + fail "plugin.json says $manifest_version, CHANGELOG.md says $changelog_version" + fi +fi + echo "" echo "Checked $CHECKED skills in $SKILLS_DIR" echo "$ERRORS error(s), $WARNINGS warning(s)" From 0144df00ccfbe5f945a3fa25372337d566d402f0 Mon Sep 17 00:00:00 2001 From: Decebal Suiu Date: Fri, 28 Aug 2026 23:33:38 +0300 Subject: [PATCH 4/4] docs: record the move and the plugin manifest in the changelog --- CHANGELOG.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 38ce575..2e810b6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Added + +- [#8]: `plugin.json`, declaring this repository as an [Agent Plugin](https://agent-plugins.org/). +- [#8]: `validate-skills.sh` checks that the `.claude/skills` compatibility path still + resolves to `skills/`, and that `plugin.json` and `CHANGELOG.md` agree on the version. + +### Changed + +- [#8]: Skills moved from `.claude/skills/` to `skills/`, which is where the Agent Plugins + standard expects them. `.claude/skills` remains as a symlink, so existing links and the + paths in our own documentation keep working. On a checkout without symlink support, + Windows without developer mode being the usual case, use `skills/` directly. + ## [1.0.0] - 2026-08-28 First tagged release. Within a major version, skill names and directory layout stay @@ -15,7 +28,7 @@ put, which is what copying or symlinking a skill folder depends on. ### Added - 18 skills covering workflow, code quality, architecture and frameworks. The - [skills README](.claude/skills/README.md) lists them. + [skills README](skills/README.md) lists them. - Setup scripts: `setup-project.sh`, `link-skills.sh`, `generate-claude-md.sh`, `configure-mcp.sh`, `configure-settings.sh`, `test-all.sh`. - Templates for `CLAUDE.md`, MCP configuration and Claude Code settings. @@ -41,5 +54,6 @@ put, which is what copying or symlinking a skill folder depends on. it produced a test that always reported the wrong result. [#5]: https://github.com/decebals/claude-code-java/issues/5 +[#8]: https://github.com/decebals/claude-code-java/issues/8 [Unreleased]: https://github.com/decebals/claude-code-java/compare/v1.0.0...HEAD [1.0.0]: https://github.com/decebals/claude-code-java/releases/tag/v1.0.0