Teach Promptless a custom task

Promptless ships with default behaviors, like reviewing code PRs for documentation impact, but you can teach it new or customized tasks on top of those defaults. A custom task pairs two ingredients: a trigger that decides when Promptless runs, and a workflow written as instructions that describes what it does. This page covers the general process, including prerequisites, the workflow, the trigger, and how a run unfolds.

The two ingredients of a custom task

Every custom task combines two pieces:

• A trigger determines when Promptless runs — you configure it in the Triggers section of the Configuration page.
• A written workflow is the set of instructions the agent follows when that trigger fires. It lives as a file under doc_workflows/ in your Knowledge Base or as an Agent Skill in a doc collection, with a hook in PROMPTLESS.md that points to it (see Write the workflow).

Promptless follows written instructions well, so the guidance you provide can redirect or augment its built-in default behavior.

This trigger-plus-instructions pattern is general: you pair written instructions with any supported trigger type so the same mechanism drives many different custom tasks. There is an example at the end of this page to illustrate.

Note

This page builds on How Promptless learns your docs, which covers where Promptless reads custom guidance — AGENTS.md/CLAUDE.md in your docs repo, Agent Skills under .claude/skills/, .agents/skills/, or .cursor/skills/, and PROMPTLESS.md.

Prerequisites

Before you build a custom task, make sure you have:

• The relevant integration or trigger source connected. For example, the GitHub integration for a GitHub PR task.
• The ability to chat with Promptless in Slack or Teams to make edits for you, or admin access to edit the Knowledge Base directly.

Write the workflow

The workflow is the what: the concrete instructions the agent follows once a trigger fires. Give the workflow a home and pair it with an “If, then” hook in PROMPTLESS.md. The workflow can live in one of two places:

• As a markdown file under doc_workflows/ in your Knowledge Base. Write the instructions as their own file (for example, doc_workflows/review-inbound-doc-prs.md).
• As an Agent Skill in a doc collection (your docs repo, under .claude/skills/, .agents/skills/, or .cursor/skills/).

Add the hook in PROMPTLESS.md, and if the skill lives in a doc collection, the hook should name which doc collection. For example, “When a contributor PR is opened in acme/docs, use the contributor-workflow skill from the Acme doc collection.”

Caution

For a custom workflow to activate reliably, have an explicit “If, then” hook in PROMPTLESS.md — of the form “If [condition], then [do this].” PROMPTLESS.md is loaded into the agent’s instructions on every run, so a hook there is always visible to the agent, whereas workflows and Agent Skills are only loaded on demand. A workflow that lives only in a separate workflow or Skill may not fire consistently unless a hook in PROMPTLESS.md points to it. See How Promptless learns your docs for how these files are loaded.

There are two ways to add or update these instructions:

• An organization admin edits PROMPTLESS.md in the Agent Knowledge Base (in the left sidebar, select Agent Knowledge Base).
• You can ask Promptless to make these changes for you — for example, by requesting the update the next time you’re working with Promptless — and it edits PROMPTLESS.md (or the custom skill) and commits the change.

Good workflow instructions are concrete. Spell out what to check, what to prioritize, and what output to produce, so the agent knows exactly what a successful run looks like.

Configure the trigger

The trigger is the when. You manage triggers in the dashboard: in the left sidebar, select Configuration, open the Triggers tab, and choose Add a trigger. You might set up a GitHub PR trigger that activates when a PR is opened or a Slack trigger that listens for messages in a channel and acts when it finds particular criteria you specify.

Caution

The GitHub PR triggers support Opened, First approval, and Merged events. If you want additional reviews at other times in the PR lifecycle, such as when new commits are pushed, request it manually via an @Promptless mention in a PR comment (see GitHub PRs).

Custom tasks built this way are event-driven: a trigger fires on new events (like a PR opening) and does not retroactively scan or audit your existing pages. For one-time, corpus-wide work such as audits, retrofits, or writing from scratch, use Pay down docs debt with Deep Analysis.

How a run unfolds

Once the workflow and trigger are in place, a custom task runs the same way every time:

1. The trigger fires on a qualifying event (like a pull request being opened).
2. Promptless reads the relevant context for that event.
3. It follows your written workflow step by step.
4. It produces the output your instructions define.

The specifics — what context is read and what output lands — depend entirely on the workflow you define.

The review inbound documentation PRs example demonstrates the full process end to end as a written review workflow paired with a GitHub PR trigger. It shows the concrete prerequisites, workflow instructions, trigger YAML, and PROMPTLESS.md updates for one real task.

Example: review inbound documentation PRsAn end-to-end GitHub PR custom workflow.