Automate: reusable workflow design

Choose and, when requested, implement the smallest maintainable automation that meets the user's workflow. A request for advice or a comparison is read-only; an explicit build request authorizes normal in-scope local implementation. Neither authorizes new external effects, accounts, paid services or deployment.

1. Establish the workflow and success criteria

Use the user's actual request and conversation context. Some runtimes expose $ARGUMENTS; it is not a portable interpolation mechanism. Ask for a description only if the workflow is genuinely absent. Resolve material ambiguities with focused questions, but do not ask again for build approval already given.

If creative exploration would help, use an available brainstorming skill within the user's scope. Do not install a plugin or block a clear implementation request merely because an optional brainstorming skill is unavailable.

Identify:

• Trigger: manual invocation, buffer action, event or schedule.
• Inputs and trust: exact sources, sensitive content, provider/account access and which input is data rather than instructions.
• Output and effects: destination, editable preview versus mutation, recipients, persistence and the exact user-visible result.
• Operational needs: latency, expected volume, state, concurrency, retries, duplicate prevention, cancellation and failure visibility.
• Authorization and acceptance: which actions are already approved, which require a new user decision, and a representative success and failure example.

Inspect existing nearby automations before creating another one. Reuse the right implementation, not just a similar name. Deterministic transformations normally belong in a function or script; add a model only where its judgment is useful.

2. Recommend an implementation

These are tendencies, not capability limits. gptel can use tools and multi-step workflows; an agent skill can also invoke Emacs. Compare the actual configured runtime, data flow and maintenance cost.

Need	Likely implementation
Conversation context/persona without a new workflow	gptel directive or preset
A callable capability with typed inputs/outputs	gptel tool or existing mapped service tool
A buffer-oriented action with controlled insertion	Elisp command using gptel where needed
A reusable agent-led workflow across files/tools	Skill in the intended runtime and scope
A deterministic repeatable operation	Function or script, optionally exposed by a tool/skill
Event-driven or scheduled unattended execution	Supported scheduler/automation plus an explicit execution contract

A skill is instructions, not a scheduler or persistent background worker. For Codex-specific schedules, settings, tool availability or runtime capabilities, use openai-docs and inspect the current local setup. Do not invent an API or claim a mechanism is installed from its documentation alone.

Briefly state the recommendation, reason and expected files. If the request was advisory, stop with the recommendation. If it was to build, implement the reasonable in-scope choice; ask only where a material choice or new authority is needed. Honor an explicit runtime target, and otherwise use the user's active environment and established pairing conventions rather than defaulting to Claude.

3. Implement in the canonical location

Use dotfiles-context when routing dotfiles, paired configuration or Elpaca changes, and elisp-conventions for Elisp edits/tests. Resolve package checkouts with the canonical helper; do not guess active profiles or edit generated mirrors. The current home skill paths link into dotfiles, but verify a path's actual source and target scope before edits rather than treating that layout as universal.

Check existing skill, directive, preset, tool, function and binding definitions before choosing names. Reuse the intended definition where appropriate; preserve unrelated definitions and resolve collisions rather than overwriting/shadowing them.

Agent skill

1. Use skill-creator for both creation and updates. Inspect a small number of relevant neighboring skills as conventions, not blanket authority.
2. Resolve identity and destination first. Honor the exact supplied/runtime-catalog path for updates; inspect project instructions and supported roots for new skills, including native .agents/skills when applicable. Do not move a project skill into global scope or edit a disposable plugin cache.
3. Follow existing paired global/project conventions. Create/update both claude/skills and codex/skills, or paired .claude/skills and .codex/skills, where that is the established layout. An explicit single-tool target requires any divergence record mandated by the repository; do not fabricate an exception or silently break parity.
4. Check for an existing name/qualified identity collision before creation. Metadata must be supported by the target runtime and local integrations; preserve intentional tool-specific arguments. Do not copy arbitrary fields just because a neighboring file has them.
5. Write clear triggers, scope, inputs, procedure, failure behavior and verification. Add scripts/resources where deterministic handling is safer than prose; keep dependencies and generated caches outside Drive and declare their setup.
6. Update required documentation and discovery/catalog metadata. Keep auxiliary files paired as well as the main instructions, except documented differences.

gptel directive or preset

Inspect the installed configuration to choose the supported directive, preset or package custom variable. This dotfiles setup uses presets as well as prompts. Do not assume an old gptel-directives alist is the right integration point.

Keep the prompt's data access and intended context explicit. Add it to the canonical config or owning package under the existing build authority, without duplicating registration or changing unrelated defaults/models.

gptel tool

Inspect the installed gptel-make-tool API and nearby supported registrations. Validate inputs in deterministic code; give side effects and output/failure semantics explicit descriptions. A model's decision to call a tool is not user authorization. Preserve existing approval scope and enforce disallowed actions; do not add generic ask-style tool gates to an auto-mode environment.

Use the mapped service tools and account/secret guidance before external access. Do not embed credentials in code, prompts, fixtures or logs. Do not add unrequested services, privileges, tools or model access as an implicit implementation step.

gptel command

Extract the intended context explicitly and minimize what is sent to a provider. Inspect the installed gptel-request callback/streaming contract before coding. For asynchronous results:

• Capture the original buffer and markers, not whichever buffer is current when the callback runs. Check their liveness and whether the source changed.
• Validate the response type/schema before mutation; handle empty, malformed, failed, cancelled and partial responses without damaging existing content.
• Define how overlapping calls, retries and late callbacks are reconciled. Do not insert the same result twice or overwrite newer user edits.
• Keep parsing and structured I/O in Elisp. Treat model-returned code as data, never something to eval merely to complete response processing.

Make the command interactive when appropriate. Add bindings only when requested or clearly covered by an established convention; preserve existing bindings. Explain a material behavior/insertion choice when needed, without dumping a full function for manual copying or asking the user to install it themselves.

Scheduled or event-driven execution

Use an existing supported scheduler only when this trigger was requested. Make timezone, inputs, approved effects, state location, retry/idempotency policy and failure reporting explicit. Decide how credentials and permissions work without an interactive user. Distinguish a reusable job definition from a request to enable recurring execution; building the former does not authorize activating it. Do not silently weaken authorization to make an unattended job succeed, or start recurring jobs during an advisory request.

Two cross-project principles apply. Failure and liveness alerts go through the shared launchd-heartbeat service; read /Users/pablostafforini/My Drive/dotfiles/claude/context/alerting.md before designing them, and do not build a project-specific alert channel. An unattended job renews its own session credentials; a recurring manual refresh is a defect (see "Unattended programs renew their own sessions" in /Users/pablostafforini/My Drive/dotfiles/claude/context/secrets.md).

4. Verify the actual contract

• Skill: validate metadata/resources, test representative success/failure prompts against the instructions, and check scope and paired auxiliary files. Resolver discovery is not proof the active runtime loaded that identity; verify actual availability/invocation using the target runtime when feasible. A new session may be needed; do not claim immediate availability from file existence alone.
• Elisp: follow elisp-conventions for targeted compilation/tests, dependency setup and active-code verification. For emacs/config.org, follow dotfiles-context's profile-aware init-build-profile path, not a generic org-babel-tangle-file call.
• Behavior: exercise the intended input-to-output action and relevant failure cases. For live acceptance use end-to-end when its trigger applies. Testing does not authorize new messages, destructive effects, paid jobs or publication; use isolated fixtures when necessary and state the remaining runtime gap.
• Scheduling: distinguish registration from a successful execution and from confirmed delivery/persistence. Do not leave throwaway recurring jobs running.
• Integration: update required docs; run bin/ai-config-sync audit for paired dotfiles changes and the catalog checks required by dotfiles-context.
• Delivery: commit scoped logical changes, preserve unrelated work, and clean up owned test artifacts/processes. Push or deploy only with separate authority.

Report the implemented type and relevant result. Distinguish built, loaded and behavior-verified states; mention an unresolved gap only where it changes the user's next decision. Never claim an automation is ready merely because a prompt file was written or a dry-run walkthrough looked plausible.