=======================
Create a Custom Skill
=======================

Skills are reusable instruction sets that agents can invoke during their work.
mootup ships with a set of built-in skills; you can add your own to capture
project-specific knowledge, review criteria, or recurring workflows.


What a skill is
----------------

A skill is a directory under ``.claude/skills/`` containing a ``SKILL.md``
file. Agents load available skills at startup. They invoke a skill when the
context matches — or you can ask an agent to invoke one explicitly as a Claude
Code slash command.

Skills are version-controlled alongside your code. Everyone on the project
shares the same skill definitions.


Create the skill
-----------------

#. Create a directory for your skill under ``.claude/skills/``:

   .. code-block:: bash

      mkdir -p .claude/skills/code-review

#. Create a ``SKILL.md`` file in that directory:

   .. code-block:: bash

      touch .claude/skills/code-review/SKILL.md

#. Open the file and write your instructions. A skill file should answer three
   questions:

   - **What is this skill called?** Give it a clear name at the top.
   - **When should an agent use it?** Describe the trigger — what situation
     or request should activate this skill.
   - **What should the agent do?** Give the concrete steps, criteria, or
     output format.

   Example — a ``code-review`` skill:

   .. code-block:: text

      # code-review

      Use this skill when asked to review a pull request or a diff.

      Review criteria:
      - Check for missing input validation on user-controlled fields
      - Flag any new dependencies and ask why they are needed
      - Confirm that new public functions have docstrings
      - Note any functions longer than 50 lines as candidates for extraction
      - Do not comment on style unless the diff violates the project linter

      Output format:
      Post findings as a numbered list. Start with blockers, then suggestions.
      End with a one-line summary: "LGTM", "Minor issues", or "Needs work".

#. Save the file. The skill is available to all agents after the next restart:

   .. code-block:: bash

      moot down
      moot up


Invoking a skill
-----------------

Agents pick up skills automatically when the context matches the trigger
description. You can also ask an agent to use a skill directly:

.. code-block:: text

   @Implementation run the code-review skill on the latest diff

Or invoke it as a Claude Code slash command from your editor:

.. code-block:: text

   /code-review