jeevesagent.skills.skill
========================

.. py:module:: jeevesagent.skills.skill

.. autoapi-nested-parse::

   The :class:`Skill` class — one loadable agent skill.

   A Skill is a directory on disk containing a ``SKILL.md`` file plus
   optional supporting resources. The ``SKILL.md`` has YAML frontmatter
   (metadata that loads at startup) and a markdown body (loaded only
   when the skill is triggered).

   Three flavours of "tools" a skill can ship — none required, freely
   mixable in one skill:

   * **Mode A** (markdown only): the body teaches the model how to use
     the agent's existing built-in tools (``read``, ``write``, ``bash``,
     etc.). No tool manifest, no Python imports. Pure instructions.
   * **Mode C** (frontmatter manifest → subprocess Tool): SKILL.md's
     ``tools:`` block declares a script as a typed tool. At skill load
     the framework wraps the script in a Tool that executes via
     subprocess and returns stdout. Works for ANY language — Python,
     bash, Node, Go.
   * **Mode B** (``tools.py`` auto-discovery): if a ``tools.py`` file
     sits in the skill folder, it's imported at construction. Any
     callable decorated with ``@tool`` becomes a registered Tool when
     the skill is loaded. In-process, Python-only.

   Every Tool ships from a skill is **prefixed with the skill name**
   (``web_research__fetch`` rather than ``fetch``) so multiple skills
   loaded simultaneously don't collide.



Exceptions
----------

.. autoapisummary::

   jeevesagent.skills.skill.SkillError


Classes
-------

.. autoapisummary::

   jeevesagent.skills.skill.Skill
   jeevesagent.skills.skill.SkillMetadata
   jeevesagent.skills.skill.ToolSpec


Module Contents
---------------

.. py:exception:: SkillError

   Bases: :py:obj:`ValueError`


   Raised on invalid skill construction or frontmatter.

   Initialize self.  See help(type(self)) for accurate signature.


.. py:class:: Skill(path: str | pathlib.Path, *, source_label: str | None = None)

   A loadable agent skill.


   .. py:method:: from_text(text: str, *, source_label: str | None = None) -> Skill
      :classmethod:


      Build an inline skill from a SKILL.md-formatted string.

      No filesystem path; bundled scripts and ``tools.py`` aren't
      accessible. Useful for one-off skill definitions in code.



   .. py:method:: list_files() -> list[pathlib.Path]

      Enumerate every file bundled with this skill.



   .. py:method:: load_body() -> str

      Return the full SKILL.md body (without frontmatter).



   .. py:property:: description
      :type: str



   .. py:attribute:: metadata


   .. py:property:: name
      :type: str



   .. py:attribute:: path


   .. py:property:: pending_tools
      :type: list[jeevesagent.tools.registry.Tool]


      The Tool instances this skill will register on load.

      Both Mode B (Python @tool from ``tools.py``) and Mode C
      (subprocess wrappers from frontmatter ``tools:`` manifest)
      contribute to this list. Empty for pure markdown skills.


.. py:class:: SkillMetadata

   Lightweight skill descriptor — what loads at startup.

   The body is NOT in here; it's read on demand via
   :meth:`Skill.load_body`. Keep this small — it lives in the
   system prompt for the entire agent's lifetime.


   .. py:method:: to_catalog_line() -> str

      One-line catalog entry for the system prompt.



   .. py:attribute:: allowed_tools
      :type:  list[str] | None
      :value: None



   .. py:attribute:: compatibility
      :type:  str | None
      :value: None



   .. py:attribute:: declared_tool_count
      :type:  int
      :value: 0



   .. py:attribute:: description
      :type:  str


   .. py:attribute:: extra
      :type:  dict[str, Any]


   .. py:attribute:: has_python_tools
      :type:  bool
      :value: False



   .. py:attribute:: license
      :type:  str | None
      :value: None



   .. py:attribute:: name
      :type:  str


   .. py:attribute:: source_label
      :type:  str | None
      :value: None



.. py:class:: ToolSpec

   One subprocess-tool declaration parsed from frontmatter.

   Mode C — the user declared this script as a tool. The skill load
   flow turns it into a real ``Tool`` whose ``fn`` execs the script
   via subprocess and returns stdout.


   .. py:attribute:: args
      :type:  dict[str, dict[str, Any]]


   .. py:attribute:: description
      :type:  str


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: script
      :type:  str


