Skill: kklouzal/kubernetes-encyclopedia (version 1.0.0)

--- name: kubernetes-encyclopedia description: >- Kubernetes documentation-first workflow for Kubernetes-specific questions, troubleshooting, command planning, cluster operations, workload/resource behavior, networking, storage, scheduling, security, and diagnostics. Use when the request is clearly about Kubernetes itself: the `kubectl` CLI, Kubernetes API objects, pods, deployments, services, ingress, config maps, secrets, volumes, nodes, scheduling, RBAC, controllers, CRDs, Helm-free core Kubernetes behavior, or cluster/runtime behavior where Kubernetes- specific semantics matter. Do not use for generic Linux administration, generic container theory, generic cloud architecture, or Docker-only questions unless the Kubernetes layer is specifically what is being discussed or debugged. metadata: {"openclaw":{"emoji":"☸️","homepage":"https://kubernetes.io/docs/home/"}} --- # Kubernetes Encyclopedia ## Overview Use a docs-first workflow for Kubernetes work. Prefer the official Kubernetes documentation at `https://kubernetes.io/docs/home/`, consult cached local copies under `.Kubernetes-Encyclopedia/` before re-fetching, and record useful official-doc excerpts plus environment-specific operational learnings so future work gets faster and safer. This skill is for the **Kubernetes API/control-plane/cluster layer**. It should trigger for real Kubernetes behavior, configuration, workload/resource, and operational questions — not for generic Linux admin work, generic container theory, or Docker-only questions where Kubernetes-specific semantics are not the real issue. ## Workflow 1. **Classify the task** - Decide whether the task is a Kubernetes question, troubleshooting task, command-planning task, resource review, cluster review, or live operational task. - Use this skill when the request is specifically about Kubernetes product behavior, `kubectl` semantics, API resource behavior, workload lifecycle, cluster networking/storage/scheduling/security behavior, or Kubernetes-specific operational details. - Do not use this skill for generic shell work, generic Linux admin, generic container theory, or Docker-only questions unless the Kubernetes layer is specifically in play. 2. **Check local cache first** - Use `.Kubernetes-Encyclopedia/` as the local knowledge/cache root. - Check these locations first when relevant: - `.Kubernetes-Encyclopedia/docs/kubernetes.io/docs/...` - `.Kubernetes-Encyclopedia/notes/components/...` - `.Kubernetes-Encyclopedia/notes/patterns/...` - `.Kubernetes-Encyclopedia/inventory/...` - If a cached page or note already answers the question well enough, use it. 3. **Consult official Kubernetes docs before answering or touching the system** - Before answering direct or indirect Kubernetes questions that depend on command syntax, resource semantics, controller behavior, feature boundaries, configuration semantics, cluster behavior, or version-sensitive details, consult the official docs unless the answer is already well-supported by the local cache. - Before performing direct Kubernetes CLI or configuration work, consult the relevant docs first when: - the exact resource or command path matters - scheduling/networking/storage/security semantics are easy to misremember - the action could affect workloads, nodes, access, traffic, storage, policy, or cluster reachability - Do not improvise high-impact Kubernetes commands or manifest changes from memory when the docs are easy to check. 4. **Cache consulted docs locally** - When you consult a Kubernetes docs page, save a normalized markdown/text cache copy under `.Kubernetes-Encyclopedia/docs/kubernetes.io/docs/...`. - Mirror the official docs path structure as much as practical. - Cache only pages actually consulted; do not try to mirror the whole docs site eagerly. - Use `scripts/cache_doc.py` when appropriate. 5. **Separate official documentation from local observations** - Store official-doc-derived material under `.Kubernetes-Encyclopedia/docs/...`. - Store environment-specific operational knowledge under: - `.Kubernetes-Encyclopedia/notes/components/` - `.Kubernetes-Encyclopedia/notes/patterns/` - `.Kubernetes-Encyclopedia/inventory/` - Distinguish clearly between: - official documented behavior - observed local configuration/state - inferred best-practice guidance 6. **Record useful local learnings** - After useful live work, save durable notes such as: - cluster-specific topology and access conventions - recurring workload/debugging patterns - ingress/network-policy/storage-class gotchas - scheduling/RBAC/manifest conventions - safe/unsafe operational boundaries for the environment - Prefer concise durable notes over re-learning the same Kubernetes details later. ## Live Work Rules - Treat official Kubernetes docs lookup as the default preflight for non-trivial Kubernetes work. - Prefer read/inspect first when entering a Kubernetes area you have not recently reviewed. - Treat namespace-wide changes, workload rollouts, storage changes, ingress/service exposure, RBAC/policy changes, and node/control-plane touching operations as high-sensitivity areas. - When uncertainty remains after checking cache + docs, say so and avoid bluffing. - When answering a question, mention when useful whether the answer comes from cached official docs, a fresh official docs lookup, or live observed environment state. ## Data Root Use this workspace-local root for cache and notes: - `.Kubernetes-Encyclopedia/` Expected structure: - `.Kubernetes-Encyclopedia/docs/kubernetes.io/docs/...` - `.Kubernetes-Encyclopedia/notes/components/...` - `.Kubernetes-Encyclopedia/notes/patterns/...` - `.Kubernetes-Encyclopedia/inventory/...` Use `scripts/init_workspace.py` to create or repair the expected directory structure. ## Note Destinations - Component-specific observations → `.Kubernetes-Encyclopedia/notes/components/<component-name>.md` - Reusable Kubernetes patterns/gotchas → `.Kubernetes-Encyclopedia/notes/patterns/<topic>.md` - Environment-wide deployment/access info → `.Kubernetes-Encyclopedia/inventory/*.md` - Cached official docs → `.Kubernetes-Encyclopedia/docs/kubernetes.io/docs/...` ## Secrets / Sensitive Data - Do not store plaintext credentials, API keys, session tokens, private URLs, recovery codes, kubeconfigs, client certificates, bearer tokens, or other secrets in the encyclopedia notes/inventory tree. - If a note needs to mention access details, keep it high-level and redact or omit secret material. - Treat these workspace notes as operational memory, not as a secrets vault. ## Resources - `scripts/init_workspace.py` — create or repair the `.Kubernetes-Encyclopedia/` directory tree. - `scripts/cache_doc.py` — fetch and cache a consulted official Kubernetes docs page under `.Kubernetes-Encyclopedia/docs/...`. - `references/workflow.md` — detailed operating workflow and evidence-handling rules. - `references/cache-layout.md` — canonical `.Kubernetes-Encyclopedia/` directory structure. - `references/topic-map.md` — useful Kubernetes topic groupings for faster doc lookup. ## Good Outcomes - Answer a Kubernetes question using cached or freshly checked official docs instead of guesswork. - Inspect a live Kubernetes environment after checking the relevant docs and record any new local operational knowledge. - Build a growing local Kubernetes knowledge cache that makes later work faster, safer, and more grounded. - Turn one-off Kubernetes discoveries into durable notes so future work does not rediscover them from scratch. ## Avoid - Answering Kubernetes-specific questions purely from memory when docs are easy to consult. - Treating local observed behavior as if it were guaranteed official documented behavior. - Dumping large amounts of low-value docs into the workspace without a reason. - Writing component-specific observations into the official-doc cache tree. - Making high-impact live changes before checking the relevant docs when exact behavior matters.

path: references/cache-layout.md
content: # `.Kubernetes-Encyclopedia/` Cache Layout

Use this directory as the workspace-local data root for the skill.

## Directory tree

```text
.Kubernetes-Encyclopedia/
  docs/
    kubernetes.io/
      docs/
        ... cached official docs pages ...
  notes/
    components/
      ... per-component notes ...
    patterns/
      ... reusable Kubernetes notes ...
  inventory/
    access.md
    topology.md
    doc-index.md
```

## Placement rules

### `docs/`
Store cached copies of official Kubernetes docs here.

Mirror the official docs path as much as practical.
Example:

```text
https://kubernetes.io/docs/concepts/workloads/controllers/deployment/
->
.Kubernetes-Encyclopedia/docs/kubernetes.io/docs/concepts/workloads/controllers/deployment/index.md
```

### `notes/components/`
Store environment-specific component notes here.

Suggested filenames:
- `control-plane.md`
- `nodes.md`
- `ingress.md`
- `storage.md`
- `rbac.md`

### `notes/patterns/`
Store reusable operational notes here.

Examples:
- `rollout-debugging.md`
- `service-vs-ingress.md`
- `rbac-review-gotchas.md`
- `stateful-workload-ops.md`

### `inventory/`
Store environment-wide inventories here.

Suggested files:
- `access.md`
- `topology.md`
- `doc-index.md`

## Cache philosophy

Do not mirror the whole docs site eagerly.
Cache only the pages you actually consulted and expect to be useful later.


path: references/topic-map.md
content: # Kubernetes Topic Map

Use this as a quick orientation aid when deciding what docs to look up.

## Core areas

- Kubernetes API objects and resource semantics
- `kubectl` commands and operational workflows
- Pods / deployments / daemonsets / statefulsets / jobs
- Services / ingress / DNS / traffic exposure
- ConfigMaps / Secrets / environment injection
- Volumes / persistent storage / storage classes
- Nodes / scheduling / taints / affinity / disruption behavior
- RBAC / policy / service accounts / security context
- Controllers / CRDs / cluster operations

## Typical lookup prompts

When the task is about...

### Workloads / resource semantics
Look for docs covering:
- pods
- deployments
- daemonsets
- statefulsets
- jobs/cronjobs
- rollout behavior

### Networking / exposure
Look for docs covering:
- services
- ingress
- DNS/service discovery
- network policy
- traffic exposure behavior

### Storage / config
Look for docs covering:
- volumes
- persistent volumes / claims
- storage classes
- configmaps
- secrets

### Scheduling / nodes
Look for docs covering:
- scheduling
- affinity / anti-affinity
- taints / tolerations
- node selection
- disruption and eviction behavior

### Security / access
Look for docs covering:
- RBAC
- service accounts
- pod security context
- admission/policy when relevant

### Operations / troubleshooting
Look for docs covering:
- kubectl reference
- rollout/debugging flows
- controller behavior
- cluster administration concepts when relevant


path: references/workflow.md
content: # Kubernetes Encyclopedia Workflow

## Core stance

Use official Kubernetes docs plus local observed state together.

Default order:
1. check `.Kubernetes-Encyclopedia/` cache/notes
2. check official docs when needed
3. inspect live environment state
4. answer or act
5. record durable learnings

## When docs lookup is mandatory

Do a docs lookup before answering or acting when any of these are true:
- the user asks about Kubernetes command syntax, resource semantics, feature behavior, or configuration behavior
- the task involves workloads, services, ingress, volumes, scheduling, RBAC, policies, nodes, controllers, or API object behavior
- the task involves a version-sensitive feature or a behavior you are not highly confident about
- the task involves live CLI/manifest work and the resource path or safety boundaries matter

## Cache-first rule

Before fetching docs, check whether the needed material already exists under:
- `.Kubernetes-Encyclopedia/docs/kubernetes.io/docs/...`
- `.Kubernetes-Encyclopedia/notes/components/...`
- `.Kubernetes-Encyclopedia/notes/patterns/...`
- `.Kubernetes-Encyclopedia/inventory/...`

If the local cache is good enough, use it.
If not, fetch/check the official docs and then cache what you used.

## How to cache docs

Use `scripts/cache_doc.py`.

Typical usage:

```bash
python3 scripts/cache_doc.py \
  --url 'https://kubernetes.io/docs/concepts/workloads/controllers/deployment/' \
  --root '<workspace>/.Kubernetes-Encyclopedia'
```

The script will:
- fetch the page
- convert it into a normalized markdown-ish cache file
- place it under `.Kubernetes-Encyclopedia/docs/kubernetes.io/docs/...`
- add metadata such as source URL and fetch timestamp

## How to store local knowledge

### Component notes

Use `.Kubernetes-Encyclopedia/notes/components/<component-name>.md` for:
- component purpose
- access path
- role in deployment
- sensitive boundaries
- discovered quirks

### Pattern notes

Use `.Kubernetes-Encyclopedia/notes/patterns/<topic>.md` for:
- recurring workload/operations patterns
- repeated gotchas
- safe operational sequences
- environment-specific design conventions

### Inventory files

Use `.Kubernetes-Encyclopedia/inventory/` for:
- deployment/access inventory
- topology/runtime layout
- documentation index

## Distinguish evidence types

When writing notes, label information mentally as one of:
- **Official docs** — from Kubernetes documentation
- **Observed local state** — from live environment inspection
- **Inference/recommendation** — your judgment based on docs + local state

Do not blur these together.

## Recommended answer style

When it helps, mention whether your answer is based on:
- cached official docs
- freshly checked official docs
- live environment inspection
- best-practice inference

## High-sensitivity areas

Treat these as high-sensitivity even when you have live access:
- namespace-wide or cluster-wide manifest changes
- RBAC, policy, or credential exposure changes
- ingress/service exposure changes
- volume/storage class or stateful workload changes
- node, control-plane, or networking changes
- changes that could break workload availability, traffic, storage, or cluster access

For these, prefer docs lookup even if you think you remember the resource shape or command path.


path: scripts/cache_doc.py
content: #!/usr/bin/env python3
from __future__ import annotations

import argparse
import html
import ipaddress
import re
import urllib.parse
import urllib.request
from datetime import datetime, timezone
from html.parser import HTMLParser
from pathlib import Path, PurePosixPath

ALLOWED_NETLOCS = {'kubernetes.io'}
ALLOWED_SCHEMES = {'https'}
OUTPUT_NETLOC = 'kubernetes.io'
USER_AGENT = 'Kubernetes-Encyclopedia/1.1'
TITLE_FALLBACK = 'Kubernetes Doc'
PATH_HELP = 'kubernetes.io docs URL to cache'
ROOT_HELP = 'Kubernetes Encyclopedia data root (default: <cwd>/.Kubernetes-Encyclopedia)'
DESCRIPTION = 'Fetch and cache a Kubernetes docs page into .Kubernetes-Encyclopedia.'
PATH_PREFIX = '/docs'
BLOCK_QUERY = True


class TextExtractor(HTMLParser):
    def __init__(self) -> None:
        super().__init__()
        self.in_script = False
        self.in_style = False
        self.title = ''
        self._in_title = False
        self.parts: list[str] = []

    def handle_starttag(self, tag: str, attrs):
        tag = tag.lower()
        if tag == 'script':
            self.in_script = True
        elif tag == 'style':
            self.in_style = True
        elif tag == 'title':
            self._in_title = True
        elif tag in {'li', 'br', 'h4', 'h3', 'div', 'h2', 'article', 'tr', 'p', 'section', 'h1', 'h6', 'h5'}:
            self.parts.append('\n')

    def handle_endtag(self, tag: str):
        tag = tag.lower()
        if tag == 'script':
            self.in_script = False
        elif tag == 'style':
            self.in_style = False
        elif tag == 'title':
            self._in_title = False
        elif tag in {'li', 'br', 'h4', 'h3', 'div', 'h2', 'article', 'tr', 'p', 'section', 'h1', 'h6', 'h5'}:
            self.parts.append('\n')

    def handle_data(self, data: str):
        if self.in_script or self.in_style:
            return
        text = html.unescape(data)
        if self._in_title:
            self.title += text
        self.parts.append(text)

    def text(self) -> str:
        text = ''.join(self.parts)
        text = re.sub(r'\r', '', text)
        text = re.sub(r'\n{3,}', '\n\n', text)
        text = re.sub(r'[ \t]+', ' ', text)
        lines = [line.strip() for line in text.splitlines()]
        return '\n'.join(line for line in lines if line).strip()


def default_root() -> Path:
    return Path.cwd() / '.Kubernetes-Encyclopedia'


def normalized_relative_path(parsed: urllib.parse.ParseResult) -> PurePosixPath:
    raw_path = urllib.parse.unquote(parsed.path or '/')
    if '\x00' in raw_path:
        raise ValueError('NUL bytes are not supported in URL paths')
    if PATH_PREFIX and not (raw_path == PATH_PREFIX or raw_path.startswith(PATH_PREFIX + '/')):
        raise ValueError(f'Only {PATH_PREFIX} URLs are supported')
    pure = PurePosixPath(raw_path)
    parts = [part for part in pure.parts if part not in ('/', '')]
    if any(part in {'.', '..'} for part in parts):
        raise ValueError('Dot path segments are not supported')
    rel = PurePosixPath(*parts) if parts else PurePosixPath('index')
    if raw_path.endswith('/'):
        rel = rel / 'index'
    return rel.with_suffix('.md')


def validate_url(url: str) -> urllib.parse.ParseResult:
    parsed = urllib.parse.urlparse(url)
    if parsed.scheme not in ALLOWED_SCHEMES:
        raise ValueError(f'Only {sorted(ALLOWED_SCHEMES)} URLs are supported')
    if parsed.username or parsed.password:
        raise ValueError('Userinfo in URLs is not supported')
    if parsed.hostname is None:
        raise ValueError('URL must include a hostname')
    try:
        ipaddress.ip_address(parsed.hostname)
    except ValueError:
        pass
    else:
        raise ValueError('Direct IP URLs are not supported')
    if parsed.hostname not in ALLOWED_NETLOCS:
        raise ValueError(f'Only {sorted(ALLOWED_NETLOCS)} URLs are supported')
    if parsed.port is not None:
        raise ValueError('Explicit ports are not supported')
    if BLOCK_QUERY and (parsed.params or parsed.query or parsed.fragment):
        raise ValueError('Query strings, params, and fragments are not supported')
    normalized_relative_path(parsed)
    return parsed


def ensure_within(base: Path, candidate: Path) -> Path:
    resolved_base = base.resolve(strict=False)
    resolved_candidate = candidate.resolve(strict=False)
    try:
        resolved_candidate.relative_to(resolved_base)
    except ValueError as exc:
        raise ValueError('Refusing to write outside the cache root') from exc
    return resolved_candidate


def build_output_path(root: Path, parsed: urllib.parse.ParseResult) -> Path:
    rel = normalized_relative_path(parsed)
    base = root / 'docs' / OUTPUT_NETLOC
    out = base.joinpath(*rel.parts)
    return ensure_within(base, out)


def fetch_html(url: str) -> str:
    req = urllib.request.Request(url, headers={'User-Agent': USER_AGENT})
    with urllib.request.urlopen(req, timeout=20) as resp:
        charset = resp.headers.get_content_charset() or 'utf-8'
        return resp.read().decode(charset, errors='replace')


def main() -> int:
    parser = argparse.ArgumentParser(description=DESCRIPTION)
    parser.add_argument('--url', required=True, help=PATH_HELP)
    parser.add_argument('--root', default=str(default_root()), help=ROOT_HELP)
    args = parser.parse_args()

    parsed = validate_url(args.url)
    root = Path(args.root).expanduser().resolve()
    html_body = fetch_html(args.url)
    extractor = TextExtractor()
    extractor.feed(html_body)
    title = extractor.title.strip() or Path(parsed.path).name or TITLE_FALLBACK
    body = extractor.text()
    out = build_output_path(root, parsed)
    out.parent.mkdir(parents=True, exist_ok=True)
    content = (
        f'# {title}\n\n'
        f'- Source: {args.url}\n'
        f'- Cached at: {datetime.now(timezone.utc).isoformat()}\n\n'
        '## Cached text\n\n'
        f'{body}\n'
    )
    out.write_text(content, encoding='utf-8')
    print(out)
    return 0


if __name__ == '__main__':
    raise SystemExit(main())


path: scripts/init_workspace.py
content: #!/usr/bin/env python3
from __future__ import annotations

import argparse
from pathlib import Path

SEED_FILES = {
    'inventory/access.md': '# Kubernetes Access Inventory\n\nStore Kubernetes environment and access notes here.\n',
    'inventory/topology.md': '# Kubernetes Topology\n\nStore environment-specific Kubernetes topology and component-role notes here.\n',
    'inventory/doc-index.md': '# Kubernetes Cached Doc Index\n\nTrack especially useful cached official-doc pages here when helpful.\n',
    'notes/components/.gitkeep': '',
    'notes/patterns/.gitkeep': '',
    'docs/kubernetes.io/docs/.gitkeep': '',
}


def default_root() -> Path:
    return Path.cwd() / '.Kubernetes-Encyclopedia'


def main() -> int:
    parser = argparse.ArgumentParser(description='Create/repair the .Kubernetes-Encyclopedia workspace layout.')
    parser.add_argument('--root', default=str(default_root()), help='Data root to initialize (default: <cwd>/.Kubernetes-Encyclopedia)')
    args = parser.parse_args()

    root = Path(args.root).expanduser().resolve()
    for rel, content in SEED_FILES.items():
        path = root / rel
        path.parent.mkdir(parents=True, exist_ok=True)
        if not path.exists():
            path.write_text(content, encoding='utf-8')
    print(root)
    return 0


if __name__ == '__main__':
    raise SystemExit(main())


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)