skill-authoring

Name: skill-authoring
Author: scitix

Other Community

Repo stars 198
Author repo siclaw

Interpretation is structured for decision-making; original keeps the upstream SKILL.md unchanged.

Decide Fit First

Core job: >- Read this guide before creating a new skill or improving an existing one. name: <kebab-case-name> One-line summary. Mention t…
Best fit: Use it when the task has reusable inputs, steps, and validation criteria rather than a one-off answer.
Avoid forcing it: If the source lacks commands, platform support, or external-service evidence, keep those fields unknown instead of guessing.

Design Intent

Structure: The skill is organized around “SKILL.md Format”, “Purpose”, “Tool”, “Parameters”, showing how the author expects the agent to judge fit, collect context, and produce verifiable output.
Trigger evidence: Prioritize the author’s wording around when to use it, what context to collect, and what output shape to produce.
Evidence boundary: Author text states facts, repository files prove commands and paths, and Fluxly only adds fit, limits, and usage judgment.

How To Use It

Inputs: Provide target material, scope, expected result, forbidden changes, and validation method.
Invocation: Name skill-authoring directly; if the source includes slash commands, start with the command and then add task context.
Validation: Start small and check whether the result follows “SKILL.md Format / Purpose / Tool” before expanding.

Boundaries And Review

Dependencies: It usually needs no extra API key, so start with a small validation task.
Permissions: Declared permissions include read / write / shell-exec; ask the agent to state file, command, and rollback boundaries before acting.
Quality bar: A useful result names the deliverable, evidence, and next action. Generic prose means the task needs tighter context.

Skill Authoring Guide

Read this guide before creating a new skill or improving an existing one.

SKILL.md Format

---
name: <kebab-case-name>
description: >-
  One-line summary. Mention the execution tool if the skill uses scripts.
---

Followed by markdown body:

# <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

Fluxly profile Author and license come from source; runtime, permissions, and network are Fluxly detections or estimates

Fluxly category: 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
Author / version / license: @scitix · no license declared
Fluxly token estimate: Lean
Fluxly setup estimate: Guided setup
External API key: No requirement detected
Detected OS requirements: macOS · Linux · Windows
Runtime requirements: Node.js
Detected file/system behavior: Read-only
Write / modify
Shell exec
Detected network behavior: Local-only
Install commands: None (reference only)

Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.

Heads up: 未限定 allowed-tools，默认拥有全部工具权限。

Output preview skill-authoring-scitix.preview

The current SKILL.md does not define a fixed output example.

SKILL.md SKILL.md

# 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

…

Evidence boundary and execution chain

Author text anchors workflow facts; Fluxly only indexes current sections, terms, files, and commands.

sections -> SKILL.md Format → Purpose → Tool → Parameters → Procedure → Examples
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> · localscript · nodescript · podscript · netns · resolvepodnetns
body sha256 -> e7cf0f672919