Building LLM Agents & Custom Skills

var body = new JSONObject()
  .put("model", "gpt-5-mini")
  .put("messages", new JSONArray(messages))
  .put("tools", registry.declarations())
  .put("tool_choice", "auto");

var req = HttpRequest.newBuilder()
  .uri(URI.create(
    "https://api.openai.com/v1"
    + "/chat/completions"))
  .header("Content-Type",
          "application/json")
  .header("Authorization",
          "Bearer " + API_KEY)
  .POST(BodyPublishers.ofString(
      body.toString()))
  .build();

var resp = client.send(req,
    BodyHandlers.ofString());

var json = new JSONObject(resp.body());
var message = json
    .getJSONArray("choices")
    .getJSONObject(0)
    .getJSONObject("message");

if (message.has("tool_calls")) {
    var calls = message.getJSONArray(
        "tool_calls");
    for (var call : calls) {
        var fn = call.getJSONObject(
            "function");
        String name = fn.getString("name");
        var args = new JSONObject(
            fn.getString("arguments"));
        String id = call.getString("id");
        // → execute tool, send result back
    }
} else {
    String text = message.getString(
        "content");
    // → final answer
}

interface Tool {
    String name();
    String description();
    JSONObject parameters();
    String execute(JSONObject args);
}

class ToolRegistry {
    Map<String, Tool> tools = new HashMap<>();

    void register(Tool t) {
        tools.put(t.name(), t);
    }
    String run(String name, JSONObject args) {
        return tools.get(name).execute(args);
    }
    JSONArray declarations() {
        var arr = new JSONArray();
        for (var t : tools.values()) {
            arr.put(new JSONObject()
              .put("type", "function")
              .put("function", new JSONObject()
                .put("name", t.name())
                .put("description", t.description())
                .put("parameters", t.parameters())));
        }
        return arr;
    }
}

class CalculatorTool implements Tool {
    public String name() {
        return "calculate";
    }
    public String description() {
        return "Evaluate a math expression";
    }
    public JSONObject parameters() {
        return new JSONObject("""
          {"type":"object","properties":{
            "expression":{"type":"string",
              "description":"e.g. 2+3*4"}
          },"required":["expression"]}""");
    }
    public String execute(JSONObject args) {
        String expr = args.getString(
            "expression");
        // Simple eval (or use ScriptEngine)
        return String.valueOf(eval(expr));
    }
}

var messages = new ArrayList<JSONObject>();
messages.add(systemMsg(prompt));
messages.add(userMsg(input));

for (int i = 0; i < MAX_ITER; i++) {
    var resp = llm.call(messages,
        registry.declarations());
    var msg = resp.getJSONArray("choices")
        .getJSONObject(0)
        .getJSONObject("message");

    if (msg.has("tool_calls")) {
        messages.add(msg);
        for (var tc : msg.getJSONArray(
                "tool_calls")) {
            var fn = tc.getJSONObject(
                "function");
            var result = registry.run(
                fn.getString("name"),
                new JSONObject(
                  fn.getString("arguments")));
            messages.add(new JSONObject()
              .put("role", "tool")
              .put("tool_call_id",
                   tc.getString("id"))
              .put("content", result));
        }
    } else {
        return msg.getString("content");
    }
}

class Skill {
    private final String name;
    private final String systemPrompt;
    private final List<Tool> tools;

    Skill(String name, String prompt,
          List<Tool> tools) {
        this.name = name;
        this.systemPrompt = prompt;
        this.tools = tools;
    }

    String execute(String userInput) {
        var registry = new ToolRegistry();
        tools.forEach(registry::register);
        var agent = new Agent(
            systemPrompt, registry);
        return agent.run(userInput);
    }
}

var reviewSkill = new Skill(
    "codeReview",
    """
    You are a code reviewer. Analyze
    the given code for:
    1. Security vulnerabilities
    2. Performance issues
    3. Readability problems
    4. Potential bugs
    Return a structured report with
    severity: critical / major / minor.
    """,
    List.of(
        new ReadFileTool(),
        new CountLinesTool()
    )
);

String report = reviewSkill.execute(
    "Review src/agent/Agent.java");
System.out.println(report);

# ~/.claude/skills/review/SKILL.md
---
name: review
description: Review code for bugs and style
user-invocable: true
allowed-tools: Read Grep
argument-hint: [file-path]
---

Review the following file for:
1. Security vulnerabilities
2. Performance issues
3. Readability problems
4. Potential bugs

File to review: $ARGUMENTS

Return a structured report with
severity levels: critical / major / minor.
Cite specific line numbers.

# ~/.claude/skills/craft/SKILL.md
---
name: craft
description: Generate a CRAFT-structured
  prompt for AI-driven development
user-invocable: true
allowed-tools: Read Grep Glob
argument-hint: [feature-description]
---

The user wants to build: $ARGUMENTS

Generate a CRAFT prompt by:

1. **Context**: Use Read and Grep to scan
   the project. Identify: framework, lang,
   existing files, conventions, types.

2. **Requirement**: Restate what the user
   wants with precise acceptance criteria.
   Add edge cases and error behavior.

3. **Action**: Specify exact file(s) to
   create or modify, with full paths.

4. **Format**: State the tech constraints
   (language, framework, patterns, types).

5. **Test**: Describe how to verify the
   result: expected behavior, edge cases,
   what must NOT happen.

Output the CRAFT prompt in a code block
ready to copy-paste into an AI assistant.