From afda949d77188a1241da4fb3dc9981fea070303e Mon Sep 17 00:00:00 2001 From: Decebal Suiu Date: Fri, 28 Aug 2026 22:34:01 +0300 Subject: [PATCH 1/6] feat: validate skills against the Agent Skills spec Add scripts/validate-skills.sh, checking the hard requirements from https://agentskills.io/specification: the closed set of frontmatter fields, name rules including the directory match, and description and compatibility length limits. It also checks the allowed-tools format, which the spec defines as a space-separated string, and this repo's convention that every skill ships a README.md. Body length and short descriptions are reported as warnings so existing skills do not fail the run. Wire it into test-all.sh as Test 5. --- scripts/test-all.sh | 5 ++ scripts/validate-skills.sh | 133 +++++++++++++++++++++++++++++++++++++ 2 files changed, 138 insertions(+) create mode 100755 scripts/validate-skills.sh diff --git a/scripts/test-all.sh b/scripts/test-all.sh index 4df9557..80ebc07 100755 --- a/scripts/test-all.sh +++ b/scripts/test-all.sh @@ -57,6 +57,11 @@ check "settings.json created" [ -f "$TEST_DIR/.claude/settings.json" ] check "settings.json has content" [ -s "$TEST_DIR/.claude/settings.json" ] echo "" +# Test 5: validate-skills.sh +echo "Testing validate-skills.sh..." +check "all skills pass validation" "$SCRIPT_DIR/validate-skills.sh" +echo "" + # Summary echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" echo "Results: $PASS passed, $FAIL failed" diff --git a/scripts/validate-skills.sh b/scripts/validate-skills.sh new file mode 100755 index 0000000..433e765 --- /dev/null +++ b/scripts/validate-skills.sh @@ -0,0 +1,133 @@ +#!/bin/bash +# validate-skills.sh - Validate skills against the Agent Skills specification +# Usage: ./validate-skills.sh [skills-directory] +# +# Spec: https://agentskills.io/specification +# Errors fail the run. Recommendations are reported as warnings only. +# +# This runs alongside skills-ref, the reference validator, which CI treats as the +# authority on the spec itself. Do not delete this script as a duplicate. It covers +# what skills-ref does not: allowed-tools formatting (a spec rule the reference +# implementation accepts violations of), this repo's README.md convention, and the +# line and description length recommendations. It also needs no Python. + +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)" + +# Frontmatter fields the spec allows. Anything else is rejected. +ALLOWED_FIELDS="name description license compatibility metadata allowed-tools" + +ERRORS=0 +WARNINGS=0 +CHECKED=0 + +fail() { echo "❌ $1"; ERRORS=$((ERRORS + 1)); } +warn() { echo "⚠️ $1"; WARNINGS=$((WARNINGS + 1)); } + +[ ! -d "$SKILLS_DIR" ] && echo "❌ Skills directory not found: $SKILLS_DIR" && exit 1 + +# Prints the frontmatter block of $1, without the --- delimiters. +# Requires the closing --- on a line of its own. +frontmatter() { + awk 'NR==1 && $0!="---" { exit } NR==1 { next } $0=="---" { exit } { print }' "$1" +} + +# Prints the value of top-level key $2 in the frontmatter of $1, joining any +# indented continuation lines. Not a YAML parser, the spec keeps this shallow. +field() { + frontmatter "$1" | awk -v key="$2" ' + $0 ~ "^"key":" { sub("^"key":[ \t]*", ""); print; found=1; next } + found && /^[ \t]+/ { sub(/^[ \t]+/, " "); printf "%s", $0; next } + found { exit } + ' +} + +# Prints the top-level keys present in the frontmatter of $1. +keys() { + frontmatter "$1" | grep -oE '^[A-Za-z][A-Za-z0-9_-]*:' | tr -d ':' +} + +for dir in "$SKILLS_DIR"/*/; do + [ -d "$dir" ] || continue + name="$(basename "$dir")" + skill="$dir/SKILL.md" + CHECKED=$((CHECKED + 1)) + + if [ ! -f "$skill" ]; then + fail "$name: missing SKILL.md" + continue + fi + + # Repo convention, not part of the spec: every skill documents itself for humans. + [ -f "$dir/README.md" ] || fail "$name: missing README.md (repo convention)" + + if [ -z "$(frontmatter "$skill")" ]; then + fail "$name: frontmatter must start on line 1 with --- and close with --- on its own line" + continue + fi + + for key in $(keys "$skill"); do + case " $ALLOWED_FIELDS " in + *" $key "*) ;; + *) fail "$name: unknown frontmatter field '$key', put extra data under 'metadata'" ;; + esac + done + + fm_name="$(field "$skill" name)" + if [ -z "$fm_name" ]; then + fail "$name: 'name' is required" + else + [ "$fm_name" = "$name" ] || fail "$name: name '$fm_name' must match the directory name" + [ "${#fm_name}" -le 64 ] || fail "$name: name is ${#fm_name} characters, max 64" + echo "$fm_name" | grep -qE '^[a-z0-9]+(-[a-z0-9]+)*$' \ + || fail "$name: name must be lowercase alphanumeric and single hyphens, no leading or trailing hyphen" + fi + + desc="$(field "$skill" description)" + if [ -z "$desc" ]; then + fail "$name: 'description' is required and must be non-empty" + else + [ "${#desc}" -le 1024 ] || fail "$name: description is ${#desc} characters, max 1024" + [ "${#desc}" -ge 50 ] || warn "$name: description is ${#desc} characters, too short to route on reliably" + fi + + compat="$(field "$skill" compatibility)" + [ -z "$compat" ] || [ "${#compat}" -le 500 ] \ + || fail "$name: compatibility is ${#compat} characters, max 500" + + if keys "$skill" | grep -qx "allowed-tools"; then + # A YAML list is indented under the key, so it has to be caught on the raw + # frontmatter. field() would join the items and hide it. + if frontmatter "$skill" | awk ' + /^allowed-tools:/ { seen = 1; next } + seen && /^[ \t]*-/ { print "list"; exit } + seen && /^[A-Za-z]/ { exit } + ' | grep -q list; then + fail "$name: allowed-tools must be a space-separated string, not a list" + else + tools="$(field "$skill" allowed-tools)" + case "$tools" in + "") fail "$name: allowed-tools must be a non-empty space-separated string" ;; + *,*) fail "$name: allowed-tools must be space-separated, not comma-separated" ;; + esac + fi + fi + + # strictyaml, used by the reference parser, rejects JSON-style flow mappings. + frontmatter "$skill" | grep -qE '^metadata:[ \t]*\{' \ + && fail "$name: metadata must be a nested block, not inline JSON" + + lines="$(wc -l < "$skill")" + [ "$lines" -le 500 ] || warn "$name: SKILL.md is $lines lines, the spec recommends under 500" +done + +echo "" +echo "Checked $CHECKED skills in $SKILLS_DIR" +echo "$ERRORS error(s), $WARNINGS warning(s)" + +[ "$ERRORS" -eq 0 ] || exit 1 +echo "✅ All skills conform to the Agent Skills specification" From 8df75f02f15705ca56bbde20c5f3495b47ceecb9 Mon Sep 17 00:00:00 2001 From: Decebal Suiu Date: Fri, 28 Aug 2026 22:34:01 +0300 Subject: [PATCH 2/6] ci: run tests and spec validation on push and pull requests Two jobs. The first runs test-all.sh, which docs/TESTING.md had listed as a planned option. The second installs skills-ref, the reference validator from the spec authors, and runs it over every skill. skills-ref is deliberately unpinned. Tracking its latest release is how this repo learns that the spec has moved, so a failure after an upstream release is information rather than a broken build. It stays out of test-all.sh because it needs Python and the local suite is meant to run with no dependencies. --- .github/workflows/test.yml | 42 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 .github/workflows/test.yml diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml new file mode 100644 index 0000000..2bd2c14 --- /dev/null +++ b/.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 From 7bf60e4149200d67c9c7e6ab54ae8deaad83450a Mon Sep 17 00:00:00 2001 From: Decebal Suiu Date: Fri, 28 Aug 2026 22:34:01 +0300 Subject: [PATCH 3/6] feat: declare MIT license in skill frontmatter Skills get copied out of this repo one folder at a time. Once a folder is copied it carries no provenance, so the license should travel with the file. license is an optional field in the Agent Skills spec. --- .claude/skills/api-contract-review/SKILL.md | 1 + .claude/skills/architecture-review/SKILL.md | 1 + .claude/skills/changelog-generator/SKILL.md | 1 + .claude/skills/clean-code/SKILL.md | 1 + .claude/skills/concurrency-review/SKILL.md | 1 + .claude/skills/design-patterns/SKILL.md | 1 + .claude/skills/git-commit/SKILL.md | 1 + .claude/skills/issue-triage/SKILL.md | 1 + .claude/skills/java-code-review/SKILL.md | 1 + .claude/skills/java-migration/SKILL.md | 1 + .claude/skills/jpa-patterns/SKILL.md | 1 + .claude/skills/logging-patterns/SKILL.md | 1 + .claude/skills/maven-dependency-audit/SKILL.md | 1 + .claude/skills/performance-smell-detection/SKILL.md | 1 + .claude/skills/security-audit/SKILL.md | 1 + .claude/skills/solid-principles/SKILL.md | 1 + .claude/skills/spring-boot-patterns/SKILL.md | 1 + .claude/skills/test-quality/SKILL.md | 1 + 18 files changed, 18 insertions(+) diff --git a/.claude/skills/api-contract-review/SKILL.md b/.claude/skills/api-contract-review/SKILL.md index d7128c8..1ff9ea4 100644 --- a/.claude/skills/api-contract-review/SKILL.md +++ b/.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 diff --git a/.claude/skills/architecture-review/SKILL.md b/.claude/skills/architecture-review/SKILL.md index 6ecef7a..3592280 100644 --- a/.claude/skills/architecture-review/SKILL.md +++ b/.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 diff --git a/.claude/skills/changelog-generator/SKILL.md b/.claude/skills/changelog-generator/SKILL.md index 0d3a94b..dd21620 100644 --- a/.claude/skills/changelog-generator/SKILL.md +++ b/.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 diff --git a/.claude/skills/clean-code/SKILL.md b/.claude/skills/clean-code/SKILL.md index d93f134..286745e 100644 --- a/.claude/skills/clean-code/SKILL.md +++ b/.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 diff --git a/.claude/skills/concurrency-review/SKILL.md b/.claude/skills/concurrency-review/SKILL.md index 198f492..bed060f 100644 --- a/.claude/skills/concurrency-review/SKILL.md +++ b/.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 diff --git a/.claude/skills/design-patterns/SKILL.md b/.claude/skills/design-patterns/SKILL.md index 45be0af..2d384c7 100644 --- a/.claude/skills/design-patterns/SKILL.md +++ b/.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 diff --git a/.claude/skills/git-commit/SKILL.md b/.claude/skills/git-commit/SKILL.md index 8d9828c..5bc0c48 100644 --- a/.claude/skills/git-commit/SKILL.md +++ b/.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 diff --git a/.claude/skills/issue-triage/SKILL.md b/.claude/skills/issue-triage/SKILL.md index 15340f6..1a6c01d 100644 --- a/.claude/skills/issue-triage/SKILL.md +++ b/.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 diff --git a/.claude/skills/java-code-review/SKILL.md b/.claude/skills/java-code-review/SKILL.md index eea9f61..66fe7ee 100644 --- a/.claude/skills/java-code-review/SKILL.md +++ b/.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 diff --git a/.claude/skills/java-migration/SKILL.md b/.claude/skills/java-migration/SKILL.md index 14171a5..cc40a6c 100644 --- a/.claude/skills/java-migration/SKILL.md +++ b/.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 diff --git a/.claude/skills/jpa-patterns/SKILL.md b/.claude/skills/jpa-patterns/SKILL.md index 70f6b34..d6d6def 100644 --- a/.claude/skills/jpa-patterns/SKILL.md +++ b/.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 diff --git a/.claude/skills/logging-patterns/SKILL.md b/.claude/skills/logging-patterns/SKILL.md index dc7a2f4..ac47a99 100644 --- a/.claude/skills/logging-patterns/SKILL.md +++ b/.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 diff --git a/.claude/skills/maven-dependency-audit/SKILL.md b/.claude/skills/maven-dependency-audit/SKILL.md index 0a72f31..d6d69e4 100644 --- a/.claude/skills/maven-dependency-audit/SKILL.md +++ b/.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 diff --git a/.claude/skills/performance-smell-detection/SKILL.md b/.claude/skills/performance-smell-detection/SKILL.md index cb19e87..0f6a7b2 100644 --- a/.claude/skills/performance-smell-detection/SKILL.md +++ b/.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 diff --git a/.claude/skills/security-audit/SKILL.md b/.claude/skills/security-audit/SKILL.md index 85e7a11..91097f3 100644 --- a/.claude/skills/security-audit/SKILL.md +++ b/.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 diff --git a/.claude/skills/solid-principles/SKILL.md b/.claude/skills/solid-principles/SKILL.md index 50aab51..84fb770 100644 --- a/.claude/skills/solid-principles/SKILL.md +++ b/.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 diff --git a/.claude/skills/spring-boot-patterns/SKILL.md b/.claude/skills/spring-boot-patterns/SKILL.md index 8f15fe3..cba0128 100644 --- a/.claude/skills/spring-boot-patterns/SKILL.md +++ b/.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 diff --git a/.claude/skills/test-quality/SKILL.md b/.claude/skills/test-quality/SKILL.md index 007fca6..8c6f73a 100644 --- a/.claude/skills/test-quality/SKILL.md +++ b/.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) From 5878c5d3460217d7c33a244f7695f5186e35a8ae Mon Sep 17 00:00:00 2001 From: Decebal Suiu Date: Fri, 28 Aug 2026 22:34:01 +0300 Subject: [PATCH 4/6] refactor(ci): drop structure checks from the skill review prompt Structure and spec conformance are now checked deterministically by validate-skills.sh and skills-ref. Asking a model to repeat them costs tokens and can disagree with the validators. The prompt keeps overlap and quality, where a model actually adds something. --- .github/workflows/skill-review.yml | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/.github/workflows/skill-review.yml b/.github/workflows/skill-review.yml index 1ac6d9e..c6a61a0 100644 --- a/.github/workflows/skill-review.yml +++ b/.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//` + 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] From 9ef4a5496d1970ddcabde3e4b5ec8925573115c9 Mon Sep 17 00:00:00 2001 From: Decebal Suiu Date: Fri, 28 Aug 2026 22:34:01 +0300 Subject: [PATCH 5/6] docs: document Agent Skills spec compliance Reposition the README around the open format while keeping Claude Code named as where the skills are developed and tested, since compatibility with other hosts has not been verified. Record the frontmatter rules in SKILL_GUIDELINES and in the skills README checklist, add the new script to SCRIPTS, and explain there why CI runs both validators, so neither gets removed later as duplication. In TESTING, move GitHub Actions out of the future options, and fill in configure-settings.sh, which was tested but undocumented. --- .claude/skills/README.md | 6 ++++-- README.md | 12 +++++++----- docs/SCRIPTS.md | 24 ++++++++++++++++++++++++ docs/SKILL_GUIDELINES.md | 8 +++++++- docs/TESTING.md | 40 ++++++++++++---------------------------- 5 files changed, 54 insertions(+), 36 deletions(-) diff --git a/.claude/skills/README.md b/.claude/skills/README.md index 155507b..f91d99e 100644 --- a/.claude/skills/README.md +++ b/.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//` -2. Create `SKILL.md` with instructions for Claude +1. Create folder: `.claude/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 5. Update main README.md +6. Run `./scripts/validate-skills.sh` ## Usage diff --git a/README.md b/README.md index 1ff87fd..1da8b85 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # 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) @@ -8,9 +8,11 @@ ## 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 diff --git a/docs/SCRIPTS.md b/docs/SCRIPTS.md index d46a737..7cbee53 100644 --- a/docs/SCRIPTS.md +++ b/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. diff --git a/docs/SKILL_GUIDELINES.md b/docs/SKILL_GUIDELINES.md index de6e786..127ff1d 100644 --- a/docs/SKILL_GUIDELINES.md +++ b/docs/SKILL_GUIDELINES.md @@ -105,16 +105,22 @@ Every skill has two files: ``` .claude/skills// -├── 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 diff --git a/docs/TESTING.md b/docs/TESTING.md index 1bc155d..99fcd48 100644 --- a/docs/TESTING.md +++ b/docs/TESTING.md @@ -1,10 +1,11 @@ # Testing Strategy -> How to test and validate claude-code-java scripts +> How to test and validate claude-code-java scripts and skills ## Current Approach: Simple Test Script -For MVP phase, we use a simple bash test script that validates all setup scripts work correctly. +A bash test script validates that the setup scripts work and that the skills conform to the +Agent Skills specification. It runs locally and in CI on every push and pull request. ### Running Tests @@ -19,11 +20,14 @@ For MVP phase, we use a simple bash test script that validates all setup scripts | `link-skills.sh` | Creates `.claude/`, symlink points to workspace | | `generate-claude-md.sh` | Creates `CLAUDE.md` with content | | `configure-mcp.sh` | Template file exists | +| `configure-settings.sh` | Creates `settings.json` with content | +| `validate-skills.sh` | Every skill passes the Agent Skills spec checks | ### Test Philosophy - Tests run in a temporary directory (auto-cleaned) -- Zero external dependencies +- Zero external dependencies. The reference validator `skills-ref` needs Python, so it runs as + a separate CI job rather than inside `test-all.sh` - Fast execution (< 2 seconds) - Clear pass/fail output @@ -49,27 +53,7 @@ For MVP phase, we use a simple bash test script that validates all setup scripts **Install:** `npm install -g bats` or `brew install bats-core` -### Option 2: GitHub Actions CI - -**When to adopt:** -- Project is public on GitHub -- Want automatic validation on PRs -- Multiple contributors - -**Example workflow (`.github/workflows/test.yml`):** -```yaml -name: Test -on: [push, pull_request] -jobs: - test: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - run: chmod +x scripts/*.sh - - run: ./scripts/test-all.sh -``` - -### Option 3: Pre-commit Hook +### Option 2: Pre-commit Hook **When to adopt:** - Want to catch issues before commit @@ -86,9 +70,9 @@ jobs: | Phase | Recommended Approach | |-------|---------------------| -| MVP (now) | Simple test script | -| v0.3+ with contributors | Add bats-core | -| Public release | Add GitHub Actions | +| MVP | Simple test script | +| Public release | GitHub Actions (adopted, `.github/workflows/test.yml`) | +| Growth with contributors | Add bats-core | | Team adoption | Add pre-commit hooks | ## Adding New Tests @@ -99,7 +83,7 @@ When adding a new script, add corresponding tests to `test-all.sh`: # Test N: new-script.sh echo "Testing new-script.sh..." "$SCRIPT_DIR/new-script.sh" "$TEST_DIR" > /dev/null 2>&1 -check "[ -f '$TEST_DIR/expected-output' ]" "expected output created" +check "[ -f '$TEST_DIR/expected-output']" "expected output created" echo "" ``` From 11553e9b9e3fc337f15fd34d718598142ba4e6aa Mon Sep 17 00:00:00 2001 From: Decebal Suiu Date: Fri, 28 Aug 2026 22:34:01 +0300 Subject: [PATCH 6/6] docs: fix reversed check arguments in the test example check() takes the description first and the command after it. The example in the Adding New Tests section had them the other way round, so following it produced a test that always reported the wrong result. --- docs/TESTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/TESTING.md b/docs/TESTING.md index 99fcd48..5e3703f 100644 --- a/docs/TESTING.md +++ b/docs/TESTING.md @@ -83,7 +83,7 @@ When adding a new script, add corresponding tests to `test-all.sh`: # Test N: new-script.sh echo "Testing new-script.sh..." "$SCRIPT_DIR/new-script.sh" "$TEST_DIR" > /dev/null 2>&1 -check "[ -f '$TEST_DIR/expected-output']" "expected output created" +check "expected output created" [ -f "$TEST_DIR/expected-output" ] echo "" ```