feat: Agent Skills spec compliance — validation, aliases, scripts, and auto-injection

Close gaps between ADK's Agent Skills implementation and the public
Agent Skills spec (agentskills.io/specification):

- Frontmatter: add field validators for name (kebab-case, max 64),
  description (non-empty, max 1024), compatibility (max 500);
  add allowed-tools alias; add extra='allow'; add populate_by_name
- utils: extract _parse_skill_md helper; use model_validate() for
  alias support; enforce name-dir matching; add validate_skill_dir()
  and read_skill_properties()
- prompt: accept Union[Frontmatter, Skill];
- skill_toolset: add scripts/ resource loading; auto-inject system
  instruction (with inject_instruction opt-out); duplicate name check;
  _list_skills() returns Skill objects
- sample agent: remove manual instruction (auto-injected now)

Co-authored-by: Haiyuan Cao <haiyuan@google.com>
PiperOrigin-RevId: 873177060

Author: haiyuan-eng-google

contributing/samples/skills_agent/agent.py

@@ -19,7 +19,7 @@
 from google.adk import Agent
 from google.adk.skills import load_skill_from_dir
 from google.adk.skills import models
-from google.adk.tools import skill_toolset
+from google.adk.tools.skill_toolset import SkillToolset
 
 greeting_skill = models.Skill(
     frontmatter=models.Frontmatter(
@@ -44,15 +44,12 @@
     pathlib.Path(__file__).parent / "skills" / "weather_skill"
 )
 
-my_skill_toolset = skill_toolset.SkillToolset(
-    skills=[greeting_skill, weather_skill]
-)
+my_skill_toolset = SkillToolset(skills=[greeting_skill, weather_skill])
 
 root_agent = Agent(
     model="gemini-2.5-flash",
     name="skill_user_agent",
     description="An agent that can use specialized skills.",
-    instruction=skill_toolset.DEFAULT_SKILL_SYSTEM_INSTRUCTION,
     tools=[
         my_skill_toolset,
     ],

src/google/adk/skills/__init__.py

@@ -14,11 +14,11 @@
 
 """Agent Development Kit - Skills."""
 
+from ._utils import _load_skill_from_dir as load_skill_from_dir
 from .models import Frontmatter
 from .models import Resources
 from .models import Script
 from .models import Skill
-from .utils import load_skill_from_dir
 
 __all__ = [
     "Frontmatter",

src/google/adk/skills/_utils.py

@@ -0,0 +1,234 @@
+# 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.
+
+"""Utility functions for Agent Skills."""
+
+from __future__ import annotations
+
+import pathlib
+from typing import Union
+
+import yaml
+
+from . import models
+
+_ALLOWED_FRONTMATTER_KEYS = frozenset({
+    "name",
+    "description",
+    "license",
+    "allowed-tools",
+    "allowed_tools",
+    "metadata",
+    "compatibility",
+})
+
+
+def _load_dir(directory: pathlib.Path) -> dict[str, str]:
+  """Recursively load files from a directory into a dictionary.
+
+  Args:
+    directory: Path to the directory to load.
+
+  Returns:
+    Dictionary mapping relative file paths to their string content.
+  """
+  files = {}
+  if directory.exists() and directory.is_dir():
+    for file_path in directory.rglob("*"):
+      if "__pycache__" in file_path.parts:
+        continue
+      if file_path.is_file():
+        relative_path = file_path.relative_to(directory)
+        try:
+          files[str(relative_path)] = file_path.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+          # Binary files or non-UTF-8 files are skipped for text content.
+          continue
+  return files
+
+
+def _parse_skill_md(
+    skill_dir: pathlib.Path,
+) -> tuple[dict, str, pathlib.Path]:
+  """Parse SKILL.md from a skill directory.
+
+  Args:
+    skill_dir: Resolved path to the skill directory.
+
+  Returns:
+    Tuple of (parsed_frontmatter_dict, body_string, skill_md_path).
+
+  Raises:
+    FileNotFoundError: If the directory or SKILL.md is not found.
+    ValueError: If SKILL.md is invalid.
+  """
+  if not skill_dir.is_dir():
+    raise FileNotFoundError(f"Skill directory '{skill_dir}' not found.")
+
+  skill_md = None
+  for name in ("SKILL.md", "skill.md"):
+    path = skill_dir / name
+    if path.exists():
+      skill_md = path
+      break
+
+  if skill_md is None:
+    raise FileNotFoundError(f"SKILL.md not found in '{skill_dir}'.")
+
+  content = skill_md.read_text(encoding="utf-8")
+  if not content.startswith("---"):
+    raise ValueError("SKILL.md must start with YAML frontmatter (---)")
+
+  parts = content.split("---", 2)
+  if len(parts) < 3:
+    raise ValueError("SKILL.md frontmatter not properly closed with ---")
+
+  frontmatter_str = parts[1]
+  body = parts[2].strip()
+
+  try:
+    parsed = yaml.safe_load(frontmatter_str)
+  except yaml.YAMLError as e:
+    raise ValueError(f"Invalid YAML in frontmatter: {e}") from e
+
+  if not isinstance(parsed, dict):
+    raise ValueError("SKILL.md frontmatter must be a YAML mapping")
+
+  return parsed, body, skill_md
+
+
+def _load_skill_from_dir(skill_dir: Union[str, pathlib.Path]) -> models.Skill:
+  """Load a complete skill from a directory.
+
+  Args:
+    skill_dir: Path to the skill directory.
+
+  Returns:
+    Skill object with all components loaded.
+
+  Raises:
+    FileNotFoundError: If the skill directory or SKILL.md is not found.
+    ValueError: If SKILL.md is invalid or the skill name does not match
+      the directory name.
+  """
+  skill_dir = pathlib.Path(skill_dir).resolve()
+
+  parsed, body, skill_md = _parse_skill_md(skill_dir)
+
+  # Use model_validate to handle aliases like allowed-tools
+  frontmatter = models.Frontmatter.model_validate(parsed)
+
+  # Validate that skill name matches the directory name
+  if skill_dir.name != frontmatter.name:
+    raise ValueError(
+        f"Skill name '{frontmatter.name}' does not match directory"
+        f" name '{skill_dir.name}'."
+    )
+
+  references = _load_dir(skill_dir / "references")
+  assets = _load_dir(skill_dir / "assets")
+  raw_scripts = _load_dir(skill_dir / "scripts")
+  scripts = {
+      name: models.Script(src=content) for name, content in raw_scripts.items()
+  }
+
+  resources = models.Resources(
+      references=references,
+      assets=assets,
+      scripts=scripts,
+  )
+
+  return models.Skill(
+      frontmatter=frontmatter,
+      instructions=body,
+      resources=resources,
+  )
+
+
+def _validate_skill_dir(
+    skill_dir: Union[str, pathlib.Path],
+) -> list[str]:
+  """Validate a skill directory without fully loading it.
+
+  Checks that the directory exists, contains a valid SKILL.md with correct
+  frontmatter, and that the skill name matches the directory name.
+
+  Args:
+    skill_dir: Path to the skill directory.
+
+  Returns:
+    List of problem strings. Empty list means the skill is valid.
+  """
+  problems: list[str] = []
+  skill_dir = pathlib.Path(skill_dir).resolve()
+
+  if not skill_dir.exists():
+    return [f"Directory '{skill_dir}' does not exist."]
+  if not skill_dir.is_dir():
+    return [f"'{skill_dir}' is not a directory."]
+
+  skill_md = None
+  for name in ("SKILL.md", "skill.md"):
+    path = skill_dir / name
+    if path.exists():
+      skill_md = path
+      break
+  if skill_md is None:
+    return [f"SKILL.md not found in '{skill_dir}'."]
+
+  try:
+    parsed, _, _ = _parse_skill_md(skill_dir)
+  except (FileNotFoundError, ValueError) as e:
+    return [str(e)]
+
+  unknown = set(parsed.keys()) - _ALLOWED_FRONTMATTER_KEYS
+  if unknown:
+    problems.append(f"Unknown frontmatter fields: {sorted(unknown)}")
+
+  try:
+    frontmatter = models.Frontmatter.model_validate(parsed)
+  except Exception as e:
+    problems.append(f"Frontmatter validation error: {e}")
+    return problems
+
+  if skill_dir.name != frontmatter.name:
+    problems.append(
+        f"Skill name '{frontmatter.name}' does not match directory"
+        f" name '{skill_dir.name}'."
+    )
+
+  return problems
+
+
+def _read_skill_properties(
+    skill_dir: Union[str, pathlib.Path],
+) -> models.Frontmatter:
+  """Read only the frontmatter properties from a skill directory.
+
+  This is a lightweight alternative to ``load_skill_from_dir`` when you
+  only need the skill metadata without loading instructions or resources.
+
+  Args:
+    skill_dir: Path to the skill directory.
+
+  Returns:
+    Frontmatter object with the skill's metadata.
+
+  Raises:
+    FileNotFoundError: If the directory or SKILL.md is not found.
+    ValueError: If the frontmatter is invalid.
+  """
+  skill_dir = pathlib.Path(skill_dir).resolve()
+  parsed, _, _ = _parse_skill_md(skill_dir)
+  return models.Frontmatter.model_validate(parsed)

src/google/adk/skills/models.py

@@ -16,9 +16,16 @@
 
 from __future__ import annotations
 
+import re
 from typing import Optional
+import unicodedata
 
 from pydantic import BaseModel
+from pydantic import ConfigDict
+from pydantic import Field
+from pydantic import field_validator
+
+_NAME_PATTERN = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
 
 
 class Frontmatter(BaseModel):
@@ -31,17 +38,57 @@ class Frontmatter(BaseModel):
       license: License for the skill (optional).
       compatibility: Compatibility information for the skill (optional).
       allowed_tools: Tool patterns the skill requires (optional, experimental).
+        Accepts both ``allowed_tools`` and the YAML-friendly ``allowed-tools``
+        key.
       metadata: Key-value pairs for client-specific properties (defaults to
         empty dict).
   """
 
+  model_config = ConfigDict(
+      extra="allow",
+      populate_by_name=True,
+  )
+
   name: str
   description: str
   license: Optional[str] = None
   compatibility: Optional[str] = None
-  allowed_tools: Optional[str] = None
+  allowed_tools: Optional[str] = Field(
+      default=None,
+      alias="allowed-tools",
+      serialization_alias="allowed-tools",
+  )
   metadata: dict[str, str] = {}
 
+  @field_validator("name")
+  @classmethod
+  def _validate_name(cls, v: str) -> str:
+    v = unicodedata.normalize("NFKC", v)
+    if len(v) > 64:
+      raise ValueError("name must be at most 64 characters")
+    if not _NAME_PATTERN.match(v):
+      raise ValueError(
+          "name must be lowercase kebab-case (a-z, 0-9, hyphens),"
+          " with no leading, trailing, or consecutive hyphens"
+      )
+    return v
+
+  @field_validator("description")
+  @classmethod
+  def _validate_description(cls, v: str) -> str:
+    if not v:
+      raise ValueError("description must not be empty")
+    if len(v) > 1024:
+      raise ValueError("description must be at most 1024 characters")
+    return v
+
+  @field_validator("compatibility")
+  @classmethod
+  def _validate_compatibility(cls, v: Optional[str]) -> Optional[str]:
+    if v is not None and len(v) > 500:
+      raise ValueError("compatibility must be at most 500 characters")
+    return v
+
 
 class Script(BaseModel):
   """Wrapper for script content."""

src/google/adk/skills/prompt.py

@@ -18,15 +18,18 @@
 
 import html
 from typing import List
+from typing import Union
 
 from . import models
 
 
-def format_skills_as_xml(skills: List[models.Frontmatter]) -> str:
+def format_skills_as_xml(
+    skills: List[Union[models.Frontmatter, models.Skill]],
+) -> str:
   """Formats available skills into a standard XML string.
 
   Args:
-    skills: A list of skill frontmatter objects.
+    skills: A list of skill frontmatter or full skill objects.
 
   Returns:
       XML string with <available_skills> block containing each skill's
@@ -38,13 +41,13 @@ def format_skills_as_xml(skills: List[models.Frontmatter]) -> str:
 
   lines = ["<available_skills>"]
 
-  for skill in skills:
+  for item in skills:
     lines.append("<skill>")
     lines.append("<name>")
-    lines.append(html.escape(skill.name))
+    lines.append(html.escape(item.name))
     lines.append("</name>")
     lines.append("<description>")
-    lines.append(html.escape(skill.description))
+    lines.append(html.escape(item.description))
     lines.append("</description>")
     lines.append("</skill>")