Adopt the Agent Skills specification

.claude/skills/README.md

@@ -58,16 +58,18 @@ Validate your skill idea against existing skills:
 - [ ] **Clear type** - Audit (review existing code) or Template (show how to write)
 - [ ] **Unique value** - What does it add that doesn't exist?
 - [ ] **Focused scope** - Can be applied in one session (<15 checklist items)
+- [ ] **Spec compliant** - `./scripts/validate-skills.sh` passes
 
 > 📖 **Full guidelines:** [docs/SKILL_GUIDELINES.md](../../docs/SKILL_GUIDELINES.md)
 
 ### Implementation Steps
 
-1. Create folder: `.claude/skills/<skill-name>/`
-2. Create `SKILL.md` with instructions for Claude
+1. Create folder: `.claude/skills/<skill-name>/`. 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
 5. Update main README.md
+6. Run `./scripts/validate-skills.sh`
 
 ## Usage
 

.claude/skills/api-contract-review/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: api-contract-review
 description: Review REST API contracts for HTTP semantics, versioning, backward compatibility, and response consistency. Use when user asks "review API", "check endpoints", "REST review", or before releasing API changes.
+license: MIT
 ---
 
 # API Contract Review Skill

.claude/skills/architecture-review/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: architecture-review
 description: Analyze Java project architecture at macro level - package structure, module boundaries, dependency direction, and layering. Use when user asks "review architecture", "check structure", "package organization", or when evaluating if a codebase follows clean architecture principles.
+license: MIT
 ---
 
 # Architecture Review Skill

.claude/skills/changelog-generator/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: changelog-generator
 description: Generate changelogs from git commits. Use when user says "generate changelog", "update changelog", "what changed since last release", or before preparing a new release.
+license: MIT
 ---
 
 # Changelog Generator Skill

.claude/skills/clean-code/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: clean-code
 description: Clean Code principles (DRY, KISS, YAGNI), naming conventions, function design, and refactoring. Use when user says "clean this code", "refactor", "improve readability", or when reviewing code quality.
+license: MIT
 ---
 
 # Clean Code Skill

.claude/skills/concurrency-review/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: concurrency-review
 description: Review Java concurrency code for thread safety, race conditions, deadlocks, and modern patterns (Virtual Threads, CompletableFuture, @Async). Use when user asks "check thread safety", "concurrency review", "async code review", or when reviewing multi-threaded code.
+license: MIT
 ---
 
 # Concurrency Review Skill

.claude/skills/design-patterns/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: design-patterns
 description: Common design patterns with Java examples (Factory, Builder, Strategy, Observer, Decorator, etc.). Use when user asks "implement pattern", "use factory", "strategy pattern", or when designing extensible components.
+license: MIT
 ---
 
 # Design Patterns Skill

.claude/skills/git-commit/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: git-commit
 description: Generate conventional commit messages for Java projects. Use when user says "commit", "create commit", "commit changes", or after completing code changes that need to be committed.
+license: MIT
 ---
 
 # Git Commit Message Skill

.claude/skills/issue-triage/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: issue-triage
 description: Triage and categorize GitHub issues with priority labels. Use when user says "triage issues", "check issues", "review open issues", or during regular maintenance of GitHub issue backlog.
+license: MIT
 ---
 
 # Issue Triage Skill

.claude/skills/java-code-review/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: java-code-review
 description: Systematic code review for Java with null safety, exception handling, concurrency, and performance checks. Use when user says "review code", "check this PR", "code review", or before merging changes.
+license: MIT
 ---
 
 # Java Code Review Skill

.claude/skills/java-migration/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: java-migration
 description: Guide for upgrading Java projects between major versions (8→11→17→21→25). Use when user says "upgrade Java", "migrate to Java 25", "update Java version", or when modernizing legacy projects.
+license: MIT
 ---
 
 # Java Migration Skill

.claude/skills/jpa-patterns/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: jpa-patterns
 description: JPA/Hibernate patterns and common pitfalls (N+1, lazy loading, transactions, queries). Use when user has JPA performance issues, LazyInitializationException, or asks about entity relationships and fetching strategies.
+license: MIT
 ---
 
 # JPA Patterns Skill

.claude/skills/logging-patterns/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: logging-patterns
 description: Java logging best practices with SLF4J, structured logging (JSON), and MDC for request tracing. Includes AI-friendly log formats for Claude Code debugging. Use when user asks about logging, debugging application flow, or analyzing logs.
+license: MIT
 ---
 
 # Logging Patterns Skill

.claude/skills/maven-dependency-audit/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: maven-dependency-audit
 description: Audit Maven dependencies for outdated versions, security vulnerabilities, and conflicts. Use when user says "check dependencies", "audit dependencies", "outdated deps", or before releases.
+license: MIT
 ---
 
 # Maven Dependency Audit Skill

.claude/skills/performance-smell-detection/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: performance-smell-detection
 description: Detect potential code-level performance smells in Java - streams, collections, boxing, regex, object creation. Provides awareness, not absolutes - always measure before optimizing. For JPA/database performance, use jpa-patterns instead.
+license: MIT
 ---
 
 # Performance Smell Detection Skill

.claude/skills/security-audit/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: security-audit
 description: Java security checklist covering OWASP Top 10, input validation, injection prevention, and secure coding. Works with Spring, Quarkus, Jakarta EE, and plain Java. Use when reviewing code security, before releases, or when user asks about vulnerabilities.
+license: MIT
 ---
 
 # Security Audit Skill

.claude/skills/solid-principles/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: solid-principles
 description: SOLID principles checklist with Java examples. Use when reviewing classes, refactoring code, or when user asks about Single Responsibility, Open/Closed, Liskov, Interface Segregation, or Dependency Inversion.
+license: MIT
 ---
 
 # SOLID Principles Skill

.claude/skills/spring-boot-patterns/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: spring-boot-patterns
 description: Spring Boot best practices and patterns. Use when creating controllers, services, repositories, or when user asks about Spring Boot architecture, REST APIs, exception handling, or JPA patterns.
+license: MIT
 ---
 
 # Spring Boot Patterns Skill

.claude/skills/test-quality/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: test-quality
 description: Write high-quality JUnit 5 tests with AssertJ assertions. Use when user says "add tests", "write tests", "improve test coverage", or when reviewing/creating test classes for Java code.
+license: MIT
 ---
 
 # Test Quality Skill (JUnit 5 + AssertJ)

.github/workflows/skill-review.yml

@@ -38,10 +38,9 @@ jobs:
             STEP 3: Read .claude/skills/README.md to check for overlap with existing skills.
             STEP 4: Validate ONLY the changed files against these criteria:
 
-            ## Structure
-            - SKILL.md has frontmatter with `name` and `description`
-            - README.md exists with human documentation
-            - Follows folder convention: `.claude/skills/<skill-name>/`
+            Structure and spec conformance are already checked by
+            scripts/validate-skills.sh and skills-ref in the Test workflow.
+            Do not repeat those checks. Review content only.
 
             ## No Overlap
             - Does not significantly overlap with existing skills
@@ -62,7 +61,6 @@ jobs:
             **Files reviewed**: [list changed files]
 
             **Findings**:
-            - Structure: [pass/fail with brief note]
             - Overlap: [pass/fail - mention related skills if relevant]
             - Quality: [pass/fail with brief note]
 

.github/workflows/test.yml

@@ -0,0 +1,42 @@
+name: Test
+
+on: [push, pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  scripts:
+    name: Setup scripts and skill conventions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: chmod +x scripts/*.sh
+      - run: ./scripts/test-all.sh
+
+  spec:
+    name: Agent Skills spec
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      # Deliberately unpinned. skills-ref is the reference validator, and tracking its
+      # latest release is how this repo finds out that the spec moved. A failure here
+      # after an upstream release is information, not a broken build.
+      # The package is skills-ref, the command it installs is agentskills.
+      - run: pip install skills-ref
+      - name: Validate every skill
+        run: |
+          fail=0
+          for d in .claude/skills/*/; do
+            if ! out=$(agentskills validate "$d" 2>&1); then
+              fail=1
+              echo "::error file=${d}SKILL.md::$(echo "$out" | tr '\n' ' ')"
+              echo "FAIL $d"
+              echo "$out" | sed 's/^/    /'
+            fi
+          done
+          echo "Validated $(ls -d .claude/skills/*/ | wc -l) skills."
+          exit $fail

README.md

@@ -1,16 +1,18 @@
 # claude-code-java
 
-> Reusable AI development infrastructure for Java projects, optimized for Claude Code
+> Agent Skills for Java projects, following the open Agent Skills specification
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 *This project is not affiliated with Anthropic.*
 
 ## What is this?
 
-A collection of reusable components for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) - Anthropic's agentic coding tool. The core of this project is a set of **skills** (structured markdown files that provide Claude with domain knowledge and workflows), but it also includes project templates, MCP server configurations, and setup scripts.
+A collection of reusable **skills** (structured markdown files that give an AI agent domain knowledge and workflows), plus project templates, MCP server configurations, and setup scripts.
 
-**Who is this for?** Java developers using Claude Code who want consistent, high-quality AI assistance for common tasks like code reviews, testing, commits, and architecture decisions.
+The skills follow the [Agent Skills specification](https://agentskills.io/specification), an open format read by a growing number of agents. They are developed and tested with [Claude Code](https://docs.anthropic.com/en/docs/claude-code), and every skill is validated against the spec in CI.
+
+**Who is this for?** Java developers who want consistent, high-quality AI assistance for common tasks like code reviews, testing, commits, and architecture decisions.
 
 ## Purpose
 
@@ -145,7 +147,7 @@ Track these to validate effectiveness:
 
 ## Requirements
 
-- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI installed
+- An agent that reads Agent Skills. Developed and tested with the [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI
 - Java 11+ projects (Java 17+ recommended)
 - Git for version control
 - Maven or Gradle build tool
@@ -156,7 +158,7 @@ Track these to validate effectiveness:
 - 18 skills (workflow, code quality, architecture, frameworks)
 - Setup automation scripts
 - Project templates
-- YAML frontmatter for automatic skill detection
+- Agent Skills spec compliance, enforced in CI by `scripts/validate-skills.sh` and the reference validator
 
 ## Used in automated code review
 

docs/SCRIPTS.md

@@ -11,6 +11,7 @@
 | `generate-claude-md.sh` | Generates `CLAUDE.md` from template |
 | `configure-mcp.sh` | Generates MCP config and optionally adds servers |
 | `configure-settings.sh` | Copies Claude Code settings with pre-approved commands |
+| `validate-skills.sh` | Validates skills against the Agent Skills specification |
 | `test-all.sh` | Runs all tests to validate scripts work |
 
 ## Usage
@@ -44,6 +45,29 @@ cd /path/to/claude-code-java
 ./scripts/test-all.sh
 ```
 
+### Validate Skills
+
+```bash
+./scripts/validate-skills.sh              # all skills
+./scripts/validate-skills.sh path/to/dir  # a specific skills directory
+```
+
+Errors fail the run, recommendations are reported as warnings.
+
+#### Why two validators
+
+CI runs this script alongside [`skills-ref`](https://pypi.org/project/skills-ref/), the
+reference validator from the spec authors. The two cover different ground, so keep both.
+
+`skills-ref` is the authority on the specification. Tracking its latest release is how this
+repo finds out that the spec has moved, without anyone having to watch for it.
+
+`validate-skills.sh` covers what `skills-ref` does not: the `allowed-tools` format, which the
+spec defines as a space-separated string but the reference implementation accepts as a list or
+comma-separated; this repo's convention that every skill ships a `README.md`; and the length
+recommendations for the body and the description. It also runs with no Python, which matters in
+a repo that is otherwise bash and markdown.
+
 ## Conventions
 
 All scripts follow the same structure for consistency and reliability.

docs/SKILL_GUIDELINES.md

@@ -105,16 +105,22 @@ Every skill has two files:
 
 ```
 .claude/skills/<skill-name>/
-├── SKILL.md    # Instructions for Claude (AI reads this)
+├── SKILL.md    # Instructions for the agent (the AI reads this)
 └── README.md   # Documentation for humans
 ```
 
 ### SKILL.md Structure
 
+Frontmatter follows the [Agent Skills specification](https://agentskills.io/specification).
+`name` and `description` are required; `license`, `compatibility`, `metadata` and
+`allowed-tools` are optional; no other top-level field is allowed. `name` must match the
+directory name. Run `./scripts/validate-skills.sh` to check.
+
 ```markdown
 ---
 name: skill-name
 description: One-line description. Use when [triggers].
+license: MIT
 ---
 
 # Skill Name