skill authoring
- Repo stars 198
- Author repo siclaw
- Domain
- Other
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @scitix · no license declared
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- macOS · Linux · Windows
- Runtime requirements
- Node.js
- Detected file/system behavior
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# Skill Authoring Guide
Read this guide before creating a new skill or improving an existing one.
## SKILL.md Format
```yaml
---
name: <kebab-case-name>
description: >-
One-line summary. Mention the execution tool if the skill uses scripts.
---
```
Followed by markdown body:
```markdown
# <Title>
## Purpose
What problem this skill solves and when to use it.
## Tool
<execution tool invocation — required for script-based skills>
Example: local_script: skill="check-pod-oom", script="check.sh", args="<ns> <pod>"
## Parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `<arg1>` | Yes | ... |
## Procedure
Step-by-step actions with concrete commands.
## Examples
Concrete tool invocations with realistic parameters.
```
## Script Execution Modes
| Tool | Runs where | When to use |
|------|-----------|-------------|
| `local_script` | AgentBox (local) | kubectl commands from outside the cluster — **most common** |
| `node_script` | K8s node (host) | Needs host tools, /proc, /sys, devices, nsenter |
| `pod_script` | Inside a pod | Diagnostics inside a running container |
| `node_script` + `netns` | Node + pod's network ns | Host tools + pod's network view (call `resolve_pod_netns` first) |
## Best Practices
- **One skill, one purpose** — don't make Swiss army knives
- **Script over inline commands** — if the procedure has more than 3 steps, write a script
- **Idempotent and read-only** — skills are for diagnosis, not remediation
- **Description is critical** — the agent uses it to decide whether to use this skill
- **Concrete examples** — at least 2 examples with realistic parameters
- **Explain expected output** — describe what normal vs abnormal output looks like
- **Severity thresholds** — when checking error counters, give thresholds so the agent can judge
## Common Mistakes
- **Too much raw output** — dump kubectl describe without filtering. Grep for relevant lines
- **Missing Tool section** — without it, the agent doesn't know which execution tool to use
- **Wrong execution mode** — using `local_script` for host-level tools (use `node_script`)
- **Hardcoded values** — node names, namespaces should be parameters
- **No severity guidance** — e.g., CRC errors: 0 = normal, 1-100 = minor, >1000 = critical
Sections and files
Listed in source order.
sections -> SKILL.md Format → Script Execution Modes → Best Practices → Common Mistakes
terms -> most common · One skill, one purpose · Script over inline commands · Idempotent and read-only · Description is critical · Concrete examples · Explain expected output · Severity thresholds
files/cmd -> <arg1> · local_script · node_script · pod_script · netns · resolve_pod_netns
body sha256 -> e7cf0f672919
SKILL.md Format
Followed by markdown body:
Script Execution Modes
Tool · Runs where · When to use
local_script· AgentBox (local) · kubectl commands from outside the cluster — most commonnode_script· K8s node (host) · Needs host tools, /proc, /sys, devices, nsenterpod_script· Inside a pod · Diagnostics inside a running containernode_script+netns· Node + pod's network ns · Host tools + pod's network view (callresolve_pod_netnsfirst)Best Practices
One skill, one purpose — don't make Swiss army knives Script over inline commands — if the procedure has more than 3 steps, write a script Idempotent and read-only — skills are for diagnosis, not remediation Description is critical — the agent uses it to decide whether to use this skill Concrete examples — at least 2 examples with realistic parameters
Common Mistakes
Too much raw output — dump kubectl describe without filtering. Grep for relevant lines Missing Tool section — without it, the agent doesn't know which execution tool to use Wrong execution mode — using
local_scriptfor host-level tools (usenode_script) Hardcoded values — node names, namespaces should be parameters No severity guidance — e.g., CRC errors: 0 = normal, 1-100 = minor, >1000 = critical