skills-toolkit

Skills Toolkit

Author and validate SKILL.md files and agent .md files for this marketplace. Replaces the old skill-creator-agent, skill-validator-agent, agent-author, and agent-validator prose-based agents (retired 2026-07-12) and their 5 command wrappers.

When to use

• "create a skill", "new SKILL.md", "add an agent"
• "validate this skill", "check this agent"
• Before opening a PR that adds or changes a skill/agent in this marketplace

Design principle

The old agents asked the model to self-score a description 0-100 against a rubric, simulate PII regex mentally, and print a "6-Phase Validation" report that had drifted from its own real step count. None of that is verifiable. This skill instead:

1. Runs scripts/validate_skills.py - a real script, not a prompt
2. Relays its findings verbatim
3. Never invents a PASS/FAIL verdict beyond what the script's exit code says

Task* protocol

TaskCreate "Gather requirements"          -> mark in_progress immediately
TaskCreate "Draft SKILL.md content"       -> blocked_by Gather requirements
TaskCreate "Run validate_skills.py"       -> blocked_by Draft SKILL.md content
TaskCreate "Fix findings, re-run if FAIL" -> blocked_by Run validate_skills.py
TaskCreate "Write file, confirm with user" -> blocked_by Fix findings, re-run if FAIL

Creating a new skill

1. Gather the skill's shape via AskUserQuestion rather than open prose - at minimum, name (kebab-case), one-line purpose, and the tool set. Example block (adapt options to context):

   {
     "questions": [
       {
         "question": "What tools does this skill need?",
         "header": "Tool set",
         "multiSelect": true,
         "options": [
           {"label": "Read/Write/Edit", "description": "Reads and writes files directly"},
           {"label": "Bash", "description": "Runs shell commands or scripts"},
           {"label": "AskUserQuestion", "description": "Needs to ask the user structured questions mid-run"},
           {"label": "Task* set", "description": "Tracks multi-step work with TaskCreate/TaskUpdate/TaskGet/TaskList"}
         ]
       }
     ]
   }
   

   For open-ended fields (skill name, one-line purpose, WHEN/WHEN NOT to trigger) that don't reduce to a short option list, ask directly in prose - AskUserQuestion free-text entry covers this. See references/askuserquestion-protocol.md for the full shape and when prose-only is fine.
2. Draft frontmatter:

   ---
   name: <kebab-case-name>
   description: <WHEN it triggers>. <WHEN NOT>. Keep under 250 chars total.
   allowed-tools:
     - Read
     - ...
   version: 1.0.0
   ---
   

3. Draft the body: a ## When to use section, a workflow, and a ## Task* protocol block if the skill does multi-step work with TaskCreate/TaskUpdate in its allowed-tools.
4. Write the file to plugins/<plugin>/skills/<name>/SKILL.md.
5. Run validation (below) before telling the user it's done.