A role says what good work looks like. A skill says how to repeat a workflow. Neither one proves that a separate agent ran.
Role
A reusable work contract
Define purpose, inputs, permitted actions, output, acceptance checks, and stopping conditions. One AI session can perform a role directly.
Skill
A repeatable procedure
Define when to use the workflow, its ordered steps, evidence, and output criteria. Keep product-specific connection steps in adapters.
Common specialists to add when needed
Choose the work you need help with. These are role templates, not installed plugins or independent workers. The prompt asks only missing clarification questions, checks existing roles and creates a bounded role in your current team.
Researcher
Compare options and gather evidence for a decision.
Expected output: A sourced brief or comparison with tradeoffs and unknowns.
Add Researcher
Add Researcher with clarification
Help me add a Researcher role to my existing work team for this need: Compare options and gather evidence for a decision.
Use my current team folder. Verify this chat's actual workspace before writes. Read AGENTS.md, POLICY.md, CONTEXT-INDEX.md and relevant existing roles. If the project differs from my intended team, stop with one exact step to open it. Preserve my Lead, active task and existing files. Do not create a second team or edit account instructions.
Ask only questions not already answered in the task or my message. Start with: What decision are we supporting? Which sources are permitted? How current must the evidence be? Do you want a comparison, a short brief or a source list? Also clarify permitted inputs/tools and what you may change. Explain whether my existing role or a small reusable skill could do this instead. Keep the questions in a short batch and wait for the answers needed to define the work.
Once the scope is clear, I authorize creating a bounded project-local role at roles/researcher.md if it adds useful capability. Record purpose, approved inputs, authority, permitted tools, output, acceptance checks and stopping conditions. Expected output: A sourced brief or comparison with tradeoffs and unknowns. Quality check: Important claims trace to evidence; missing information stays unknown. Do not promise expertise or accuracy that has not been demonstrated.
Start with the current session applying the specialist contract. Do not imply a separate worker exists because a role file or name was created. Keep the Lead as the single writer of canonical task state and accepted outputs. Reviewer findings go to a proposal path, not over the accepted artifact. If independent execution would help, propose it separately and verify platform support before claiming it.
Index the new role in CONTEXT-INDEX.md with its use trigger. Ensure AGENTS.md can load the selected role on demand while retaining the active task and Lead ownership. Read back changes and show how I invoke the role. Do not install plugins, grant connector access, add schedulers or perform external actions as part of role creation.
Offer one small non-sensitive trial with observable Done when criteria. If my current inputs already permit that trial, perform it within scope and save its proposal to a unique task artifact path without overwriting accepted work. Otherwise ask for the missing input. Report the role path, actual loading evidence, trial result or not run, and my next action. If local writes are unavailable, return labeled files or downloads and an exact saving step, without claiming they are installed.
If copying is blocked, select the text and copy it manually.
Writer and editor
Turn your material into clear drafts for a defined audience.
Expected output: A draft with requested format and a short explanation of material changes.
Add Writer and editor
Add Writer and editor with clarification
Help me add a Writer and editor role to my existing work team for this need: Turn your material into clear drafts for a defined audience.
Use my current team folder. Verify this chat's actual workspace before writes. Read AGENTS.md, POLICY.md, CONTEXT-INDEX.md and relevant existing roles. If the project differs from my intended team, stop with one exact step to open it. Preserve my Lead, active task and existing files. Do not create a second team or edit account instructions.
Ask only questions not already answered in the task or my message. Start with: Who will read this? What should they understand or do? What format, tone and length do you want? Which facts and style examples may I use? Also clarify permitted inputs/tools and what you may change. Explain whether my existing role or a small reusable skill could do this instead. Keep the questions in a short batch and wait for the answers needed to define the work.
Once the scope is clear, I authorize creating a bounded project-local role at roles/writer-editor.md if it adds useful capability. Record purpose, approved inputs, authority, permitted tools, output, acceptance checks and stopping conditions. Expected output: A draft with requested format and a short explanation of material changes. Quality check: Facts match supplied inputs, tone fits the audience and unsupported claims are removed. Do not promise expertise or accuracy that has not been demonstrated.
Start with the current session applying the specialist contract. Do not imply a separate worker exists because a role file or name was created. Keep the Lead as the single writer of canonical task state and accepted outputs. Reviewer findings go to a proposal path, not over the accepted artifact. If independent execution would help, propose it separately and verify platform support before claiming it.
Index the new role in CONTEXT-INDEX.md with its use trigger. Ensure AGENTS.md can load the selected role on demand while retaining the active task and Lead ownership. Read back changes and show how I invoke the role. Do not install plugins, grant connector access, add schedulers or perform external actions as part of role creation.
Offer one small non-sensitive trial with observable Done when criteria. If my current inputs already permit that trial, perform it within scope and save its proposal to a unique task artifact path without overwriting accepted work. Otherwise ask for the missing input. Report the role path, actual loading evidence, trial result or not run, and my next action. If local writes are unavailable, return labeled files or downloads and an exact saving step, without claiming they are installed.
If copying is blocked, select the text and copy it manually.
Project planner
Break an outcome into manageable steps and dependencies.
Expected output: A plan with owners, dependencies, milestones and explicitly unknown dates.
Add Project planner
Add Project planner with clarification
Help me add a Project planner role to my existing work team for this need: Break an outcome into manageable steps and dependencies.
Use my current team folder. Verify this chat's actual workspace before writes. Read AGENTS.md, POLICY.md, CONTEXT-INDEX.md and relevant existing roles. If the project differs from my intended team, stop with one exact step to open it. Preserve my Lead, active task and existing files. Do not create a second team or edit account instructions.
Ask only questions not already answered in the task or my message. Start with: What outcome and deadline matter? Who owns each part? What constraints or dependencies are already known? Do you need a checklist, timeline or risk review? Also clarify permitted inputs/tools and what you may change. Explain whether my existing role or a small reusable skill could do this instead. Keep the questions in a short batch and wait for the answers needed to define the work.
Once the scope is clear, I authorize creating a bounded project-local role at roles/project-planner.md if it adds useful capability. Record purpose, approved inputs, authority, permitted tools, output, acceptance checks and stopping conditions. Expected output: A plan with owners, dependencies, milestones and explicitly unknown dates. Quality check: Tasks support the outcome; invented commitments and deadlines are absent. Do not promise expertise or accuracy that has not been demonstrated.
Start with the current session applying the specialist contract. Do not imply a separate worker exists because a role file or name was created. Keep the Lead as the single writer of canonical task state and accepted outputs. Reviewer findings go to a proposal path, not over the accepted artifact. If independent execution would help, propose it separately and verify platform support before claiming it.
Index the new role in CONTEXT-INDEX.md with its use trigger. Ensure AGENTS.md can load the selected role on demand while retaining the active task and Lead ownership. Read back changes and show how I invoke the role. Do not install plugins, grant connector access, add schedulers or perform external actions as part of role creation.
Offer one small non-sensitive trial with observable Done when criteria. If my current inputs already permit that trial, perform it within scope and save its proposal to a unique task artifact path without overwriting accepted work. Otherwise ask for the missing input. Report the role path, actual loading evidence, trial result or not run, and my next action. If local writes are unavailable, return labeled files or downloads and an exact saving step, without claiming they are installed.
If copying is blocked, select the text and copy it manually.
Data analyst
Check and summarize a small approved dataset.
Expected output: A reproducible summary, calculation or chart with data-quality notes.
Add Data analyst
Add Data analyst with clarification
Help me add a Data analyst role to my existing work team for this need: Check and summarize a small approved dataset.
Use my current team folder. Verify this chat's actual workspace before writes. Read AGENTS.md, POLICY.md, CONTEXT-INDEX.md and relevant existing roles. If the project differs from my intended team, stop with one exact step to open it. Preserve my Lead, active task and existing files. Do not create a second team or edit account instructions.
Ask only questions not already answered in the task or my message. Start with: What question should the data answer? What does each field mean? Where may the data be processed? Which calculations and output format do you need? Also clarify permitted inputs/tools and what you may change. Explain whether my existing role or a small reusable skill could do this instead. Keep the questions in a short batch and wait for the answers needed to define the work.
Once the scope is clear, I authorize creating a bounded project-local role at roles/data-analyst.md if it adds useful capability. Record purpose, approved inputs, authority, permitted tools, output, acceptance checks and stopping conditions. Expected output: A reproducible summary, calculation or chart with data-quality notes. Quality check: Calculations reconcile to the source and missing or ambiguous values are explained. Do not promise expertise or accuracy that has not been demonstrated.
Start with the current session applying the specialist contract. Do not imply a separate worker exists because a role file or name was created. Keep the Lead as the single writer of canonical task state and accepted outputs. Reviewer findings go to a proposal path, not over the accepted artifact. If independent execution would help, propose it separately and verify platform support before claiming it.
Index the new role in CONTEXT-INDEX.md with its use trigger. Ensure AGENTS.md can load the selected role on demand while retaining the active task and Lead ownership. Read back changes and show how I invoke the role. Do not install plugins, grant connector access, add schedulers or perform external actions as part of role creation.
Offer one small non-sensitive trial with observable Done when criteria. If my current inputs already permit that trial, perform it within scope and save its proposal to a unique task artifact path without overwriting accepted work. Otherwise ask for the missing input. Report the role path, actual loading evidence, trial result or not run, and my next action. If local writes are unavailable, return labeled files or downloads and an exact saving step, without claiming they are installed.
If copying is blocked, select the text and copy it manually.
Quality reviewer
Check an artifact against its acceptance criteria.
Expected output: Findings with evidence, importance and suggested corrections.
Add Quality reviewer
Add Quality reviewer with clarification
Help me add a Quality reviewer role to my existing work team for this need: Check an artifact against its acceptance criteria.
Use my current team folder. Verify this chat's actual workspace before writes. Read AGENTS.md, POLICY.md, CONTEXT-INDEX.md and relevant existing roles. If the project differs from my intended team, stop with one exact step to open it. Preserve my Lead, active task and existing files. Do not create a second team or edit account instructions.
Ask only questions not already answered in the task or my message. Start with: Which artifact and Done when criteria should I review? What evidence may I inspect? Which errors matter most? Should I report findings only or propose corrections? Also clarify permitted inputs/tools and what you may change. Explain whether my existing role or a small reusable skill could do this instead. Keep the questions in a short batch and wait for the answers needed to define the work.
Once the scope is clear, I authorize creating a bounded project-local role at roles/reviewer.md if it adds useful capability. Record purpose, approved inputs, authority, permitted tools, output, acceptance checks and stopping conditions. Expected output: Findings with evidence, importance and suggested corrections. Quality check: Each finding points to the artifact and a criterion; accepted files are preserved. Do not promise expertise or accuracy that has not been demonstrated.
Start with the current session applying the specialist contract. Do not imply a separate worker exists because a role file or name was created. Keep the Lead as the single writer of canonical task state and accepted outputs. Reviewer findings go to a proposal path, not over the accepted artifact. If independent execution would help, propose it separately and verify platform support before claiming it.
Index the new role in CONTEXT-INDEX.md with its use trigger. Ensure AGENTS.md can load the selected role on demand while retaining the active task and Lead ownership. Read back changes and show how I invoke the role. Do not install plugins, grant connector access, add schedulers or perform external actions as part of role creation.
Offer one small non-sensitive trial with observable Done when criteria. If my current inputs already permit that trial, perform it within scope and save its proposal to a unique task artifact path without overwriting accepted work. Otherwise ask for the missing input. Report the role path, actual loading evidence, trial result or not run, and my next action. If local writes are unavailable, return labeled files or downloads and an exact saving step, without claiming they are installed.
If copying is blocked, select the text and copy it manually.
Developer
Implement a small change and verify the resulting behavior.
Expected output: A scoped change, verification results and instructions for running or reverting it.
Add Developer
Add Developer with clarification
Help me add a Developer role to my existing work team for this need: Implement a small change and verify the resulting behavior.
Use my current team folder. Verify this chat's actual workspace before writes. Read AGENTS.md, POLICY.md, CONTEXT-INDEX.md and relevant existing roles. If the project differs from my intended team, stop with one exact step to open it. Preserve my Lead, active task and existing files. Do not create a second team or edit account instructions.
Ask only questions not already answered in the task or my message. Start with: What behavior should change? Which repository and files are authorized? What environment and dependencies already exist? What acceptance checks prove the change? Also clarify permitted inputs/tools and what you may change. Explain whether my existing role or a small reusable skill could do this instead. Keep the questions in a short batch and wait for the answers needed to define the work.
Once the scope is clear, I authorize creating a bounded project-local role at roles/developer.md if it adds useful capability. Record purpose, approved inputs, authority, permitted tools, output, acceptance checks and stopping conditions. Expected output: A scoped change, verification results and instructions for running or reverting it. Quality check: The requested behavior is tested; unrelated work is preserved and unrun checks are labeled. Do not promise expertise or accuracy that has not been demonstrated.
Start with the current session applying the specialist contract. Do not imply a separate worker exists because a role file or name was created. Keep the Lead as the single writer of canonical task state and accepted outputs. Reviewer findings go to a proposal path, not over the accepted artifact. If independent execution would help, propose it separately and verify platform support before claiming it.
Index the new role in CONTEXT-INDEX.md with its use trigger. Ensure AGENTS.md can load the selected role on demand while retaining the active task and Lead ownership. Read back changes and show how I invoke the role. Do not install plugins, grant connector access, add schedulers or perform external actions as part of role creation.
Offer one small non-sensitive trial with observable Done when criteria. If my current inputs already permit that trial, perform it within scope and save its proposal to a unique task artifact path without overwriting accepted work. Otherwise ask for the missing input. Report the role path, actual loading evidence, trial result or not run, and my next action. If local writes are unavailable, return labeled files or downloads and an exact saving step, without claiming they are installed.
If copying is blocked, select the text and copy it manually.
UX and UI designer
Make a screen or workflow easier for its intended users.
Expected output: A prioritized design proposal tied to user tasks and observable usability checks.
Add UX and UI designer
Add UX and UI designer with clarification
Help me add a UX and UI designer role to my existing work team for this need: Make a screen or workflow easier for its intended users.
Use my current team folder. Verify this chat's actual workspace before writes. Read AGENTS.md, POLICY.md, CONTEXT-INDEX.md and relevant existing roles. If the project differs from my intended team, stop with one exact step to open it. Preserve my Lead, active task and existing files. Do not create a second team or edit account instructions.
Ask only questions not already answered in the task or my message. Start with: Who uses this and what are they trying to accomplish? Which screen or workflow should I inspect? What devices and existing design conventions matter? Do you want findings, a sketch or a small implementation proposal? Also clarify permitted inputs/tools and what you may change. Explain whether my existing role or a small reusable skill could do this instead. Keep the questions in a short batch and wait for the answers needed to define the work.
Once the scope is clear, I authorize creating a bounded project-local role at roles/ux-designer.md if it adds useful capability. Record purpose, approved inputs, authority, permitted tools, output, acceptance checks and stopping conditions. Expected output: A prioritized design proposal tied to user tasks and observable usability checks. Quality check: Recommendations explain the user benefit and respect the approved scope and existing design. Do not promise expertise or accuracy that has not been demonstrated.
Start with the current session applying the specialist contract. Do not imply a separate worker exists because a role file or name was created. Keep the Lead as the single writer of canonical task state and accepted outputs. Reviewer findings go to a proposal path, not over the accepted artifact. If independent execution would help, propose it separately and verify platform support before claiming it.
Index the new role in CONTEXT-INDEX.md with its use trigger. Ensure AGENTS.md can load the selected role on demand while retaining the active task and Lead ownership. Read back changes and show how I invoke the role. Do not install plugins, grant connector access, add schedulers or perform external actions as part of role creation.
Offer one small non-sensitive trial with observable Done when criteria. If my current inputs already permit that trial, perform it within scope and save its proposal to a unique task artifact path without overwriting accepted work. Otherwise ask for the missing input. Report the role path, actual loading evidence, trial result or not run, and my next action. If local writes are unavailable, return labeled files or downloads and an exact saving step, without claiming they are installed.
If copying is blocked, select the text and copy it manually.
Accessibility reviewer
Review a page or document for barriers to access.
Expected output: Evidence-based findings and scoped corrections, with manual checks still needed clearly labeled.
Add Accessibility reviewer
Add Accessibility reviewer with clarification
Help me add a Accessibility reviewer role to my existing work team for this need: Review a page or document for barriers to access.
Use my current team folder. Verify this chat's actual workspace before writes. Read AGENTS.md, POLICY.md, CONTEXT-INDEX.md and relevant existing roles. If the project differs from my intended team, stop with one exact step to open it. Preserve my Lead, active task and existing files. Do not create a second team or edit account instructions.
Ask only questions not already answered in the task or my message. Start with: Which page or document should I review? Who is the audience and which accessibility requirements apply? What tools and source files may I inspect? Should I report findings or propose fixes? Also clarify permitted inputs/tools and what you may change. Explain whether my existing role or a small reusable skill could do this instead. Keep the questions in a short batch and wait for the answers needed to define the work.
Once the scope is clear, I authorize creating a bounded project-local role at roles/accessibility-reviewer.md if it adds useful capability. Record purpose, approved inputs, authority, permitted tools, output, acceptance checks and stopping conditions. Expected output: Evidence-based findings and scoped corrections, with manual checks still needed clearly labeled. Quality check: Each finding includes a location and reproducible check; automated checks alone are not called certification. Do not promise expertise or accuracy that has not been demonstrated.
Start with the current session applying the specialist contract. Do not imply a separate worker exists because a role file or name was created. Keep the Lead as the single writer of canonical task state and accepted outputs. Reviewer findings go to a proposal path, not over the accepted artifact. If independent execution would help, propose it separately and verify platform support before claiming it.
Index the new role in CONTEXT-INDEX.md with its use trigger. Ensure AGENTS.md can load the selected role on demand while retaining the active task and Lead ownership. Read back changes and show how I invoke the role. Do not install plugins, grant connector access, add schedulers or perform external actions as part of role creation.
Offer one small non-sensitive trial with observable Done when criteria. If my current inputs already permit that trial, perform it within scope and save its proposal to a unique task artifact path without overwriting accepted work. Otherwise ask for the missing input. Report the role path, actual loading evidence, trial result or not run, and my next action. If local writes are unavailable, return labeled files or downloads and an exact saving step, without claiming they are installed.
If copying is blocked, select the text and copy it manually.
Training designer
Create a short lesson or reusable training aid.
Expected output: A lesson, activity or job aid tied to observable learning outcomes.
Add Training designer
Add Training designer with clarification
Help me add a Training designer role to my existing work team for this need: Create a short lesson or reusable training aid.
Use my current team folder. Verify this chat's actual workspace before writes. Read AGENTS.md, POLICY.md, CONTEXT-INDEX.md and relevant existing roles. If the project differs from my intended team, stop with one exact step to open it. Preserve my Lead, active task and existing files. Do not create a second team or edit account instructions.
Ask only questions not already answered in the task or my message. Start with: Who is learning and what do they already know? What should they be able to do afterward? How much time do they have? What source material and assessment are appropriate? Also clarify permitted inputs/tools and what you may change. Explain whether my existing role or a small reusable skill could do this instead. Keep the questions in a short batch and wait for the answers needed to define the work.
Once the scope is clear, I authorize creating a bounded project-local role at roles/training-designer.md if it adds useful capability. Record purpose, approved inputs, authority, permitted tools, output, acceptance checks and stopping conditions. Expected output: A lesson, activity or job aid tied to observable learning outcomes. Quality check: Activities and assessment match the outcome; content is supported by approved material. Do not promise expertise or accuracy that has not been demonstrated.
Start with the current session applying the specialist contract. Do not imply a separate worker exists because a role file or name was created. Keep the Lead as the single writer of canonical task state and accepted outputs. Reviewer findings go to a proposal path, not over the accepted artifact. If independent execution would help, propose it separately and verify platform support before claiming it.
Index the new role in CONTEXT-INDEX.md with its use trigger. Ensure AGENTS.md can load the selected role on demand while retaining the active task and Lead ownership. Read back changes and show how I invoke the role. Do not install plugins, grant connector access, add schedulers or perform external actions as part of role creation.
Offer one small non-sensitive trial with observable Done when criteria. If my current inputs already permit that trial, perform it within scope and save its proposal to a unique task artifact path without overwriting accepted work. Otherwise ask for the missing input. Report the role path, actual loading evidence, trial result or not run, and my next action. If local writes are unavailable, return labeled files or downloads and an exact saving step, without claiming they are installed.
If copying is blocked, select the text and copy it manually.
Already have a process for adding roles?
Use that process and reuse an existing matching role. New teams created with the current setup prompt include a clarification-first role-addition rule. Older teams can use the prompts above, which inspect and preserve their instructions.
Short prompt for teams with the role-addition rule
I need help with [describe the task]. Follow our role-addition procedure. Reuse an existing role or skill if it fits; otherwise clarify the missing requirements and add a bounded specialist in this team.
If copying is blocked, select the text and copy it manually.
Ask for the role by its name and your task. Its file is loaded only when relevant. For installed packages, use Shared skills and plugins; a role file itself needs no GitHub access or product plugin.
Optional demo: Research role example
starter-kit/roles/research.md
# Research role
Purpose: compare the supplied fictional options with clear evidence and tradeoffs.
Authority: read the indexed task inputs and update its task record and artifact
within the approved scope. Follow POLICY.md. Do not browse or access calendars.
Compare every option against the four criteria in the Brief. Attribute claims
to those supplied facts. Distinguish inference from fact and state uncertainty.
Any of the options can be recommended when the tradeoff is explained. Do not
invent weights or conflicts. Use the compare-options skill and Done when list.
This role is performed in one session. It is not an independent worker.
If copying is blocked, select the text and copy it manually.
Optional demo: comparison skill example
starter-kit/skills/compare-options/SKILL.md
# Compare supplied options
Input: the task Brief, its four criteria, and its Done when list.
1. Extract the supplied facts for each of the three options.
2. Compare all three against availability, focus time, transition, and overrun risk.
3. Recommend one option. Explain the evidence, the tradeoff, and any assumptions.
4. Save tasks/meeting-times/artifacts/recommendation.md and read it back.
5. Check every Done when criterion. Append the evidence to the task Work log,
update only the header for current state, and save paths and restart guidance
in Handoff. Read back the task and run its validator if available.
Missing availability is unknown, including availability beyond the scheduled
30 minutes. No stated hard stop does not establish an overrun buffer.
No criterion weights are assigned. Do not substitute equal weights or numerical
scores. Explain a qualitative tradeoff without forcing a preferred option.
Check the saved recommendation for unsupported claims before marking completed.
Do not browse, invent conflicts, or claim checks that did not run.
If copying is blocked, select the text and copy it manually.
Describe execution honestly
Single-session role
One runtime applies a role contract and does the work.
Sequential handoff
A later session resumes from saved state and artifacts.
Independent worker
A separate execution receives a bounded assignment and returns an identifiable artifact.
Use Role: research | Mode: single_session_role and a separate Session: fresh or Session: resumed line. A label is attribution, not delegation evidence. The work-team route starts with a Lead role in one session. The optional demo uses Research. Independent workers remain a separate extension.