feat: add skills configuration and event handling features

Author: brunoborges

src/main/java/com/github/copilot/sdk/CopilotClient.java

@@ -428,6 +428,9 @@ public CompletableFuture<CopilotSession> createSession(SessionConfig config) {
                 request.setMcpServers(config.getMcpServers());
                 request.setCustomAgents(config.getCustomAgents());
                 request.setInfiniteSessions(config.getInfiniteSessions());
+                request.setSkillDirectories(config.getSkillDirectories());
+                request.setDisabledSkills(config.getDisabledSkills());
+                request.setConfigDir(config.getConfigDir());
             }
 
             return connection.rpc.invoke("session.create", request, CreateSessionResponse.class).thenApply(response -> {

src/main/java/com/github/copilot/sdk/CopilotSession.java

@@ -305,6 +305,52 @@ public Closeable on(Consumer<AbstractSessionEvent> handler) {
         return () -> eventHandlers.remove(handler);
     }
 
+    /**
+     * Registers an event handler for a specific event type.
+     * <p>
+     * This provides a type-safe way to handle specific events without needing
+     * {@code instanceof} checks. The handler will only be called for events
+     * matching the specified type.
+     *
+     * <h2>Example Usage</h2>
+     *
+     * <pre>{@code
+     * // Handle assistant messages
+     * session.on(AssistantMessageEvent.class, msg -> {
+     * 	System.out.println(msg.getData().getContent());
+     * });
+     *
+     * // Handle session idle
+     * session.on(SessionIdleEvent.class, idle -> {
+     * 	done.complete(null);
+     * });
+     *
+     * // Handle streaming deltas
+     * session.on(AssistantMessageDeltaEvent.class, delta -> {
+     * 	System.out.print(delta.getData().getDeltaContent());
+     * });
+     * }</pre>
+     *
+     * @param <T>
+     *            the event type
+     * @param eventType
+     *            the class of the event to listen for
+     * @param handler
+     *            a callback invoked when events of this type occur
+     * @return a Closeable that unsubscribes the handler when closed
+     * @see #on(Consumer)
+     * @see AbstractSessionEvent
+     */
+    public <T extends AbstractSessionEvent> Closeable on(Class<T> eventType, Consumer<T> handler) {
+        Consumer<AbstractSessionEvent> wrapper = event -> {
+            if (eventType.isInstance(event)) {
+                handler.accept(eventType.cast(event));
+            }
+        };
+        eventHandlers.add(wrapper);
+        return () -> eventHandlers.remove(wrapper);
+    }
+
     /**
      * Dispatches an event to all registered handlers.
      * <p>

src/main/java/com/github/copilot/sdk/json/CreateSessionRequest.java

@@ -60,6 +60,15 @@ public final class CreateSessionRequest {
     @JsonProperty("infiniteSessions")
     private InfiniteSessionConfig infiniteSessions;
 
+    @JsonProperty("skillDirectories")
+    private List<String> skillDirectories;
+
+    @JsonProperty("disabledSkills")
+    private List<String> disabledSkills;
+
+    @JsonProperty("configDir")
+    private String configDir;
+
     /** Gets the model name. @return the model */
     public String getModel() {
         return model;
@@ -179,4 +188,34 @@ public InfiniteSessionConfig getInfiniteSessions() {
     public void setInfiniteSessions(InfiniteSessionConfig infiniteSessions) {
         this.infiniteSessions = infiniteSessions;
     }
+
+    /** Gets skill directories. @return the skill directories */
+    public List<String> getSkillDirectories() {
+        return skillDirectories;
+    }
+
+    /** Sets skill directories. @param skillDirectories the directories */
+    public void setSkillDirectories(List<String> skillDirectories) {
+        this.skillDirectories = skillDirectories;
+    }
+
+    /** Gets disabled skills. @return the disabled skill names */
+    public List<String> getDisabledSkills() {
+        return disabledSkills;
+    }
+
+    /** Sets disabled skills. @param disabledSkills the skill names to disable */
+    public void setDisabledSkills(List<String> disabledSkills) {
+        this.disabledSkills = disabledSkills;
+    }
+
+    /** Gets config directory. @return the config directory path */
+    public String getConfigDir() {
+        return configDir;
+    }
+
+    /** Sets config directory. @param configDir the config directory path */
+    public void setConfigDir(String configDir) {
+        this.configDir = configDir;
+    }
 }

src/main/java/com/github/copilot/sdk/json/SessionConfig.java

@@ -43,6 +43,9 @@ public class SessionConfig {
     private Map<String, Object> mcpServers;
     private List<CustomAgentConfig> customAgents;
     private InfiniteSessionConfig infiniteSessions;
+    private List<String> skillDirectories;
+    private List<String> disabledSkills;
+    private String configDir;
 
     /**
      * Gets the custom session ID.
@@ -338,4 +341,77 @@ public SessionConfig setInfiniteSessions(InfiniteSessionConfig infiniteSessions)
         this.infiniteSessions = infiniteSessions;
         return this;
     }
+
+    /**
+     * Gets the skill directories.
+     *
+     * @return the list of skill directory paths
+     */
+    public List<String> getSkillDirectories() {
+        return skillDirectories;
+    }
+
+    /**
+     * Sets the skill directories for loading custom skills.
+     * <p>
+     * Skills are loaded from SKILL.md files in subdirectories of the specified
+     * directories. Each skill subdirectory should contain a SKILL.md file with YAML
+     * frontmatter defining the skill metadata.
+     *
+     * @param skillDirectories
+     *            the list of skill directory paths
+     * @return this config instance for method chaining
+     */
+    public SessionConfig setSkillDirectories(List<String> skillDirectories) {
+        this.skillDirectories = skillDirectories;
+        return this;
+    }
+
+    /**
+     * Gets the disabled skill names.
+     *
+     * @return the list of disabled skill names
+     */
+    public List<String> getDisabledSkills() {
+        return disabledSkills;
+    }
+
+    /**
+     * Sets the list of skill names to disable.
+     * <p>
+     * Skills in this list will not be applied to the session, even if they are
+     * found in the skill directories.
+     *
+     * @param disabledSkills
+     *            the list of skill names to disable
+     * @return this config instance for method chaining
+     */
+    public SessionConfig setDisabledSkills(List<String> disabledSkills) {
+        this.disabledSkills = disabledSkills;
+        return this;
+    }
+
+    /**
+     * Gets the custom configuration directory.
+     *
+     * @return the config directory path
+     */
+    public String getConfigDir() {
+        return configDir;
+    }
+
+    /**
+     * Sets a custom configuration directory for the session.
+     * <p>
+     * This allows using a specific directory for session configuration instead of
+     * the default location.
+     *
+     * @param configDir
+     *            the configuration directory path
+     * @return this config instance for method chaining
+     */
+    public SessionConfig setConfigDir(String configDir) {
+        this.configDir = configDir;
+        return this;
+    }
 }

src/site/markdown/advanced.md

@@ -130,6 +130,22 @@ var session = client.createSession(
 String workspace = session.getWorkspacePath();
 ```
 
+### Compaction Events
+
+When compaction occurs, the session emits events that you can listen for:
+
+```java
+session.on(event -> {
+    if (event instanceof SessionCompactionStartEvent start) {
+        System.out.println("Compaction started");
+    } else if (event instanceof SessionCompactionCompleteEvent complete) {
+        var data = complete.getData();
+        System.out.println("Compaction completed - success: " + data.isSuccess() 
+            + ", tokens removed: " + data.getTokensRemoved());
+    }
+});
+```
+
 For short conversations, disable to avoid overhead:
 
 ```java
@@ -160,6 +176,63 @@ var session = client.createSession(
 
 ---
 
+## Skills Configuration
+
+Load custom skills from directories to extend the AI's capabilities with domain-specific knowledge.
+
+### Loading Skills
+
+Skills are loaded from `SKILL.md` files in subdirectories of the specified skill directories:
+
+```java
+var session = client.createSession(
+    new SessionConfig()
+        .setSkillDirectories(List.of("/path/to/skills"))
+).get();
+```
+
+Each skill subdirectory should contain a `SKILL.md` file with YAML frontmatter:
+
+```markdown
+---
+name: my-skill
+description: A skill that provides domain-specific knowledge
+---
+
+# Skill Instructions
+
+Your skill instructions go here...
+```
+
+### Disabling Skills
+
+Disable specific skills by name:
+
+```java
+var session = client.createSession(
+    new SessionConfig()
+        .setSkillDirectories(List.of("/path/to/skills"))
+        .setDisabledSkills(List.of("my-skill"))
+).get();
+```
+
+---
+
+## Custom Configuration Directory
+
+Use a custom configuration directory for session settings:
+
+```java
+var session = client.createSession(
+    new SessionConfig()
+        .setConfigDir("/path/to/custom/config")
+).get();
+```
+
+This is useful when you need to isolate session configuration or use different settings for different environments.
+
+---
+
 ## Permission Handling
 
 Approve or deny permission requests from the AI.

src/site/markdown/documentation.md

@@ -58,20 +58,39 @@ For more control, subscribe to events and use `send()`:
 ```java
 var done = new CompletableFuture<Void>();
 
-session.on(event -> {
-    if (event instanceof AssistantMessageEvent msg) {
-        System.out.println("Response: " + msg.getData().getContent());
-    } else if (event instanceof SessionErrorEvent err) {
-        System.err.println("Error: " + err.getData().getMessage());
-    } else if (event instanceof SessionIdleEvent) {
-        done.complete(null);
-    }
+// Type-safe event handlers (recommended)
+session.on(AssistantMessageEvent.class, msg -> {
+    System.out.println("Response: " + msg.getData().getContent());
+});
+
+session.on(SessionErrorEvent.class, err -> {
+    System.err.println("Error: " + err.getData().getMessage());
+});
+
+session.on(SessionIdleEvent.class, idle -> {
+    done.complete(null);
 });
 
 session.send("Tell me a joke").get();
 done.get(); // Wait for completion
 ```
 
+You can also use a single handler for all events:
+
+```java
+session.on(event -> {
+    switch (event) {
+        case AssistantMessageEvent msg -> 
+            System.out.println("Response: " + msg.getData().getContent());
+        case SessionErrorEvent err -> 
+            System.err.println("Error: " + err.getData().getMessage());
+        case SessionIdleEvent idle -> 
+            done.complete(null);
+        default -> { }
+    }
+});
+```
+
 ### Key Event Types
 
 | Event | Description |
@@ -82,6 +101,9 @@ done.get(); // Wait for completion
 | `SessionErrorEvent` | An error occurred |
 | `ToolExecutionStartEvent` | Tool invocation started |
 | `ToolExecutionCompleteEvent` | Tool invocation completed |
+| `SessionCompactionStartEvent` | Context compaction started (infinite sessions) |
+| `SessionCompactionCompleteEvent` | Context compaction completed |
+| `SessionUsageInfoEvent` | Token usage information |
 
 See the [events package Javadoc](apidocs/com/github/copilot/sdk/events/package-summary.html) for all event types.
 
@@ -185,6 +207,6 @@ client.deleteSession(sessionId).get();
 
 ## Next Steps
 
-- 📖 **[Advanced Usage](advanced.html)** - Tools, BYOK, MCP Servers, System Messages, Infinite Sessions
+- 📖 **[Advanced Usage](advanced.html)** - Tools, BYOK, MCP Servers, System Messages, Infinite Sessions, Skills
 - 📖 **[MCP Servers](mcp.html)** - Integrate external tools via Model Context Protocol
 - 📖 **[API Javadoc](apidocs/index.html)** - Complete API reference

src/site/markdown/index.md

@@ -69,7 +69,7 @@ public class Example {
 | Document | Description |
 |----------|-------------|
 | [Documentation](documentation.html) | Basic usage, streaming, handling responses, and session management |
-| [Advanced Usage](advanced.html) | Tools, BYOK, MCP servers, infinite sessions, and more |
+| [Advanced Usage](advanced.html) | Tools, BYOK, MCP servers, infinite sessions, skills, and more |
 | [MCP Servers](mcp.html) | Integrating Model Context Protocol servers |
 | [Javadoc](apidocs/index.html) | Generated API documentation |