bk-instruction

name	bk-instruction
description	BlueKiwi instruction template management skill. Creates, updates, and deletes agent instruction templates, and links credentials using natural language. This skill should be used when the user says "/bk-instruction", "create instruction", "manage instruction templates", or wants to manage BlueKiwi instruction templates.
user_invocable	true

Asking questions across runtimes: wherever this skill says AskUserQuestion, use your host runtime's native structured-question tool: AskUserQuestion (Claude Code), clarify (Hermes Agent), requestUserInput (Codex CLI), question (opencode). Always present the choices through that tool rather than plain prose. If the runtime has no such tool, list the options as numbered text and wait for the user's reply before proceeding.

BlueKiwi Instruction Management

Create, update, and delete agent instruction templates. Optionally link credentials to instructions using natural language.

Argument Handling

• /bk-instruction → Show action selection menu.
• /bk-instruction add <title> → Start creating a new instruction.
• /bk-instruction list → Show instruction list.
• /bk-instruction move <id> <folder id> → Move an instruction between folders.

What is an Instruction?

An instruction is an execution directive that a workflow node delivers to the agent at runtime.

• Well-written instructions control agent behavior precisely.
• Instructions can optionally bind a default credential via credential_id. When a workflow node references this instruction, the credential is available automatically at runtime.

Execution Steps

Step 0: Select Action

If no argument, ask via AskUserQuestion:

• header: "Instructions"
• options: ["List", "Create new", "Edit", "Move", "Delete"]

---

Action: List

Call list_instructions and display results:

Instruction Templates
━━━━━━━━━━━━━━━━━━━━━━━━━
ID   Title                   Agent Type    Active
━━━━━━━━━━━━━━━━━━━━━━━━━
1    SaaS Competitor Analysis  general       ✅
2    Code Review Checklist     code-review   ✅
━━━━━━━━━━━━━━━━━━━━━━━━━
2 total

For folder-based filtering → call list_folders, then re-query with list_instructions(folder_id).

---

Action: Create New

Collect basic info:

1. Title: ask via AskUserQuestion.
2. Agent type: ask via AskUserQuestion (options: ["general", "code-review", "data-analysis", "Type my own"])
3. Tags: comma-separated keywords (optional)
4. Priority: integer (default 0, higher = more important)

Write content:

Ask how to write the content via AskUserQuestion:

• header: "Write content"
• "How would you like to write the instruction content?"
• options: ["I'll write it myself", "Generate AI draft for review"]

If "Generate AI draft":

Based on the goal and agent type, write a draft using this format:

## Goal
<1-sentence goal>

## Instructions
1. <specific action 1>
2. <specific action 2>
...

## Output Format
<expected output format>

## Success Criteria
- <quantitative criterion 1>
- <quantitative criterion 2>

Show the draft and ask if the user wants to modify it.

VS Component Directives

When writing instructions for visual_selection: true gate nodes, include a VS directive block that tells the execution agent which components to render:

## VS Components
Use bk-options for the main selection. Add data-recommended to the suggested choice.
Include a bk-slider named "confidence" (0-100, default 75, unit "%").
Add a bk-section break before the slider.

The execution agent reads this directive and composes the corresponding bk-* HTML fragment. Available components: bk-options, bk-cards, bk-checklist, bk-code-compare, bk-slider, bk-ranking, bk-matrix, bk-split, bk-pros-cons, bk-mockup, bk-timeline.

Write the directive in concrete terms. Specify:

• which component(s) to use
• which option should be marked data-recommended, if any
• names, ranges, defaults, and units for sliders
• which items must appear in rankings, checklists, or matrix plots
• the user's language for all visible text

Credential binding:

Ask: "Does this instruction use an external service?" via AskUserQuestion:

• options: ["Yes, specify a service", "No"]

If "Yes":

1. Ask the user to describe the service in natural language. Example: "Use the GitHub API to fetch the PR list."
2. Call list_credentials to get registered credentials.
3. Try to match the input against service_name (case-insensitive partial match).
4. Show the match result and confirm:

Matched credentials for "GitHub":
  → ID 2: github (GitHub PAT)

Bind this credential to the instruction?

If matched: set credential_id in the create_instruction call (see below).

If no match: "Could not find a matching credential. Register it first with /bk-credential add."

Select folder: Call list_folders, show the tree to the user, then ask via AskUserQuestion which folder the new instruction should live in. If the user picks nothing, omit folder_id — the server drops the instruction into the caller's My Workspace.

Folders control who else can see/edit this instruction: group-shared folders expose the instruction to the members of those groups; personal folders keep it caller-only. To change visibility later, either move the instruction with move_instruction or change the folder's sharing with the folder share APIs.

Register:

Call create_instruction:

{
  "title": "<title>",
  "content": "<content>",
  "agent_type": "<agent type>",
  "tags": ["tag1", "tag2"],
  "priority": 0,
  "credential_id": <credential id or omit>,
  "folder_id": <folder id or omit>
}

On success:

✅ Instruction registered
Title: <title> (ID: <id>)
Credential: <service_name> (ID: <credential_id>) — or "없음"

To use this instruction in a workflow node, set instruction_id: <id>
when designing nodes with `/bk-create`.

---

Action: Edit

Call list_instructions → select target via AskUserQuestion.

Ask what to change (AskUserQuestion):

• options: ["Change title", "Edit content", "Change agent type", "Change credential", "Activate/Deactivate", "Cancel"]

If "Change credential": call list_credentials, show options, then call update_instruction with credential_id (or null to unbind).

Call update_instruction with only the changed fields.

---

Action: Move

Call list_instructions → select the instruction to move via AskUserQuestion.

Call list_folders → display the folder tree and ask which folder to move into (AskUserQuestion).

Call move_instruction:

{
  "instruction_id": <id>,
  "folder_id": <target folder id>
}

The server validates that the caller has edit access on the target folder (otherwise returns 403). Moving between group-shared folders changes who can see/edit the instruction because visibility is inherited from the folder unless the instruction has an explicit visibility_override.

On 403: tell the user "이 폴더로 이동할 권한이 없습니다. 다른 폴더를 선택하거나, 폴더 소유자에게 contributor 권한을 요청하세요." Offer to retry with a different folder via AskUserQuestion. Do not silently swallow the error.

---

Action: Delete

Call list_instructions → select target via AskUserQuestion.

Confirm via AskUserQuestion:

• header: "Confirm delete"
• "Delete '{title}'? This will fail if any workflow node is using it."
• options: ["Delete", "Cancel"]

Call delete_instruction. On 409 error, show which workflow is using it.