Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

fix(skills): pin install guidance and generalize runtime prompts

wizardchen2d7df096ca30
diff --git a/config/prompt_templates/agent_system_prompt.yaml b/config/prompt_templates/agent_system_prompt.yaml
index 72b42d94f..dcad90136 100644
--- a/config/prompt_templates/agent_system_prompt.yaml
+++ b/config/prompt_templates/agent_system_prompt.yaml
@@ -434,8 +434,8 @@ templates:
1. Read the SKILL.md text in the user message and work out what has to be installed. Dependencies are often described in prose rather than a requirements file — read carefully.
2. Inspect the skill directory with `ls -la` before installing, so you know which of requirements.txt / pyproject.toml / package.json actually exist.
3. Install dependencies INTO THE SKILL DIRECTORY (see <isolation>), including on-demand extras (see <on_demand_dependencies>).
- 4. PROVE the imports resolve by running them (see <prove_it_runs>). Also identify and verify external CLI prerequisites, even for Markdown-only skills, following linked official setup guides when necessary. "Installed separately" does not mean no dependency.
- 5. Write the runtime prerequisite report requested in the user message. Record unresolved external setup or sandbox incompatibility as blockers; never claim readiness just because there are no package manifests.
+ 4. PROVE the imports resolve by running them (see <prove_it_runs>). Verify runtime prerequisites, including dependencies described only in documentation, and consult referenced official setup guides when necessary.
+ 5. Write the runtime prerequisite report requested in the user message using this skill's actual requirements and verification results. Record unresolved setup or execution-environment incompatibility as blockers.
6. Reply with a short summary: what you installed, where it went, and anything you had to change in the skill's own files.
</workflow>
diff --git a/frontend/src/components/SandboxSkillsPanel.vue b/frontend/src/components/SandboxSkillsPanel.vue
index 1d8425cb2..a1ca1210f 100644
--- a/frontend/src/components/SandboxSkillsPanel.vue
+++ b/frontend/src/components/SandboxSkillsPanel.vue
@@ -233,7 +233,7 @@
</div>
</div>
</section>
- <section v-if="hasTranscript(managedSkill)" class="skill-manage__section">
+ <section v-if="hasTranscript(managedSkill)" class="skill-manage__section skill-manage__section--transcript">
<div class="skill-manage__section-head">
<h4>{{ $t('settings.sandbox.skillTranscriptTitle') }}</h4>
<div v-if="managedSkill.status === 'installing'" class="skill-manage__progress">
@@ -1662,7 +1662,30 @@ onUnmounted(() => {
}
.sandbox-skills-panel--focused {
+ display: flex;
+ flex: 1;
min-height: 0;
+
+ > :deep(.t-loading__parent) {
+ display: flex;
+ flex: 1;
+ min-width: 0;
+ }
+
+ .skill-manage,
+ .skill-manage__section--transcript,
+ :deep(.skill-timeline) {
+ flex: 1;
+ min-width: 0;
+ }
+
+ :deep(.skill-timeline__guidance) {
+ // Include the drawer's 18px side padding and 16px bottom padding.
+ --skill-guidance-gutter: 30px;
+ --skill-guidance-bottom-gap: 16px;
+ margin-bottom: -12px;
+ padding-bottom: 12px;
+ }
}
.skill-header-uninstall {
@@ -2159,6 +2182,10 @@ onUnmounted(() => {
</style>
<style lang="less">
+.setting-drawer__body:has(> .sandbox-skills-panel--focused) {
+ min-height: 100%;
+}
+
.skill-transcript-popup,
.skill-env-popup {
z-index: 3200 !important;
diff --git a/frontend/src/components/SkillInstallTimeline.vue b/frontend/src/components/SkillInstallTimeline.vue
index 9aad02f3e..c791d1d74 100644
--- a/frontend/src/components/SkillInstallTimeline.vue
+++ b/frontend/src/components/SkillInstallTimeline.vue
@@ -1,47 +1,47 @@
<template>
<section class="skill-timeline" :class="{ 'skill-timeline--compact': compact }" :aria-busy="loading">
- <t-loading v-if="loading && messages.length === 0" size="small" />
- <p v-else-if="messages.length === 0" class="skill-timeline__empty">
- {{ live
- ? $t('settings.sandbox.skillTranscriptWaiting')
- : $t('settings.sandbox.skillTranscriptEmpty') }}
- </p>
- <template v-else>
- <div v-for="(msg, index) in messages" :key="msg.id || index" class="skill-timeline__turn">
- <pre v-if="msg.role === 'user'" class="skill-timeline__prompt">{{ msg.content }}</pre>
- <AgentStreamDisplay
- v-else
- :session="msg"
- :session-id="sessionId"
- :user-query="''"
- embedded-mode
- />
- </div>
- </template>
- <div class="skill-timeline__guidance">
+ <div class="skill-timeline__content">
+ <t-loading v-if="loading && messages.length === 0" size="small" />
+ <p v-else-if="messages.length === 0" class="skill-timeline__empty">
+ {{ live
+ ? $t('settings.sandbox.skillTranscriptWaiting')
+ : $t('settings.sandbox.skillTranscriptEmpty') }}
+ </p>
+ <template v-else>
+ <div v-for="(msg, index) in messages" :key="msg.id || index" class="skill-timeline__turn">
+ <pre v-if="msg.role === 'user'" class="skill-timeline__prompt">{{ msg.content }}</pre>
+ <AgentStreamDisplay
+ v-else
+ :session="msg"
+ :session-id="sessionId"
+ :user-query="''"
+ embedded-mode
+ />
+ </div>
+ </template>
<div v-for="item in guidance.messages" :key="item.id" class="skill-timeline__guidance-message">
<span>{{ $t(`settings.sandbox.skillGuidance.${item.status}`) }}</span>
<p>{{ item.content }}</p>
</div>
- <template v-if="live || canRetry">
- <t-textarea
- v-model="guidanceText"
- :placeholder="$t('settings.sandbox.skillGuidance.placeholder')"
- :maxlength="10000"
- :autosize="{ minRows: 2, maxRows: 6 }"
- :disabled="sendingGuidance"
- />
- <p v-if="guidanceError" role="alert" class="skill-timeline__guidance-error">{{ guidanceError }}</p>
- <div class="skill-timeline__guidance-actions">
- <span v-if="live && !guidance.accepting">{{ $t('settings.sandbox.skillGuidance.unavailable') }}</span>
- <t-button
- size="small"
- :loading="sendingGuidance"
- :disabled="!guidanceText.trim() || (live && !guidance.accepting)"
- @click="sendGuidance"
- >{{ $t(live ? 'settings.sandbox.skillGuidance.send' : 'settings.sandbox.skillGuidance.retry') }}</t-button>
- </div>
- </template>
+ </div>
+ <div v-if="live || canRetry" class="skill-timeline__guidance">
+ <t-textarea
+ v-model="guidanceText"
+ :placeholder="$t('settings.sandbox.skillGuidance.placeholder')"
+ :maxlength="10000"
+ :autosize="{ minRows: 2, maxRows: 6 }"
+ :disabled="sendingGuidance"
+ />
+ <p v-if="guidanceError" role="alert" class="skill-timeline__guidance-error">{{ guidanceError }}</p>
+ <div class="skill-timeline__guidance-actions">
+ <span v-if="live && !guidance.accepting">{{ $t('settings.sandbox.skillGuidance.unavailable') }}</span>
+ <t-button
+ size="small"
+ :loading="sendingGuidance"
+ :disabled="!guidanceText.trim() || (live && !guidance.accepting)"
+ @click="sendGuidance"
+ >{{ $t(live ? 'settings.sandbox.skillGuidance.send' : 'settings.sandbox.skillGuidance.retry') }}</t-button>
+ </div>
</div>
</section>
</template>
@@ -331,7 +331,32 @@ onUnmounted(stop)
</script>
<style scoped lang="less">
-.skill-timeline__guidance { margin-top: 12px; }
+.skill-timeline__content {
+ flex: 1;
+ min-width: 0;
+}
+
+.skill-timeline__guidance {
+ position: sticky;
+ bottom: 0;
+ z-index: 1;
+ flex-shrink: 0;
+ margin-top: 12px;
+ padding-top: 12px;
+ background: var(--td-bg-color-container, #fff);
+ border-top: 1px solid var(--td-component-stroke, #e7e7e7);
+
+ // Cover the timeline's padding too, so scrolling text cannot peek around
+ // the sticky composer. Its z-index keeps this backdrop above the transcript.
+ &::before {
+ content: '';
+ position: absolute;
+ inset: 0 calc(-1 * var(--skill-guidance-gutter, 12px)) calc(-1 * var(--skill-guidance-bottom-gap, 12px));
+ z-index: -1;
+ background: inherit;
+ pointer-events: none;
+ }
+}
.skill-timeline__guidance-message {
margin: 8px 0;
padding: 8px;
@@ -351,6 +376,8 @@ onUnmounted(stop)
.skill-timeline__guidance-error { color: var(--td-error-color); font-size: 12px; }
.skill-timeline {
+ display: flex;
+ flex-direction: column;
padding: 12px;
background: var(--td-bg-color-secondarycontainer, #f7f7f7);
border: 1px solid var(--td-component-stroke, #e7e7e7);
diff --git a/internal/application/service/tenant_skill_runtime_verify.go b/internal/application/service/tenant_skill_runtime_verify.go
index faaaa2d53..51d937d96 100644
--- a/internal/application/service/tenant_skill_runtime_verify.go
+++ b/internal/application/service/tenant_skill_runtime_verify.go
@@ -12,26 +12,24 @@ import (
)
const skillInstallRuntimeInstructions = `
-Runtime prerequisites and completion report (required even for Markdown-only skills):
-- No requirements.txt/package.json does NOT mean no dependencies. Identify external CLI binaries, system
- libraries, and external services/devices from SKILL.md, including its prerequisites and linked official
- setup documentation. Read those guides with shell tools when needed.
-- Documentation saying "installed separately" describes a prerequisite, not permission to skip it. Check
- availability and install missing CLI dependencies in this sandbox where supported. Put standalone
- binaries in <skill-dir>/.weknora/bin (on PATH when a session selects this skill); do not rely on root's
- ~/.local/bin or an export that only lasts one shell call. Use the explicit path during installation.
-- Verify required commands with --version/--help and the documented readiness check. A successful package
- download is not proof of readiness.
-- Assess compatibility with THIS remote sandbox. A browser extension/local daemon on the user's computer,
- local IPC/127.0.0.1, interactive login, or unavailable hardware may not be reachable here. Install what
- can be installed; report precisely what still requires user action or a different environment. Do not
- silently substitute a different tool or claim readiness.
-- With write_skill_file, create .weknora/install-report.json containing exactly:
- {"commands":["bsk"],"blockers":["Describe an unresolved external prerequisite here"]}
- commands lists every required runtime CLI (bare executable names, no arguments), including existing
- ones. blockers lists unresolved setup/compatibility requirements, never credentials. Use empty arrays
- only when there really are none. Do not put ordinary per-user API keys here; declare them in
- requirements.json instead.
+Runtime prerequisites and completion report (required for every skill):
+- Identify runtime prerequisites from the skill's documentation and manifests, including dependencies
+ described only in prose. Consult referenced official setup guides when needed.
+- Check availability and install missing dependencies supported by this sandbox within the installer
+ scope. Put standalone CLI binaries in <skill-dir>/.weknora/bin (on PATH when a session selects this
+ skill). Use the explicit path during installation so verification does not depend on temporary shell
+ configuration.
+- Verify required commands with documented, non-destructive checks. Assess whether required capabilities
+ are available in this execution environment and whether dependencies outside it are reachable. Report
+ unresolved setup or compatibility requirements precisely; do not silently substitute a different tool.
+- With write_skill_file, create .weknora/install-report.json as a JSON object with two required fields:
+ - commands: an array of strings listing every runtime CLI required by this skill, including those
+ already installed. Each entry must be a bare executable name without paths or arguments.
+ - blockers: an array of strings describing unresolved setup or compatibility requirements found
+ during verification.
+ Populate both arrays from this skill's actual requirements and verification results, without
+ placeholder entries. Use an empty array when there are no entries for that field. Never include
+ credentials; declare ordinary per-user API keys in .weknora/requirements.json instead of blockers.
- The server refuses missing/invalid reports, missing commands, and unresolved blockers. Do not remove a
required command or blocker merely to pass verification. Only remove a blocker after verifying it is
resolved.
diff --git a/internal/application/service/tenant_skill_runtime_verify_test.go b/internal/application/service/tenant_skill_runtime_verify_test.go
index 9bb88851d..a511f7a48 100644
--- a/internal/application/service/tenant_skill_runtime_verify_test.go
+++ b/internal/application/service/tenant_skill_runtime_verify_test.go
@@ -98,13 +98,27 @@ func TestRunInstallDoesNotSnapshotUnresolvedExternalPrerequisites(t *testing.T)
require.Len(t, fx.agentPrompts, 1, "an external setup blocker must not trigger pointless package retries")
}
-func TestInstallPromptRequiresExternalPrerequisites(t *testing.T) {
+func TestRuntimeReportPromptsDoNotPrescribeSkillSpecificValues(t *testing.T) {
fx := newInstallFixture(t)
- prompt := buildInstallPrompt(installSkillDir, fx.bundle, nil)
- for _, text := range []string{
- "No requirements.txt/package.json does NOT mean no dependencies",
- "installed separately", "install-report.json", "127.0.0.1", ".weknora/bin",
- } {
- require.Contains(t, strings.ToLower(prompt), strings.ToLower(text))
+ fx.bundle.Files = map[string][]byte{
+ "SKILL.md": []byte("Summarize supplied text. No external commands are required."),
+ }
+ prompts := map[string]string{
+ "install": buildInstallPrompt(installSkillDir, fx.bundle, nil),
+ "repair": buildRepairPrompt(installSkillDir, &skillVerificationError{
+ Language: "runtime prerequisites", Problems: []string{"Missing install-report.json"},
+ }),
+ }
+ for name, prompt := range prompts {
+ t.Run(name, func(t *testing.T) {
+ for _, field := range []string{".weknora/install-report.json", "commands:", "blockers:"} {
+ require.Contains(t, prompt, field)
+ }
+ for _, leakedExample := range []string{
+ "bsk", "browser extension", "127.0.0.1", "Describe an unresolved external prerequisite here",
+ } {
+ require.NotContains(t, strings.ToLower(prompt), strings.ToLower(leakedExample))
+ }
+ })
}
}