Skip to content
March 30, 2026

How to Build a Claude Agent Skill with Java — A Complete Walkthrough

rajeshsgr · 4 min read · GenAI

Python is the most common choice for Skill scripts — it requires no compilation, comes pre-installed in Claude’s execution environment, and does the same job in far fewer lines. Most of Anthropic’s official examples use Python, making it the practical default.

I chose Java here for a specific reason — if your team already works in a Java ecosystem, keeping the Skill in Java means everyone can read and maintain it without switching languages. It also proves an important point: Skills are language-agnostic. Claude does not care whether your script is Python, Java, or bash — it runs the script, reads the output, and reasons over it. The language is your choice, not Claude’s constraint.

Prerequisites

Before we start, you need three things set up on your machine:

  • Claude Code CLI — the command line tool to run Claude locally
  • Anthropic API Key — to authenticate with Anthropic’s servers
  • GitHub CLI — to fetch repository data from GitHub

Step 1 — Install Claude Code CLI

npm install -g @anthropic-ai/claude-code

Step 2 — Set Your Anthropic API Key

Get your key from console.anthropic.com → API Keys → Create Key.

Set it as an environment variable:

export ANTHROPIC_API_KEY=your-api-key-here

To make it permanent:

echo 'export ANTHROPIC_API_KEY=your-api-key-here' >> ~/.zshrc
source ~/.zshrc

Step 3 — Install and Authenticate GitHub CLI

On Mac:

brew install gh
gh auth login

On Windows

winget install GitHub.cli

Follow the prompts — choose GitHub.com, HTTPS, and login via browser.

Step 4— Create the Project Structure

Create a new project folder and set up the Skill directory:

mkdir github-repo-summariser
cd github-repo-summariser
mkdir -p .claude/skills/github-repo-summariser/scripts
```

Your project structure will look like this by the end:
```
github-repo-summariser/          ← your project root
└── .claude/
    └── skills/
        └── github-repo-summariser/
            ├── SKILL.md          ← Skill instructions
            ├── ANALYSIS.md       ← Deep analysis guide
            └── scripts/
                ├── FetchRepo.java
                ├── FetchRepo.class
                ├── DetectStack.java
                └── DetectStack.class

Step 5— Create the SKILL.md

This is the core of the Skill. It has two parts — the frontmatter and the instructions.

The frontmatter is the trigger. Claude reads the name and description at startup and uses them to decide when to activate the Skill:

---
name: github-repo-summariser
description: Reads a GitHub repository and produces a structured summary of what it does, its tech stack, architecture, and how to get started. Use when the user shares a GitHub URL, mentions a repo they want to understand, or asks what a project does.
---
```

**The instructions** tell Claude exactly what to do once triggered — extract the repo identifier, run the Java script, and format the output into a structured summary covering what the project does, the tech stack, architecture overview, key files, getting started steps, and notable details.

It also tells Claude when to load `ANALYSIS.md` — only when the user asks for a detailed or in-depth analysis, not on every request.

Step 6 — Create ANALYSIS.md

This file is not loaded on every request. Claude reads it only when the user explicitly asks for a detailed or in-depth analysis. This is the progressive disclosure pattern in action — keeping context lean for simple requests and loading extra guidance only when the task actually needs it.

The SKILL.md instructs Claude to fetch this file on demand:

You can get this file from the github repo

What ANALYSIS.md contains:

It provides Claude with instructions on how to identify architecture patterns, assess code quality signals, and structure a detailed seven-section analysis report when the user asks for an in-depth review.

Step 7 — Compile the Java Files

The Skill uses two Java classes. The full source code is available in the GitHub repo linked at the end of this article.

  • FetchRepo.java — the main entry point. It takes an `owner/repo` argument, uses the GitHub CLI via `ProcessBuilder` to make a series of API calls, and collects: —
  • Repository metadata — name, description, language, stars, forks
  • Root directory structure — what files and folders exist at the top level
  • README content — first 150 lines decoded from base64
  • Dependency files — whichever of `package.json`, `pom.xml`, `requirements.txt`, `go.mod` and others exist
  • CI/CD signals — presence of Dockerfiles, GitHub Actions, Jenkinsfile
  • Source directory structure — contents of `src/`, `lib/`, `app/`, `cmd/` and similar

Once all data is collected, it calls `DetectStack.detect()` directly — no piping, no separate process.

  • DetectStack.java— scans the collected repo content and identifies the tech stack. It looks for known markers across languages (JavaScript, Python, Java, Go, Rust, Ruby, PHP, Elixir, Dart), frameworks (React, Spring Boot, Django, FastAPI), infrastructure tools (Docker, Kubernetes, Terraform, GitHub Actions), and databases (PostgreSQL, MongoDB, Redis, MySQL).

Step 8 — Compile the Java Files

cd .claude/skills/github-repo-summariser/scripts
javac DetectStack.java FetchRepo.java -d .

Step 9 — Test the Scripts Directly

Before running inside Claude, verify the scripts work on their own:

java -cp .claude/skills/github-repo-summariser/scripts \
  FetchRepo josharsh/jfmt

You should see METADATA, ROOT STRUCTURE, README, DEPENDENCIES, CI/CD, SOURCE STRUCTURE, and STACK DETECTION all printed to the terminal.

Step 10 — Run the Skill in Claude Code

Navigate to your project root and start Claude:

cd ~/github-repo-summariser
claude
```

For a standard summary:
```
Summarise this repo: https://github.com/josharsh/jfmt
```

For a deep analysis:
```
Give me a detailed analysis of: https://github.com/josharsh/jfmt

Source Code

The complete source code for this Skill is available on GitHub:

https://github.com/rajeshsgr/git-repo-skills

Tags: , , , ,

Leave a Reply