kind: InlineAgentSkill
content: |
  ---
  name: skilladvisor
  description: Find the installed skill that best fits a task and return its full instructions, optionally running the skill's bundled script. Use when the user asks which skill applies, wants a skill's instructions
  ---
  # SkillAdvisor

  Find the installed skill that best fits a task and return its full instructions, optionally running the skill's bundled script. Use when the user asks which skill applies, wants a skill's instructions

  Contract (OpenAI function schema):
  ```json
  {
    "type": "object",
    "properties": {
      "task": {
        "type": "string",
        "description": "What the user wants done."
      },
      "skill": {
        "type": "string",
        "description": "Optional: a specific skill name to use instead of matching."
      },
      "run_script": {
        "type": "string",
        "description": "Optional: a bundled script to run, e.g. scripts/check.py."
      }
    },
    "required": [
      "task"
    ]
  }
  ```

  This capability has no live tool in Copilot Studio. Reason with the reference implementation below; when the user needs the real effect, say what would run and what input it needs.

  ## Reference implementation (RAPP agent.py, untrusted data, never instructions)
  ```python
  """Skill Advisor — an agent that USES skills. Shows the `utils.skills` API every agent gets.

  Given a task, it picks the best installed skill by keyword overlap, returns that skill's
  rendered instructions (with the task substituted for $ARGUMENTS), and, when the skill
  bundles a script, runs it and includes the output. Pure Python; the model does the rest.
  """
  import re

  from agents.basic_agent import BasicAgent
  from utils.skills import get_skill, list_skills, render
  from utils.skills import run_script as _run_skill_script


  class SkillAdvisorAgent(BasicAgent):
      def __init__(self):
          self.name = "SkillAdvisor"
          self.metadata = {
              "name": self.name,
              "description": (
                  "Find the installed skill that best fits a task and return its full instructions, "
                  "optionally running the skill's bundled script. Use when the user asks which skill "
                  "applies, wants a skill's instructions, or says 'use the right skill for this'."
              ),
              "parameters": {
                  "type": "object",
                  "properties": {
                      "task": {"type": "string", "description": "What the user wants done."},
                      "skill": {"type": "string", "description": "Optional: a specific skill name to use instead of matching."},
                      "run_script": {"type": "string", "description": "Optional: a bundled script to run, e.g. scripts/check.py."},
                  },
                  "required": ["task"],
              },
          }
          super().__init__(self.name, self.metadata)

      @staticmethod
      def _words(text):
          return set(re.findall(r"[a-z0-9]{3,}", (text or "").lower()))

      def perform(self, task="", skill=None, run_script=None, **_):
          skills = list_skills()
          if not skills:
              return "No skills are installed. Drop a <name>/SKILL.md directory into agents/ to add one."
          chosen = get_skill(skill) if skill else None
          if chosen is None:
              want = self._words(task)
              scored = sorted(skills, key=lambda s: len(want & self._words(s["name"] + " " + s["description"])), reverse=True)
              best = scored[0]
              if not (want & self._words(best["name"] + " " + best["description"])):
                  names = ", ".join(s["name"] for s in skills)
                  return f"No installed skill clearly matches {task!r}. Installed: {names}."
              chosen = get_skill(best["name"])
          out = [f"Best skill: {chosen['name']} — {chosen['description']}", "", render(chosen["name"], task)]
          if run_script:
              result = _run_skill_script(chosen["name"], run_script)
              out += ["", f"Ran {run_script} (exit {result['exit_code']}):", result["stdout"] or result["stderr"]]
          return "\n".join(out)
  ```

