docs: Add documentation for Skills support

docs/agents/index.md

@@ -41,9 +41,44 @@ While each agent type serves a distinct purpose, the true power often comes from
 
 Understanding these core types is the first step toward building sophisticated, capable AI applications with ADK.
 
----
+## Extend Agent Capabilities
 
-## What's Next?
+Beyond the core agent types, ADK allows you to significantly expand what your
+agents can do through several key mechanisms:
+
+*   [**AI Models**](/adk-docs/agents/models/):
+    Swap the underlying intelligence of your agents by integrating with
+    different generative AI models from Google and other providers.
+
+*   [**Artifacts**](/adk-docs/artifacts/):
+    Enable agents to create and manage persistent outputs like files, code, or
+    documents that exist beyond the conversation lifecycle.
+
+*   [**Pre-built tools and integrations**](/adk-docs/integrations/):
+    Equip your agents with a wide array tools, plugins, and other integrations
+    to interact with the world, including web sites, MCP tools, applications,
+    databases, programming interfaces, and more.
+
+*   [**Custom tools**](/adk-docs/tools-custom/):
+    Create your own, task-specific tools for solving specific problems with
+    precision and control.
+
+*   [**Plugins**](/adk-docs/plugins/):
+    Integrate complex, pre-packaged behaviors and third-party services directly
+    into your agent's workflow.
+
+*   [**Skills**](/adk-docs/skills/):
+    Use prebuilt or custom [Agent Skills](https://agentskills.io/) to extend
+    agent capabilities in a way that works efficiently inside AI context window
+    limits.
+
+*   [**Callbacks**](/adk-docs/callbacks/):
+    Hook into specific events during an agent's execution lifecycle to add
+    logging, monitoring, or custom side-effects without altering core agent
+    logic.
+
+
+## Next Steps
 
 Now that you have an overview of the different agent types available in ADK, dive deeper into how they work and how to use them effectively:
 

docs/skills/index.md

@@ -0,0 +1,154 @@
+# Skills for ADK agents
+
+<div class="language-support-tag">
+    <span class="lst-supported">Supported in ADK</span><span class="lst-python">Python v1.25.0</span><span class="lst-preview">Experimental</span>
+</div>
+
+An agent ***Skill*** is a self-contained unit of functionality that an ADK agent
+can use to perform a specific task. An agent Skill encapsulates the necessary
+instructions, resources, and tools required for a task, based on the
+[Agent Skill specification](https://agentskills.io/specification).
+The structure of a Skill allows it to be loaded incrementally to minimize the
+impact on the operating context window of the agent.
+
+!!! example "Experimental"
+    The Skills feature is experimental and has some
+    [known limitations](#known-limitations). We welcome your
+    [feedback](https://github.com/google/adk-python/issues/new?template=feature_request.md&labels=skills)!
+
+## Get started
+
+Use the `SkillToolset` class to include one or more Skills in your agent
+definition and then add to your agent's tools list. You can define a
+[Skill in code](#inline-skills),
+or load the skill from a file definition, as shown below:
+
+```python
+import pathlib
+
+from google.adk import Agent
+from google.adk.skills import load_skill_from_dir
+from google.adk.tools import skill_toolset
+
+weather_skill = load_skill_from_dir(
+    pathlib.Path(__file__).parent / "skills" / "weather_skill"
+)
+
+my_skill_toolset = skill_toolset.SkillToolset(
+    skills=[weather_skill]
+)
+
+root_agent = Agent(
+    model="gemini-2.5-flash",
+    name="skill_user_agent",
+    description="An agent that can use specialized skills.",
+    instruction=(
+        "You are a helpful assistant that can leverage skills to perform tasks."
+    ),
+    tools=[
+        my_skill_toolset,
+    ],
+)
+```
+
+For a complete code example of an ADK agent with a Skill, including both
+file-based and in-line Skill definitions, see the code sample
+[skills_agent](https://github.com/google/adk-python/tree/main/contributing/samples/skills_agent).
+
+## Define Skills
+
+The Skills feature allows you to create modular packages of Skill instructions
+and resources that agents can load on demand. This approach helps you organize
+your agent's capabilities and optimize the context window by only loading
+instructions when they are needed. The structure of Skills is organized into
+three levels:
+
+-   **L1 (Metadata):** Provides metadata for skill discovery. This information
+    is defined in the frontmatter section of the `SKILL.md` file and includes
+    properties such as the Skill name and description.
+-   **L2 (Instructions):** Contains the primary instructions for the Skill,
+    loaded when the Skill is triggered by the agent. This information is defined
+    in the body of the `SKILL.md` file.
+-   **L3 (Resources):** Includes additional resources such as reference
+    materials, assets, and scripts that can be loaded as needed. These resources
+    are organized into the following directories:
+    -   `references/`: Additional Markdown files with extended instructions,
+        workflows, or guidance.
+    -   `assets/`: Resource materials such as database schemas, API
+        documentation, templates, or examples.
+    -   `scripts/`: Executable scripts supported by the agent runtime.
+
+### Define Skills with files
+
+The following directory structure shows the recommended way to include Skills in
+your ADK agent project. The `example_skill/` directory shown below, and any
+parallel Skill directories, must follow the
+[Agent Skill specification](https://agentskills.io/specification)
+file structure. Only the `SKILL.md` file is required.
+
+```
+my_agent/
+    agent.py
+    .env
+    skills/
+        example_skill/        # Skill
+            SKILL.md          # main instructions (required)
+            references/
+                REFERENCE.md  # detailed API reference
+                FORMS.md      # form-filling guide
+                *.md          # domain-specific information
+            assets/
+                *.*           # templates, images, data
+            scripts/
+                *.py          # utility scripts
+```
+
+!!! warning "Script execution not supported"
+    Scripts execution is not yet supported and is a
+    [known limitation](#known-limitations).
+
+### Define Skills in code {#inline-skills}
+
+In ADK agents, you can also define Skills within the code of the agent, using
+the `Skill` model class, as shown below. This method of Skill definition enables
+you to dynamically modify skills from your ADK agent code.
+
+```python
+from google.adk.skills import models
+
+greeting_skill = models.Skill(
+    frontmatter=models.Frontmatter(
+        name="greeting-skill",
+        description=(
+            "A friendly greeting skill that can say hello to a specific person."
+        ),
+    ),
+    instructions=(
+        "Step 1: Read the 'references/hello_world.txt' file to understand how"
+        " to greet the user. Step 2: Return a greeting based on the reference."
+    ),
+    resources=models.Resources(
+        references={
+            "hello_world.txt": "Hello! So glad to have you here!",
+            "example.md": "This is an example reference.",
+        },
+    ),
+)
+```
+
+## Known limitations {#known-limitations}
+
+The Skills feature is experimental and includes the following
+limitations:
+
+-   **Script execution:** The Skills feature does not currently support
+    script execution (`scripts/` directory).
+
+## Next steps
+
+Check out these resources for building agents with Skills:
+
+*   ADK Skills agent code sample:
+    [skills_agent](https://github.com/google/adk-python/tree/main/contributing/samples/skills_agent).
+*   Agent Skills
+    [specification documentation](https://agentskills.io/)

mkdocs.yml

@@ -225,6 +225,7 @@ plugins:
         - integrations/*.md
         - tools/*.md
         - tools-custom/*.md
+        - skills/*.md
         Run Agents:
         - runtime/*.md
         - deploy/*.md
@@ -304,6 +305,8 @@ nav:
       - OpenAPI tools: tools-custom/openapi-tools.md
       - Authentication: tools-custom/authentication.md
       - Tool limitations: tools/limitations.md
+    - Skills for Agents:
+      - skills/index.md
   - Run Agents:
     - Agent Runtime:
       - Agent Runtime: runtime/index.md