feat: Add SkillSource interface and implementations for loading skills

core/src/main/java/com/google/adk/skills/AbstractSkillSource.java

@@ -0,0 +1,160 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.adk.skills;
+
+import static com.google.common.base.Preconditions.checkArgument;
+import static java.nio.channels.Channels.newReader;
+import static java.nio.charset.StandardCharsets.UTF_8;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.dataformat.yaml.YAMLFactory;
+import com.google.common.collect.ImmutableMap;
+import com.google.common.io.ByteSource;
+import java.io.BufferedReader;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.UncheckedIOException;
+import java.nio.channels.Channels;
+import java.nio.channels.ReadableByteChannel;
+import java.util.function.BiConsumer;
+
+/**
+ * Abstract base class for SkillSource implementations that load skills from path like object.
+ *
+ * @param <PathT> the type of path object
+ */
+public abstract class AbstractSkillSource<PathT> implements SkillSource {
+
+  private static final String THREE_DASHES = "---";
+  private static final ObjectMapper yamlMapper = new ObjectMapper(new YAMLFactory());
+
+  @Override
+  public ImmutableMap<String, Frontmatter> listFrontmatters() {
+    ImmutableMap.Builder<String, Frontmatter> builder = ImmutableMap.builder();
+    iterateSkills((name, path) -> builder.put(name, loadFrontmatter(name, path)));
+    return builder.buildOrThrow();
+  }
+
+  @Override
+  public Frontmatter loadFrontmatter(String skillName) {
+    PathT skillMdPath = findSkillMdPath(skillName);
+    return loadFrontmatter(skillName, skillMdPath);
+  }
+
+  private Frontmatter loadFrontmatter(String skillName, PathT skillMdPath) {
+    try (BufferedReader reader = openReader(skillMdPath)) {
+      String yaml = readFrontmatterYaml(reader);
+      Frontmatter frontmatter = parseFrontmatter(yaml);
+      checkArgument(
+          frontmatter.name().equals(skillName),
+          "Skill name '%s' does not match directory name '%s'.",
+          frontmatter.name(),
+          skillName);
+      return frontmatter;
+    } catch (IOException e) {
+      throw new UncheckedIOException(e);
+    }
+  }
+
+  @Override
+  public String loadInstructions(String skillName) {
+    PathT skillMdPath = findSkillMdPath(skillName);
+
+    try (BufferedReader reader = openReader(skillMdPath)) {
+      return readInstructions(reader);
+    } catch (IOException e) {
+      throw new UncheckedIOException(e);
+    }
+  }
+
+  @Override
+  public ByteSource loadResource(String skillName, String resourcePath) {
+    PathT path = findResourcePath(skillName, resourcePath);
+    return new ByteSource() {
+      @Override
+      public InputStream openStream() throws IOException {
+        return Channels.newInputStream(AbstractSkillSource.this.openChannel(path));
+      }
+    };
+  }
+
+  /** Iterates through SKILL.md files for all the supported skills. */
+  protected abstract void iterateSkills(BiConsumer<String, PathT> skillMdConsumer);
+
+  /** Returns the path to the SKILL.md file for the given skill. */
+  protected abstract PathT findSkillMdPath(String skillName);
+
+  /** Returns the path to the resource for the given skill. */
+  protected abstract PathT findResourcePath(String skillName, String resourcePath);
+
+  /** Opens a {@link InputStream} for reading the content of the given path. */
+  protected abstract ReadableByteChannel openChannel(PathT path) throws IOException;
+
+  private BufferedReader openReader(PathT path) throws IOException {
+    return new BufferedReader(newReader(openChannel(path), UTF_8));
+  }
+
+  private String readFrontmatterYaml(BufferedReader reader) throws IOException {
+    String line = reader.readLine();
+    checkArgument(
+        line != null && line.trim().equals(THREE_DASHES),
+        "Skill file must start with %s",
+        THREE_DASHES);
+
+    StringBuilder sb = new StringBuilder();
+    while ((line = reader.readLine()) != null) {
+      if (line.trim().equals(THREE_DASHES)) {
+        return sb.toString();
+      }
+      sb.append(line).append("\n");
+    }
+    throw new IllegalArgumentException(
+        "Skill file frontmatter not properly closed with " + THREE_DASHES);
+  }
+
+  private String readInstructions(BufferedReader reader) throws IOException {
+    // Skip the frontmatter block
+    String line = reader.readLine();
+    checkArgument(
+        line != null && line.trim().equals(THREE_DASHES),
+        "Skill file must start with %s",
+        THREE_DASHES);
+    boolean dashClosed = false;
+    while ((line = reader.readLine()) != null) {
+      if (line.trim().equals(THREE_DASHES)) {
+        dashClosed = true;
+        break;
+      }
+    }
+    checkArgument(dashClosed, "Skill file frontmatter not properly closed with %s", THREE_DASHES);
+
+    // Read the instructions till the end of the file
+    StringBuilder sb = new StringBuilder();
+    while ((line = reader.readLine()) != null) {
+      sb.append(line).append("\n");
+    }
+    return sb.toString().trim();
+  }
+
+  private Frontmatter parseFrontmatter(String yaml) {
+    try {
+      return yamlMapper.readValue(yaml, Frontmatter.class);
+    } catch (IOException e) {
+      throw new UncheckedIOException(e);
+    }
+  }
+}

core/src/main/java/com/google/adk/skills/Frontmatter.java

@@ -0,0 +1,146 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.adk.skills;
+
+import com.fasterxml.jackson.annotation.JsonAlias;
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
+import com.google.adk.JsonBaseModel;
+import com.google.auto.value.AutoValue;
+import com.google.common.collect.ImmutableMap;
+import com.google.common.escape.Escaper;
+import com.google.common.html.HtmlEscapers;
+import com.google.errorprone.annotations.CanIgnoreReturnValue;
+import java.util.Map;
+import java.util.Optional;
+import java.util.regex.Pattern;
+
+/**
+ * Frontmatter represents the YAML metadata at the top of a SKILL.md file. For more details, see
+ * https://agentskills.io/specification#frontmatter.
+ */
+@AutoValue
+@JsonDeserialize(builder = Frontmatter.Builder.class)
+@JsonIgnoreProperties(ignoreUnknown = true)
+public abstract class Frontmatter extends JsonBaseModel {
+
+  private static final Pattern NAME_PATTERN = Pattern.compile("^[a-z0-9]+(-[a-z0-9]+)*$");
+
+  /** Skill name in kebab-case. */
+  @JsonProperty("name")
+  public abstract String name();
+
+  /** What the skill does and when the model should use it. */
+  @JsonProperty("description")
+  public abstract String description();
+
+  /** License for the skill. */
+  @JsonProperty("license")
+  public abstract Optional<String> license();
+
+  /** Compatibility information for the skill. */
+  @JsonProperty("compatibility")
+  public abstract Optional<String> compatibility();
+
+  /** A space-delimited list of tools that are pre-approved to run. */
+  @JsonProperty("allowed-tools")
+  public abstract Optional<String> allowedTools();
+
+  /** Key-value pairs for client-specific properties. */
+  @JsonProperty("metadata")
+  public abstract ImmutableMap<String, Object> metadata();
+
+  public String toXml() {
+    Escaper escaper = HtmlEscapers.htmlEscaper();
+    return String.format(
+        """
+        <skill>
+        <name>
+        %s
+        </name>
+        <description>
+        %s
+        </description>
+        </skill>
+        """,
+        escaper.escape(name()), escaper.escape(description()));
+  }
+
+  public static Builder builder() {
+    return new AutoValue_Frontmatter.Builder().metadata(ImmutableMap.of());
+  }
+
+  @AutoValue.Builder
+  public abstract static class Builder {
+
+    @JsonCreator
+    private static Builder create() {
+      return builder();
+    }
+
+    @CanIgnoreReturnValue
+    @JsonProperty("name")
+    public abstract Builder name(String name);
+
+    @CanIgnoreReturnValue
+    @JsonProperty("description")
+    public abstract Builder description(String description);
+
+    @CanIgnoreReturnValue
+    @JsonProperty("license")
+    public abstract Builder license(String license);
+
+    @CanIgnoreReturnValue
+    @JsonProperty("compatibility")
+    public abstract Builder compatibility(String compatibility);
+
+    @CanIgnoreReturnValue
+    @JsonProperty("allowed-tools")
+    @JsonAlias({"allowed_tools"})
+    public abstract Builder allowedTools(String allowedTools);
+
+    @CanIgnoreReturnValue
+    @JsonProperty("metadata")
+    public abstract Builder metadata(Map<String, Object> metadata);
+
+    abstract Frontmatter autoBuild();
+
+    public Frontmatter build() {
+      Frontmatter fm = autoBuild();
+      if (fm.name().length() > 64) {
+        throw new IllegalArgumentException("name must be at most 64 characters");
+      }
+      if (!NAME_PATTERN.matcher(fm.name()).matches()) {
+        throw new IllegalArgumentException(
+            "name must be lowercase kebab-case (a-z, 0-9, hyphens), with no leading, trailing, or"
+                + " consecutive hyphens");
+      }
+      if (fm.description().isEmpty()) {
+        throw new IllegalArgumentException("description must not be empty");
+      }
+      if (fm.description().length() > 1024) {
+        throw new IllegalArgumentException("description must be at most 1024 characters");
+      }
+      if (fm.compatibility().isPresent() && fm.compatibility().get().length() > 500) {
+        throw new IllegalArgumentException("compatibility must be at most 500 characters");
+      }
+      return fm;
+    }
+  }
+}