.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "tutorial/task_agent_skill.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_tutorial_task_agent_skill.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_tutorial_task_agent_skill.py:


.. _agent_skill:

Agent Skill
============================

`Agent skill <https://claude.com/blog/skills>`_ is an approach proposed by
Anthropic to improve agent capabilities on specific tasks.

AgentScope provides built-in support for Agent Skills through the ``Toolkit``
class, allowing users to easily register and manage agent skills.

The related APIs are as follows:

.. list-table:: Agent skill API in ``Toolkit`` class
    :header-rows: 1

    * - API
      - Description
    * - ``register_agent_skill``
      - Register agent skills from a given directory.
    * - ``remove_agent_skill``
      - Remove a registered agent skill by name.
    * - ``get_agent_skill_prompt``
      - Get the prompt for all registered agent skills, which can be
        attached to the system prompt for the agent.

In this section we demonstrate how to register agent skills and use them in an
ReAct agent.

.. GENERATED FROM PYTHON SOURCE LINES 32-40

.. code-block:: Python

    import os

    from agentscope.agent import ReActAgent
    from agentscope.formatter import DashScopeChatFormatter
    from agentscope.memory import InMemoryMemory
    from agentscope.model import DashScopeChatModel
    from agentscope.tool import Toolkit








.. GENERATED FROM PYTHON SOURCE LINES 41-62

Registering Agent Skills
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

First, we need to prepare an agent skill directory, which follows the
requirements specified in the `Anthropic blog <https://claude.com/blog/skills>`_.

.. note:: The skill directory must contain a ``SKILL.md`` file containing
 YAML frontmatter and instructions.

Here, we fake an example skill directory ``sample_skill`` with the following files:

.. code-block:: markdown

  ---
  name: sample_skill
  description: A sample agent skill for demonstration.
  ---

  # Sample Skill
  ...


.. GENERATED FROM PYTHON SOURCE LINES 62-76

.. code-block:: Python


    os.makedirs("sample_skill", exist_ok=True)
    with open("sample_skill/SKILL.md", "w", encoding="utf-8") as f:
        f.write(
            """---
    name: sample_skill
    description: A sample agent skill for demonstration.
    ---

    # Sample Skill
    ...
    """,
        )








.. GENERATED FROM PYTHON SOURCE LINES 77-80

Then, we can register the skill using the ``register_agent_skill`` API of
the ``Toolkit`` class.


.. GENERATED FROM PYTHON SOURCE LINES 80-85

.. code-block:: Python


    toolkit = Toolkit()

    toolkit.register_agent_skill("sample_skill")








.. GENERATED FROM PYTHON SOURCE LINES 86-88

After that, we can get the prompt for all registered agent skills using the
``get_agent_skill_prompt`` API

.. GENERATED FROM PYTHON SOURCE LINES 88-93

.. code-block:: Python


    agent_skill_prompt = toolkit.get_agent_skill_prompt()
    print("Agent Skill Prompt:")
    print(agent_skill_prompt)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Agent Skill Prompt:
    # Agent Skills
    The agent skills are a collection of folds of instructions, scripts, and resources that you can load dynamically to improve performance on specialized tasks. Each agent skill has a `SKILL.md` file in its folder that describes how to use the skill. If you want to use a skill, you MUST read its `SKILL.md` file carefully.
    ## sample_skill
    A sample agent skill for demonstration.
    Check "sample_skill/SKILL.md" for how to use this skill




.. GENERATED FROM PYTHON SOURCE LINES 94-96

Of course, we can customize the prompt template when creating the ``Toolkit``
instance.

.. GENERATED FROM PYTHON SOURCE LINES 96-110

.. code-block:: Python


    toolkit = Toolkit(
        # The instruction that introduces how to use the skill to the agent/llm
        agent_skill_instruction="<system-info>You're provided a collection of skills, each in a directory and described by a SKILL.md file.</system-info>\n",
        # The template for formatting each skill's prompt, must contain
        # {name}, {description}, and {dir} fields
        agent_skill_template="- {name}({dir}): {description}",
    )

    toolkit.register_agent_skill("sample_skill")
    agent_skill_prompt = toolkit.get_agent_skill_prompt()
    print("Customized Agent Skill Prompt:")
    print(agent_skill_prompt)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Customized Agent Skill Prompt:
    <system-info>You're provided a collection of skills, each in a directory and described by a SKILL.md file.</system-info>

    - sample_skill(sample_skill): A sample agent skill for demonstration.




.. GENERATED FROM PYTHON SOURCE LINES 111-123

Integrating Agent Skills with ReActAgent
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The `ReActAgent` class in AgentScope will attach the agent skill prompt to
the system prompt automatically.

We can create a ReAct agent with the registered agent skills as follows:

.. important:: When using agent skills, the agent must be equipped with text
 file reading or shell command tools to access the skill instructions in
 `SKILL.md` files.


.. GENERATED FROM PYTHON SOURCE LINES 123-138

.. code-block:: Python


    agent = ReActAgent(
        name="Friday",
        sys_prompt="You are a helpful assistant named Friday.",
        model=DashScopeChatModel(
            model_name="qwen3-max",
            api_key=os.environ["DASHSCOPE_API_KEY"],
        ),
        memory=InMemoryMemory(),
        formatter=DashScopeChatFormatter(),
        toolkit=toolkit,
    )

    print("Agent's System Prompt with Agent Skills:")
    print(agent.sys_prompt)




.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Agent's System Prompt with Agent Skills:
    You are a helpful assistant named Friday.

    <system-info>You're provided a collection of skills, each in a directory and described by a SKILL.md file.</system-info>

    - sample_skill(sample_skill): A sample agent skill for demonstration.





.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 0.004 seconds)


.. _sphx_glr_download_tutorial_task_agent_skill.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: task_agent_skill.ipynb <task_agent_skill.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: task_agent_skill.py <task_agent_skill.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: task_agent_skill.zip <task_agent_skill.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_