instafy-integration-onboarding
Action-card policy for integration setup and guided onboarding in Instafy's browser.
- License 许可
- AGPL-3.0
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- instafy-integration-onboarding
- description
- Action-card policy for integration setup and guided onboarding in Instafy's browser.
- routing_keywords
- token, api key, secret, connection, portal, dashboard, developer, walk me through, set up, integration, connect, github, repo, import, unauthorized, permission denied, 401, 403
03 SKILL.md 正文
Integration onboarding (action-card contract)
Goal: make provider workflows (GitHub, Slack, WhatsApp, etc.) proactively guide setup instead of failing silently.
Capability preflight
Before claiming success on provider work:
- Identify the provider and requested capability (examples: repo clone, issues read, Slack post, WhatsApp send).
- If auth/scope is missing or uncertain, return an onboarding action first.
- Do not ask users to paste tokens in chat.
Automation strategy (API-first)
If the user asks for repeated/automated actions against a third-party service:
- Prefer official API/integration flows first (more reliable and auditable).
- Use browser automation for repeated or scheduled work only when no viable API exists. Opening the browser to look, verify or show the person the way is always fine.
- If both are possible, explain the API option first and ask which path the user wants.
For high-risk domains (finance, payments, account/security settings):
- Require explicit confirmation before executing impactful actions.
- Summarize the exact action before execution (target account, amount/change, and expected outcome).
Required action types
Use these actions in the JSON response:
request_integrationprovider: provider id (for examplegithub,slack,whatsapp)- optional
description,requiredScopes,capabilities,authMethods,suggestedSecretNames,suggestedSecrets,agentHandles
request_secretname: env var (for exampleGITHUB_TOKEN)- optional
valueLabel,description,whereToGet,sensitive,skill,agentHandles; a skill setup says how to fill each
request_browsertask: the user's browsing request, written as their own message- optional
browserLocation:autounless the user named this device or the Workspace
Use request_integration for account connection/scope onboarding.
Use request_secret for project runtime tokens/webhooks.
Use request_browser to open Instafy's browser when no browser tools are on this turn.
Keep cards small
- Treat action-card
descriptionfields as one-line hints (not documentation). - Put detailed setup steps (where to find tokens, what to click, how to verify) in the
summarytext. - Keep
requiredScopes/capabilitiesshort; only include items you are confident are needed. - In
summary, include a short numbered checklist for where to obtain credentials. If you don’t know the exact provider UI path, include a precise search phrase the user can copy and ask exactly one clarifying question.
Scope model
Keep these scopes distinct:
- User credential scope: user-owned identity/session used to connect providers.
- Project integration scope: per-project provider connection state + scopes/capabilities.
- Project secret scope: per-project runtime env vars for agent execution.
Do not collapse OAuth credentials into project secrets by default.
Failure recovery rule
If commands or APIs fail with auth/permission errors (401/403/unauthorized/permission denied/missing token):
- Return the most relevant onboarding action(s) in the same response.
- Ask the user to confirm when done, then retry.
GitHub repo onboarding
Treat requests like these as direct repo-onboarding intents:
- "continue working on my project https://github.com/org/repo"
- "import this repo"
- "open this GitHub project"
Default behavior:
- Treat the current space as the target workspace.
- Continue with repo import instead of sending the user through a separate onboarding script.
- Keep follow-up questions to a minimum. Only ask about branch or subfolder when the repo is clearly large/ambiguous or the user asked for a specific slice.
For private or access-restricted repos:
- If auth is missing or uncertain, emit
request_integrationforgithub. - Include only the scopes/capabilities you are confident are needed for the next step (for repo import this is usually
repo/repo.read). - After connection completes, provide exactly one retry phrase that resumes the same repo request.
Avoid product bloat:
- Do not invent a bespoke multi-step onboarding checklist when the user already gave the repo intent in chat.
- Prefer one direct retry phrase over multiple variants.
- Use the dedicated onboarding UI only as a shortcut surface; the real contract is that the chat intent should work.
- Do not silently redirect the user into a different space just because the same repo might exist elsewhere. Spaces are isolation boundaries.
Follow-up UX
After onboarding completes, suggest one concrete retry prompt so the user can continue immediately.
- Provide exactly one retry phrase. Don’t add an alternate “then reply …” phrase.
Showing the way in Instafy's browser
When provider setup needs dashboard/login interaction:
- When setup involves the provider's own screens, open Instafy's browser without asking, once per setup. With browser tools on this turn, go there now. Without them, emit one
request_browseraction after anyrequest_secretcards; write itstaskas the user's own request, and say in one sentence where it goes. - Open only an address a skill declares or the user gave you, and walk the screens the declaration names, in order. Never guess a provider address. When a skill declares more than one (such as live and demo) and the user has not chosen, open it only after they have.
- Guide step-by-step and pause for user-only actions (login, MFA, consent) with
request_human_inputon their fields, so the user completes them on the page and chooses Let Octo continue. Never type a password, a one-time code or another credential, and never ask for one in chat. - Stop on the screen that lists a secret value (an API secret, token or key), such as the list whose row opens it. In Instafy's browser, never open a screen that shows the value and never ask the user to open one: others watching that browser can see it, it often cannot be copied out, and it reaches you with the next look at the page. Tell the user to open that same page in a tab of their own browser, open the value there and copy it into its
request_secretcard. - If the user closes or pauses the browser, give manual steps and do not open it again for this setup unless they ask.
04 同仓库更多 Skills
workspace
Work with an Instafy space — find and read its conversations and message history, inspect the person's agents and their context notes, and read run diagnostics. Use when the person mentions an Instafy space, a conversation, an agent such as @octo, a run or plan group id, or asks what was decided or tried earlier in the workspace.
gamma-renamed
Third fixture skill whose frontmatter name differs from its folder.
beta
暂无简介
alpha
First fixture skill.
instafy-web-research
Research and cite web facts, cross-check sources and respect site restrictions.
instafy-space-review
Review accessible recent chats and start at most one useful private Octo conversation with grounded context and a natural next step. Use for an opted-in space review automation or “review this space”; it never carries out the suggested work.