siclaw 0.1.0 → 0.1.2

package/skills/core/volcano-scheduler-logs/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: volcano-scheduler-logs
+description: >-
+  Retrieve and analyze Volcano scheduler logs.
+  Filter by keyword, time range, or pod name to debug scheduling decisions.
+---
+
+# Volcano Scheduler Logs
+
+Retrieve and analyze Volcano scheduler logs to understand scheduling decisions, failures, and performance issues.
+
+**Scope:** This skill is for **diagnosis only**. It retrieves logs for analysis but does not modify any cluster state.
+
+## Usage
+
+```bash
+bash skills/core/volcano-scheduler-logs/scripts/get-scheduler-logs.sh [options]
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `--keyword KEYWORD` | no | Filter logs by keyword (case-insensitive) |
+| `--pod POD` | no | Filter logs related to specific pod name |
+| `--since TIME` | no | Show logs newer than relative time (e.g., 10m, 1h) |
+| `--lines N` | no | Number of lines to show (default: 100) |
+| `--follow` | no | Stream logs in real-time (Ctrl+C to stop) |
+| `--previous` | no | Show logs from previous container instance (after restart) |
+
+## Examples
+
+Get recent scheduler logs:
+```bash
+bash skills/core/volcano-scheduler-logs/scripts/get-scheduler-logs.sh
+```
+
+Search for error messages:
+```bash
+bash skills/core/volcano-scheduler-logs/scripts/get-scheduler-logs.sh --keyword error
+```
+
+Get logs for a specific pod:
+```bash
+bash skills/core/volcano-scheduler-logs/scripts/get-scheduler-logs.sh --pod my-job-0
+```
+
+Get last 500 lines from the past hour:
+```bash
+bash skills/core/volcano-scheduler-logs/scripts/get-scheduler-logs.sh --since 1h --lines 500
+```
+
+Stream logs for gang scheduling issues:
+```bash
+bash skills/core/volcano-scheduler-logs/scripts/get-scheduler-logs.sh --keyword gang --follow
+```
+
+Check logs from previous scheduler instance (after crash/restart):
+```bash
+bash skills/core/volcano-scheduler-logs/scripts/get-scheduler-logs.sh --previous --lines 200
+```
+
+## Common Keywords for Filtering
+
+| Keyword | Use Case |
+|---------|----------|
+| `error` | Find error messages and failures |
+| `FailedScheduling` | Scheduling failures |
+| `allocate` | Resource allocation attempts |
+| `gang` | Gang scheduling decisions |
+| `minMember` | MinMember constraint issues |
+| `preempt` | Preemption events |
+| `reclaim` | Resource reclamation |
+| `enqueue` | Queue admission decisions |
+| `bind` | Pod binding attempts |
+| `queue` | Queue-related decisions |
+| `proportion` | Proportion plugin decisions |
+| `priority` | Priority-related decisions |
+
+## Understanding Scheduler Logs
+
+### Log Format
+
+Volcano scheduler logs typically follow this format:
+```
+I0102 15:04:05.123456       1 scheduler.go:123] Starting scheduling session
+I0102 15:04:05.234567       1 allocate.go:456] Try to allocate resources for Job <namespace>/<job-name>
+E0102 15:04:05.345678       1 gang.go:789] Failed to schedule pod <pod-name>: minMember not satisfied
+```
+
+**Log levels:**
+- `I` - Info: Normal operation information
+- `W` - Warning: Unusual but non-fatal conditions
+- `E` - Error: Failures and errors
+- `F` - Fatal: Critical errors causing shutdown
+
+### Common Log Patterns
+
+#### Session Start
+```
+Starting scheduling session
+Starting scheduling loop
+```
+- Indicates scheduler is processing a new batch of pending pods
+
+#### Enqueue Decisions
+```
+Try to enqueue pod group
+PodGroup <name> is enqueued
+PodGroup <name> is pending
+```
+- Shows whether pod groups are admitted to the queue
+
+#### Allocation Attempts
+```
+Try to allocate resources for Job
+Try to allocate for task
+```
+- Shows scheduling attempts for specific jobs/pods
+
+#### Gang Scheduling
+```
+minMember not satisfied
+gang member not ready
+Waiting for gang members
+```
+- Indicates Gang constraint preventing scheduling
+
+#### Resource Shortage
+```
+Insufficient cpu
+Insufficient memory
+0 nodes are available
+```
+- Indicates resource constraint preventing scheduling
+
+#### Preemption
+```
+Preempting pods
+Found victim pods
+```
+- Shows preemption decisions for high-priority workloads
+
+#### Reclaim
+```
+Try to reclaim resources
+Reclaiming resources from queue
+```
+- Shows resource reclamation between queues
+
+## Diagnostic Use Cases
+
+### Case 1: Pod Stuck in Pending
+
+Find relevant scheduler decisions:
+```bash
+bash skills/core/volcano-scheduler-logs/scripts/get-scheduler-logs.sh --pod <pod-name> --since 30m
+```
+
+Look for:
+- `FailedScheduling` events
+- `minMember not satisfied`
+- `Insufficient` resource messages
+- `enqueue` decisions (is the PodGroup being admitted?)
+
+### Case 2: Gang Scheduling Issues
+
+Check Gang plugin behavior:
+```bash
+bash skills/core/volcano-scheduler-logs/scripts/get-scheduler-logs.sh --keyword gang --since 1h
+```
+
+Look for:
+- `minMember` related messages
+- Gang constraint validation
+- Comparison of running vs required members
+
+### Case 3: Queue Resource Issues
+
+Check proportion and reclaim decisions:
+```bash
+bash skills/core/volcano-scheduler-logs/scripts/get-scheduler-logs.sh --keyword "reclaim\|proportion" --since 30m
+```
+
+Look for:
+- Queue resource calculations
+- Reclaim triggers
+- Over-commit handling
+
+### Case 4: Scheduler Performance
+
+Check for scheduling delays:
+```bash
+bash skills/core/volcano-scheduler-logs/scripts/get-scheduler-logs.sh --lines 500 | grep -E "(Starting|Finished) scheduling"
+```
+
+Look for:
+- Long gaps between "Starting" and "Finished"
+- High frequency of scheduling loops
+- Errors causing retries
+
+### Case 5: Preemption Analysis
+
+Check preemption decisions:
+```bash
+bash skills/core/volcano-scheduler-logs/scripts/get-scheduler-logs.sh --keyword preempt --since 1h
+```
+
+Look for:
+- Which pods are being preempted
+- Priority comparisons
+- Preemption success/failure
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `VOLCANO_SCHEDULER_NS` | `volcano-system` | Scheduler namespace |
+| `VOLCANO_SCHEDULER_LABEL` | `app=volcano-scheduler` | Label selector for scheduler pods |
+
+## Limitations
+
+1. **Log retention:** Logs may be rotated based on cluster configuration
+2. **Multi-scheduler:** If running multiple schedulers, logs will be interleaved
+3. **Log level:** Default log level may not show all debug information
+4. **Previous logs:** `--previous` only works if the container has restarted
+
+## Tips for Effective Log Analysis
+
+1. **Use time ranges:** Narrow down with `--since` to focus on recent issues
+2. **Combine keywords:** Search for `error\|Failed\|failed` to catch all failures
+3. **Check pod context:** Always include `--pod` when investigating specific pods
+4. **Look for patterns:** Repeating errors may indicate systemic issues
+5. **Correlate with events:** Compare with `kubectl get events` timestamps
+
+## See Also
+
+- `volcano-diagnose-pod` - Diagnose individual pod issues
+- `volcano-gang-scheduling` - Gang scheduling specific diagnosis
+- `volcano-queue-diagnose` - Queue resource analysis
+- `volcano-resource-insufficient` - Resource shortage diagnosis

package/skills/core/volcano-scheduler-logs/scripts/get-scheduler-logs.sh

@@ -0,0 +1,159 @@
+#!/bin/bash
+# Retrieve and analyze Volcano scheduler logs.
+# This script performs read-only operations using kubectl.
+set -euo pipefail
+
+show_help() {
+  cat <<EOF
+Usage: $0 [options]
+
+Retrieve and analyze Volcano scheduler logs.
+Filter by keyword, time range, or pod name to debug scheduling decisions.
+
+Options:
+  --keyword KEYWORD   Filter logs by keyword (case-insensitive)
+  --pod POD           Filter logs related to specific pod name
+  --since TIME        Show logs newer than relative time (e.g., 10m, 1h, 1d)
+  --lines N           Number of lines to show (default: 100)
+  --follow            Stream logs in real-time (Ctrl+C to stop)
+  --previous          Show logs from previous container instance
+  -h, --help          Show this help message
+
+Environment:
+  VOLCANO_SCHEDULER_NS      Scheduler namespace (default: volcano-system)
+  VOLCANO_SCHEDULER_LABEL   Pod label selector (default: app=volcano-scheduler)
+
+Examples:
+  $0 --keyword error                    # Search for errors
+  $0 --pod my-job-0 --since 30m        # Logs for pod in last 30 min
+  $0 --lines 500 --since 1h            # Last 500 lines from past hour
+  $0 --keyword gang --follow           # Stream gang scheduling logs
+  $0 --previous --lines 200            # Logs from previous scheduler instance
+EOF
+  exit 0
+}
+
+# Parse arguments
+KEYWORD=""
+POD=""
+SINCE=""
+LINES=100
+FOLLOW=false
+PREVIOUS=false
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    -h|--help) show_help ;;
+    --keyword) KEYWORD="$2"; shift 2 ;;
+    --pod) POD="$2"; shift 2 ;;
+    --since) SINCE="$2"; shift 2 ;;
+    --lines) LINES="$2"; shift 2 ;;
+    --follow) FOLLOW=true; shift ;;
+    --previous) PREVIOUS=true; shift ;;
+    *) echo "Unknown option: $1. Use --help for usage." >&2; exit 1 ;;
+  esac
+done
+
+# Validate arguments
+if [[ "$FOLLOW" == "true" && -n "$SINCE" ]]; then
+  echo "Error: --follow and --since cannot be used together" >&2
+  exit 1
+fi
+
+if [[ "$FOLLOW" == "true" && -n "$SINCE" && "$LINES" != "100" ]]; then
+  echo "Warning: --follow ignores --lines, streaming from now" >&2
+fi
+
+# Environment settings
+SCHEDULER_NS="${VOLCANO_SCHEDULER_NS:-volcano-system}"
+SCHEDULER_LABEL="${VOLCANO_SCHEDULER_LABEL:-app=volcano-scheduler}"
+
+echo "=== Volcano Scheduler Logs ==="
+echo "Namespace: $SCHEDULER_NS"
+echo "Label: $SCHEDULER_LABEL"
+[[ -n "$KEYWORD" ]] && echo "Keyword filter: $KEYWORD"
+[[ -n "$POD" ]] && echo "Pod filter: $POD"
+[[ -n "$SINCE" ]] && echo "Time range: $SINCE"
+echo "Lines: $LINES"
+[[ "$PREVIOUS" == "true" ]] && echo "Previous instance: yes"
+echo
+
+# Check if scheduler pod exists
+if ! kubectl get pods -n "$SCHEDULER_NS" -l "$SCHEDULER_LABEL" &>/dev/null; then
+  echo "Error: No scheduler pods found in namespace '$SCHEDULER_NS' with label '$SCHEDULER_LABEL'" >&2
+  echo "Available pods in $SCHEDULER_NS:" >&2
+  kubectl get pods -n "$SCHEDULER_NS" 2>/dev/null | head -10 >&2 || echo "  (failed to list pods)" >&2
+  exit 1
+fi
+
+# Get scheduler pod name
+SCHEDULER_POD=$(kubectl get pods -n "$SCHEDULER_NS" -l "$SCHEDULER_LABEL" -o jsonpath='{.items[0].metadata.name}' 2>/dev/null || echo "")
+
+if [[ -z "$SCHEDULER_POD" ]]; then
+  echo "Error: Could not determine scheduler pod name" >&2
+  exit 1
+fi
+
+echo "Scheduler Pod: $SCHEDULER_POD"
+echo
+
+# Build kubectl logs command
+LOG_CMD="kubectl logs -n $SCHEDULER_NS $SCHEDULER_POD"
+
+# Add options
+[[ "$FOLLOW" == "true" ]] && LOG_CMD="$LOG_CMD --follow"
+[[ "$PREVIOUS" == "true" ]] && LOG_CMD="$LOG_CMD --previous"
+[[ -n "$SINCE" ]] && LOG_CMD="$LOG_CMD --since=$SINCE"
+[[ "$FOLLOW" == "false" ]] && LOG_CMD="$LOG_CMD --tail=$LINES"
+
+# Execute command with optional filtering
+echo "Executing: $LOG_CMD"
+echo "----------------------------------------"
+echo
+
+# Build filter pattern
+FILTER_PATTERN=""
+
+# If both keyword and pod are specified, combine them
+if [[ -n "$KEYWORD" && -n "$POD" ]]; then
+  FILTER_PATTERN="$KEYWORD|$POD"
+elif [[ -n "$KEYWORD" ]]; then
+  FILTER_PATTERN="$KEYWORD"
+elif [[ -n "$POD" ]]; then
+  FILTER_PATTERN="$POD"
+fi
+
+# Execute and filter
+if [[ -n "$FILTER_PATTERN" ]]; then
+  # Use case-insensitive grep for filtering
+  if [[ "$FOLLOW" == "true" ]]; then
+    # For follow mode, we need to filter in real-time
+    $LOG_CMD 2>&1 | grep -iE "$FILTER_PATTERN" || true
+  else
+    # For non-follow mode, filter after getting logs
+    $LOG_CMD 2>&1 | grep -iE "$FILTER_PATTERN" || {
+      echo "(No log lines matched the filter pattern: $FILTER_PATTERN)"
+    }
+  fi
+else
+  # No filtering, show all logs
+  $LOG_CMD 2>&1 || {
+    echo "Error: Failed to retrieve logs" >&2
+    exit 1
+  }
+fi
+
+echo
+
+# If not following, show some helpful hints
+if [[ "$FOLLOW" == "false" ]]; then
+  echo "----------------------------------------"
+  echo "Hints:"
+  echo "  - Use --follow to stream logs in real-time"
+  echo "  - Use --since 30m for recent logs only"
+  echo "  - Use --previous if scheduler recently restarted"
+  echo "  - Common keywords: error, FailedScheduling, gang, preempt, reclaim"
+fi
+
+echo
+echo "=== Log Retrieval Complete ==="

package/skills/platform/create-skill/SKILL.md

@@ -15,6 +15,32 @@ Use this skill when the user asks you to:
 - Create a new skill for a specific operational procedure
 - Save a diagnosis workflow as a skill
 
+## Duplicate / Overlap Check — Do This FIRST
+
+**Before creating any skill, check whether an existing skill already covers the same functionality.** Consult the `<available_skills>` index in your context.
+
+- **Functional overlap found**: If an existing builtin, team, or personal skill solves the same problem (even with a different name), DO NOT silently create a new one. Instead:
+  1. Tell the user which existing skill overlaps and what it does.
+  2. Ask if they want to: (a) use the existing skill as-is, (b) fork it with `fork_skill` to make a customized personal copy, or (c) still create a brand-new separate skill.
+  3. Only proceed with `create_skill` if the user explicitly chooses option (c).
+- **Why this matters**: Duplicate skills with similar functionality confuse the model — it cannot reliably choose between two skills that do the same thing. One well-maintained skill is always better than two overlapping ones.
+- To fork a builtin or team skill into a personal copy, use `fork_skill`.
+
+## Environments and Approval Workflow
+
+Skills go through a review workflow that behaves differently per environment:
+
+| Environment | Behavior |
+|-------------|----------|
+| **Dev / Test** | Newly created skills (draft status) are immediately visible and usable. You can test them right away. |
+| **Production** | Only **approved** skill versions are visible and usable. Draft and pending skills do NOT appear. |
+
+- After creating a skill, it starts in **draft** status.
+- Skills with scripts must be **submitted for review** and **approved by an admin** before they become active in production.
+- Skills without scripts (pure guidance) also start as draft but can be submitted and approved more quickly.
+- **After creating a skill in production context**: inform the user that it is pending review and will not be available in production until approved. Suggest testing in the dev/test environment first.
+- **Do NOT attempt to test or run a newly created skill in production** — it will not be found.
+
 ## Skill Structure
 
 A skill is a directory under `skills/` containing:
@@ -171,9 +197,12 @@ node_script: node="node-1", skill="node-logs", script="get-node-logs.sh", args="
 
 ## How to Create a Skill
 
-### Step 0: Check Completeness — Ask Before You Build
+### Step 0: Check for Duplicates and Completeness
+
+Before calling `create_skill`:
 
-Before calling `create_skill`, review what you know and identify gaps. A good skill needs **all** of the following. If any are missing or vague, ask the user to clarify before proceeding:
+1. **Check for existing skills** — consult the `<available_skills>` index. If an existing skill covers the same functionality, discuss with the user: reuse as-is, fork with `fork_skill`, or create new.
+2. **Verify completeness** — a good skill needs **all** of the following. If any are missing, ask the user:
 
 | Required Info | What to check | Example question to ask |
 |---|---|---|
@@ -205,7 +234,8 @@ create_skill({
   description: "Find OOMKilled pods and analyze memory usage",
   type: "Monitoring",
   specs: "---\nname: check-pod-oom\n...",
-  scripts: [{ name: "check-oom.sh", content: "#!/bin/bash\n..." }]
+  scripts: [{ name: "check-oom.sh", content: "#!/bin/bash\n..." }],
+  labels: ["monitoring", "memory"]
 })
 ```
 
@@ -283,6 +313,8 @@ pod_netns_script: pod="<pod>", namespace="<ns>", skill="pod-ping-gateway", scrip
 - **`## Parameters` table**: list required and optional parameters with descriptions
 - **Actionable examples**: show multiple real tool invocations with realistic parameters
 - **Category selection**: choose from Monitoring, Network, Security, Database, Core, Utility, Automation, Custom
+- **Labels**: add relevant labels (e.g. `['gpu', 'network', 'monitoring']`) for discoverability
 - **Scripts are optional**: simple skills that just guide the bot's kubectl usage don't need scripts
 - **One concern per skill**: keep skills focused on a single task
+- **No duplicates**: always check for existing skills first; fork rather than recreate
 - **User scripts by name**: when referencing uploaded scripts, just pass `{name: "file.sh"}` without content

package/skills/platform/manage-skill/SKILL.md

@@ -9,15 +9,22 @@ description: >-
 
 ## When to Use
 
-When the user requests to create, update, edit, enable, or disable a Skill.
+When the user requests to create, update, edit, enable, or disable a Skill in a **Channel** conversation (where skill management tools are not available).
 
 ## Instructions
 
 Skill creation, updates, and management should be done through the Siclaw Web page.
 
 On the Web page, you can:
-- Create and edit Skills
+- Create and edit Skills (with live preview)
+- Fork builtin or team skills into personal copies
+- Submit skills for review and approval
 - Enable or disable Skills
 - View Skill execution history
 
 Inform the user of this directly — no further action is required.
+
+## Environments
+
+- **Dev / Test environment**: newly created or updated skills are immediately usable for testing.
+- **Production environment**: only approved skill versions are available. Skills must go through admin review before they appear in production.

package/skills/platform/update-skill/SKILL.md

@@ -2,27 +2,37 @@
 name: update-skill
 description: >-
   Procedure for modifying, updating, or fixing an existing Siclaw skill.
-  Skills are on a read-only filesystem — use the update_skill tool,
-  never edit files directly.
+  Use the update_skill tool — never edit skill files directly.
 ---
 
 # Update Skill
 
 ## When to Use
 
-When the user's message contains `[Editing Skill: <name> (id:<id>)]` followed by the current skill content, or when the user asks to modify/update/fix an existing skill.
+When the user's message contains `[Skill: <name>]` (UI skill editing context), or when the user asks to modify/update/fix an existing skill.
+
+## Environments and Approval Workflow
+
+| Environment | Behavior |
+|-------------|----------|
+| **Dev / Test** | Updated content (working copy) is immediately visible and testable. |
+| **Production** | Only the **approved** version is active. Updates enter a staged review state; the old version remains in use until the new version is approved by an admin. |
+
+- When scripts are changed, the update enters a **staged review** state.
+- The **old version** of the skill remains usable in production during review.
+- In dev/test, the working copy is available immediately for testing.
 
 ## How to Update
 
 Call the `update_skill` tool (NOT `create_skill`) with the skill ID and the complete updated definition.
 
-**Do NOT use `read`, `edit`, `write`, or `bash` on files under `/mnt/skills/` — the filesystem is read-only.**
+**Skill directories are read-only. All skill modifications must go through skill management tools (create_skill, update_skill, fork_skill).**
 
 ### Tool Call Format
 
 ```
 update_skill({
-  id: "<skill-id>",                // Required — from [Editing Skill: ... (id:<id>)]
+  id: "<skill-id>",                // From [Skill: ...] context, or the skill's kebab-case name
   name: "skill-name",              // Keep original name unless user wants rename
   description: "What the skill does",
   type: "Monitoring",
@@ -31,7 +41,8 @@ update_skill({
     { name: "run.sh", content: "#!/bin/bash\n..." },   // Changed: provide full content
     { name: "check.sh" }                                // Unchanged: name only
     // Omitted scripts are deleted
-  ]
+  ],
+  labels: ["monitoring", "memory"] // Optional labels/tags
 })
 ```