PromptFloe Developer Docs
Build

Run a skill

Invoke a critique skill — /roast, /seo-audit, /eli5, etc. — from server code. Results stream as markdown chunks plus optional structured insights.

#Basic call

const result = await client.skills.run({
  alias: 'roast',
  appId: 'app_abc',          // OR
  // url: 'https://example.com',  // OR
  // text: 'paste of content to critique',
});

console.log(result.markdown);
console.log(result.insights);

#Streaming variant

For real-time UX (showing the report as it generates), use the stream variant:

const stream = client.skills.runStream({
  alias: 'seo-audit',
  url: 'https://example.com',
});

for await (const ev of stream) {
  if (ev.type === 'chunk')    process.stdout.write(ev.delta);
  if (ev.type === 'insight')  console.log('\ninsight:', ev.insight);
  if (ev.type === 'done')     console.log('\nfinished, tokens:', ev.tokensUsed);
}

#Request fields

FieldTypeDescription
aliasrequiredstringSkill alias without the / prefix. e.g. "roast", "seo-audit". For custom skills, omit the @ and prefix with workspace: "@my-skill" → "my-skill".
appIdstringRun the skill against an app you own. Files in the app are passed as context.
chatIdstringRun within an existing chat. Result appears as a message in that chat.
urlstringRun against a public URL (skill fetches and analyzes).
textstringRun against raw text.
argsstringFree-form additional arguments — same as appending after a slash command.
workspaceContextOverrideobjectPer-run override of brand voice fields.

#Response shape

FieldTypeDescription
runIdstringUnique id for this run. Use for follow-up calls or webhooks.
markdownstringThe full critique report as markdown.
insightsInsight[]Structured chips — { kind, label, detail } objects extracted from the report.
relatedstring[]Other skill aliases the engine thinks might be useful next.
tokensUsednumberTokens consumed by this run. Counts against your daily quota.
durationMsnumberEnd-to-end run duration.

#Quotas & rate limits

Skills run against your daily critique quota (separate from the augmenter quota). If you exceed the limit, the call returns 403 quota_exceeded. Use X-RateLimit-Remaining-Critique to check headroom.

See Rate limits for the per-tier breakdown.

#Where to go next

PromptFloe developer docs