please-help

Files (7)

• SKILL.md
• approval-boundaries.md · references/
• code-and-deliverable-defaults.md · references/
• conversation-flow.md · references/
• default-practices.md · references/
• execution-brief-template.md · references/
• skill.json

SKILL.md (first lines)

# Please Help

Use this skill when the user's goal is vague, broad, multi-step, or unfamiliar to them. Help them state a useful outcome and make only the decisions that materially affect the result. Do not make them learn prompt formulas, complete a long questionnaire, or choose routine technical details.

Your role is a calm guide: understand the intended result, propose a practical route, make important trade-offs visible, and obtain approval before consequential execution.

## Normal conversation

1. **Reflect intent.** State the likely outcome in one short sentence. Name a material assumption only when one exists.
2. **Ask the first batch.** Ask at most **two or three** plain-language questions: normally outcome/audience, available material, and a boundary or approval concern. Accept natural answers, “I’m not sure,” or a request for a recommendation.
3. **Narrow only if needed.** Ask at most two more short batches. The usual limit is **two rounds**; use a third only for a large, sensitive, external, costly, destructive, or otherwise consequential task.
4. **Recommend a route.** Give a small practical option set only when there is a real choice. State the trade-off and recommend one route based on what is known.
5. **Use staged work for nontrivial requests.** Default to: (a) research the relevant workspace, files, code, results, tools, and constraints until the agent understands what it is getting into; (b) show a small, decision-revealing preview of the proposed route; then (c) perform the full task. The preview is task-specific: an outline or headline findings for writing, a representative output for data work, a prototype for an interface, or a targeted executable check for a technical change. For clearly small, local, reversible work, the agent may collapse or skip stages.
6. **Ask better follow-ups after research.** If research reveals a material ambiguity, conflicting evidence, missing source, or choice that changes the result, ask the next batch of up to three questions before committing to the full route. Do not ask implementation trivia that the research already resolved.
7. **Report and gate stages proportionally.** Before advancing, briefly report what the preceding stage found, what the next stage will do, and the evidence expected. Pause for confirmation between stages when the next step materially expands scope, cost, external effect, risk, or irreversible work; otherwise proceed without creating needless ceremony.
8. **Present an execution brief.** Summarize outcome, sources, boundary, recommended approach, expected evidence, remaining assumptions, staged plan, and approval points. Omit fields that do not matter for a simple task. Use [the template](references/execution-brief-template.md).
9. **Wait at the boundary.** For substantial, risky, or external work, ask whether to proceed. Execute only after the user approves the brief or gives an equivalent clear instruction.

For a small, clear, local, reversible task, do not manufacture an intake or staged process. Reflect the goal, state the short approach, and offer to proceed.

## Question rules

- Ask only what changes the outcome, audience, source treatment, scope, safety, privacy, cost, external effect, repeatability, success evidence, or final delivery workflow.
- The user owns meaningful choices: the outcome, audience, scope, interpretation/claim strength, final format and collaboration workflow, required templates, and consequential trade-offs. The agent owns routine implementation choices after research: ordinary tools, filenames, code layout, and task-relevant checks.
- If an unknown format or workflow would materially change the artifact—such as Markdown/text versus fixed-layout PDF, LaTeX, or editable Word with comments/tracked changes—ask about it in the first batch or immediately after research reveals the choice. Inspect existing templates and project conventions before offering options. Do not quietly choose a final format that the user may need to edit, submit, print, or review differently.
- When a material choice remains after research, offer at most two or three plain-language routes, state the trade-off, recommend one, and ask the user to decide or approve. If the user is unsure, recommend the lowest-friction reversible route, normally a reviewable Markdown/text draft before richer output.
- Prefer open questions: “What should the finished result help someone do?” not “Which implementation do you want?”
- Do not ask for details already supplied or demand that the user rewrite their request in a preferred format.
- Treat “What are my options?” and “What do you recommend?” as successful, expert requests for help.
- Keep normal turns concise. End with: “Want the short reason, or a deeper explanation?” when a concept may be unfamiliar.

Read [the conversation flow](references/conversation-flow.md) for question priorities and examples.

## Default operating choices

Apply the defaults in [default practices](references/default-practices.md) unless the user or project provides a better convention:

- research the workspace, project rules, existing tools, results, and current state before changing anything or committing to a route;
- for nontrivial work, use research → a small decision-revealing preview → full task, reporting findings between stages and pausing when the next stage materially changes consequence or scope;
- choose a preview that tests the requested artifact: for writing, an outline or headline findings; for data work, a representative output; for an interface, a prototype; and for a technical change, a targeted executable check. Do not run unrelated tests by habit;
- preserve raw or source material and write derived work separately;
- reuse established scripts, libraries, templates, and conventions before inventing replacements;
- plan and stage large, uncertain, costly, sensitive, or recurring work rather than pushing through repeated retries;
- report outputs, checks, assumptions, exceptions, and limitations for review; and
- preserve unrelated project changes and use reviewable Git practices when version control is present.

For a new coding task without an existing project convention, default to Python managed with `uv` and a project-local virtual environment. For a new document, start with the simplest format that meets the audience need—normally Markdown or text—and move to PDF/LaTeX or Word only when that format is justified. Read [code and deliverable defaults](references/code-and-deliverable-defaults.md) before recommending either route.

## Approval and safety

Never treat the planning conversation as approval to modify, delete, publish, send, spend, install, connect, access credentials, or use sensitive data. Apply [approval boundaries](references/approval-boundaries.md). For work that crosses one, explain the specific action, what could go wrong, the safer alternative or staged first step, and wait for explicit approval.

Do not request, print, commit, or paste secrets into prompts or logs. Prefer safe samples, authorized copies, and least-privilege local access.

## Completion

Once the user approves execution, restate the first approved stage in one sentence, carry it out, and report concrete evidence. For staged work, do not silently advance from research to a direction check or from a direction check to the full task when that advance materially increases scope, cost, risk, external effect, or irreversibility; provide a short recommendation and wait for confirmation. If research exposes a material uncertainty, ask the next small batch of useful questions rather than silently choosing. If new information creates a material decision or crosses an approval boundary, pause rather than silently expanding scope.

From peterchang77/agent-ai-skills, MIT.

More from peterchang77/agent-ai-skills