diff --git a/skills/skill-creator/SKILL.md b/skills/skill-creator/SKILL.md index 4680d5e2d..03fdbd0a0 100644 --- a/skills/skill-creator/SKILL.md +++ b/skills/skill-creator/SKILL.md @@ -1,6 +1,6 @@ --- name: skill-creator -description: Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets. +description: Create or update AgentSkills. Use when designing, structuring, packaging, or enriching skills with scripts, references, assets, and conversation-activation templates that help users engage and provide inputs quickly. --- # Skill Creator @@ -43,6 +43,16 @@ Match the level of specificity to the task's fragility and variability: Think of Codex as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom). +### Activate the Conversation + +Guide the user into fast, low-friction replies. Add short prompts, clear choices, and progressive questions when a skill expects back-and-forth input. + +- Provide 1 opener, 1 clarifying ladder, 1 confirmation checkpoint, and 1 completion prompt. +- Offer defaults and escape hatches ("use defaults", "skip", "not sure"). +- Keep one question per message to avoid fatigue. + +Use `references/chat-activation.md` for ready-to-copy templates. + ### Anatomy of a Skill Every skill consists of a required SKILL.md file and optional bundled resources: @@ -88,6 +98,7 @@ Documentation and reference material intended to be loaded as needed into contex - **Benefits**: Keeps SKILL.md lean, loaded only when Codex determines it's needed - **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md - **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files. +- **Conversation templates**: If the skill needs multi-turn input, store reusable prompt templates in `references/` and link them from SKILL.md. Use `references/chat-activation.md` as a starter set. ##### Assets (`assets/`) @@ -258,6 +269,11 @@ Example: When building a `big-query` skill to handle queries like "How many user 1. Querying BigQuery requires re-discovering the table schemas and relationships each time 2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill +Example: When building a `project-intake` skill to handle "Help me scope this project," the analysis shows: + +1. The skill needs consistent prompts to collect goals, constraints, and outputs +2. A `references/chat-activation.md` file with conversation templates would be helpful to store in the skill + To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets. ### Step 3: Initializing the Skill @@ -301,6 +317,7 @@ Consult these helpful guides based on your skill's needs: - **Multi-step processes**: See references/workflows.md for sequential workflows and conditional logic - **Specific output formats or quality standards**: See references/output-patterns.md for template and example patterns +- **Conversation activation**: See references/chat-activation.md for prompt templates and questioning ladders These files contain established best practices for effective skill design. diff --git a/skills/skill-creator/references/chat-activation.md b/skills/skill-creator/references/chat-activation.md new file mode 100644 index 000000000..417dc9edf --- /dev/null +++ b/skills/skill-creator/references/chat-activation.md @@ -0,0 +1,103 @@ +# Chat Activation Templates + +Use this reference to design conversational flow inside a new skill. Copy the templates into the target skill's SKILL.md (or a reference file) and tailor placeholders. Keep them concise and action-oriented. + +## Core Principles + +- Start with one clear question and 2-4 options so users can answer quickly. +- Ask for missing constraints only; avoid dumping a long questionnaire. +- Offer a recommended default path to reduce choice paralysis. +- Confirm understanding before executing large actions. +- Provide a fast exit path ("skip", "use defaults", "not sure"). + +## Minimal Trigger Map + +Use this to decide when to engage deeper. + +- **Clear intent + low risk**: proceed, confirm scope. +- **Unclear intent**: ask a single clarifying question with options. +- **High risk/irreversible**: confirm twice, restate consequences. +- **Missing inputs**: request only the top 1-2 blocking inputs. + +## Quick-Start Opener Templates + +Choose one style per skill. + +### Option A: Single question + +"What do you want to accomplish with {domain}?" + +### Option B: Menu + default + +"Pick a starting point for {domain}. I recommend **{default}** if you’re unsure.\n1) {option1}\n2) {option2}\n3) {option3}" + +### Option C: Example-driven + +"Give me one example of the desired outcome (e.g., {example1}, {example2})." + +## Clarifying Question Ladder + +Ask in order, stop once you have enough. + +1) Goal: "What outcome should we optimize for?" +2) Scope: "Which part of {system} should we focus on?" +3) Constraints: "Any limits on time, budget, or tools?" +4) Format: "How should the output be delivered (list, table, code, doc)?" + +## Checkpoint Confirmation + +"Here’s what I’ll do: {plan}. Proceed? (yes/no)" + +## Option Picker (Short) + +"Choose one:\n1) {path1}\n2) {path2}\n3) {path3}" + +## Context Recovery (If the user went silent) + +"Quick check — do you want to continue with {last_step}, or should I switch to {fallback}?" + +## Progress Updates (Non-spammy) + +- "I’ve gathered {x}. Next, I’ll {next}." +- "I can proceed with defaults. Want me to?" + +## Skill-Scoped Completion + +"Done. Want any of these next?\n1) {next1}\n2) {next2}\n3) {next3}" + +## Safety/Boundary Prompt + +"This action is reversible by {rollback}. Confirm if you want to proceed." + +## Example: Requirements Gathering (Short) + +"To build {feature}, I need two things: goal and constraints.\n1) What’s the primary goal?\n2) Any must-have constraints?" + +## Example: Debugging/Investigation + +"What’s the exact error message and the last step before it happened?" + +## Example: Content/Copy Generation + +"Who is the audience, and what action should they take after reading it?" + +## Example: Data/Reporting + +"Which metric matters most, and over what time range?" + +## Example: Design/UX + +"What feeling or brand tone should this convey?" + +## Tone Tips + +- Use short sentences. +- Prefer verbs and choices over explanations. +- Avoid stacked questions; keep one question per message. + +## Integration Checklist + +- Include 1 opener template +- Include a 3-step clarifying ladder +- Include a confirmation line before major actions +- Include a completion prompt with 2-3 next steps