Merge pull request KafClaw#27 from scalytics/sills

Add Skill management, hardening, security, keystore

Author: novatechflow

.github/workflows/ci.yml

@@ -76,6 +76,9 @@ jobs:
       - name: Run tests
         run: go test ./...
 
+      - name: Security check gate
+        run: go run ./cmd/kafclaw security check
+
       - name: Run race detector
         run: go test -race ./...
 

.github/workflows/release.yml

@@ -136,6 +136,10 @@ jobs:
           go-version: "1.24.13"
           cache-dependency-path: go.sum
 
+      - name: Validate bundled skills artifacts
+        shell: bash
+        run: bash scripts/check_bundled_skills.sh
+
       - name: Build hardened binary
         shell: bash
         env:
@@ -174,9 +178,11 @@ jobs:
           set -euo pipefail
           BIN_NAME="kafclaw-${{ matrix.artifact_suffix }}${{ matrix.ext }}"
           BUNDLE_DIR="dist/kafclaw-${{ matrix.artifact_suffix }}-bundle"
-          mkdir -p "$BUNDLE_DIR/bin" "$BUNDLE_DIR/systemd" "$BUNDLE_DIR/env"
+          mkdir -p "$BUNDLE_DIR/bin" "$BUNDLE_DIR/systemd" "$BUNDLE_DIR/env" "$BUNDLE_DIR/skills" "$BUNDLE_DIR/docs/skills"
 
           cp "dist/${BIN_NAME}" "$BUNDLE_DIR/bin/kafclaw"
+          cp -R skills/. "$BUNDLE_DIR/skills/"
+          cp -R docs/skills/. "$BUNDLE_DIR/docs/skills/"
 
           cat > "$BUNDLE_DIR/systemd/kafclaw.service" <<'UNIT'
           [Unit]
@@ -227,6 +233,10 @@ jobs:
 
           tar -C dist -czf "dist/kafclaw-${{ matrix.artifact_suffix }}-bundle.tar.gz" "kafclaw-${{ matrix.artifact_suffix }}-bundle"
 
+          if [[ "${{ matrix.goarch }}" == "amd64" ]]; then
+            tar -czf "dist/kafclaw-skills-bundle.tar.gz" skills docs/skills
+          fi
+
       - name: Upload artifact
         uses: actions/upload-artifact@v4
         with:

Makefile

@@ -10,7 +10,7 @@ NPM_MIN_VERSION := 11
 HOST_GOMODCACHE := $(shell go env GOMODCACHE)
 HOST_GOCACHE := $(shell go env GOCACHE)
 
-.PHONY: help check bootstrap build run rerun test vet race commit-check test-smoke test-critical test-fuzz code-ql test-classification test-subagents-e2e install \
+.PHONY: help check bootstrap build run rerun test vet race fmt-check commit-check test-smoke test-critical test-fuzz code-ql test-classification test-subagents-e2e check-bundled-skills install \
 	release release-major release-minor release-patch dist-go \
 	docker-build docker-up docker-down docker-logs \
 	run-standalone run-full run-headless \
@@ -108,9 +108,20 @@ vet: ## Run go vet across all packages
 race: ## Run race-enabled tests across all packages
 	go test -race ./...
 
+fmt-check: ## Verify Go files are gofmt-formatted
+	@unformatted="$$(gofmt -l .)"; \
+	if [ -n "$$unformatted" ]; then \
+		echo "The following files are not gofmt-formatted:"; \
+		echo "$$unformatted"; \
+		exit 1; \
+	fi
+
 test-smoke: ## Run fast critical-path smoke tests (bug-finding first)
 	bash scripts/test_smoke.sh
 
+check-bundled-skills: ## Validate that bundled skills/docs artifacts exist
+	bash scripts/check_bundled_skills.sh
+
 test-critical: ## Enforce 100% coverage on critical logic
 	bash scripts/check_critical_coverage.sh
 
@@ -120,7 +131,7 @@ test-fuzz: ## Run fuzz tests for critical guard logic
 code-ql: ## Run local CodeQL (Go + JS/TS + Actions) and emit SARIF under .tmp/codeql/
 	bash scripts/codeql_local.sh
 
-commit-check: check vet race test-fuzz code-ql ## Run pre-commit quality gates (vet, race, fuzz, CodeQL)
+commit-check: check fmt-check vet race test-fuzz code-ql ## Run pre-commit quality gates (fmt, vet, race, fuzz, CodeQL)
 	@echo "commit-check completed."
 
 test-classification: ## Run internal/external message classification E2E test (verbose)

docs/architecture-security/security-for-ops.md

@@ -94,6 +94,21 @@ Test restore regularly on a clean host.
 ./kafclaw status
 ./kafclaw doctor
 ./kafclaw doctor --fix
+./kafclaw security check
+./kafclaw security audit --deep
+./kafclaw security fix --yes
 ```
 
 Use these as part of daily operations and after any security-relevant change.
+
+## 9. Skills and OAuth Security Notes
+
+- Prefer `skills.scope=selected` for least-privilege skill exposure.
+- Use `skills.runtimeIsolation=auto` (or `strict` when container runtime is guaranteed).
+- When using `strict`, `kafclaw security check` validates that `docker`/`podman` is actually usable by the current operator user.
+- OAuth skill tokens are encrypted at rest with local tomb-key management by default (`~/.config/kafclaw/tomb.rr`), with optional keyring/file backends.
+- `doctor --fix` moves sensitive env keys into tomb-managed encrypted storage and scrubs them from `~/.config/kafclaw/env`.
+- Security events and install decisions are chained into immutable-style audit logs under `~/.kafclaw/skills/audit/`.
+- For deployment-specific skill operations and remediations, refer to:
+  - [Skills](../skills/index.md)
+  - [KafClaw Management Guide](../operations-admin/manage-kafclaw.md)

docs/operations-admin/manage-kafclaw.md

@@ -14,9 +14,11 @@ Operator-focused guide for managing KafClaw from CLI and runtime endpoints.
 | `kafclaw onboard` | Initialize config and scaffold workspace identity files |
 | `kafclaw gateway` | Run full gateway (API, dashboard, channels, memory, group/orchestrator when enabled) |
 | `kafclaw status` | Quick operational status: config, providers, channels, pairing, policy diagnostics |
-| `kafclaw doctor` | Run setup and config diagnostics |
+| `kafclaw doctor` | Run setup/config diagnostics including skills readiness checks |
+| `kafclaw security` | Unified security checks/audit/fix (`check`, `audit --deep`, `fix --yes`) |
 | `kafclaw config` | Low-level dotted-path config read/write/unset |
-| `kafclaw configure` | Guided updates for selected settings (currently subagent allowlist) |
+| `kafclaw configure` | Guided/non-interactive config updates (subagents + skills toggles) |
+| `kafclaw skills` | Skills lifecycle (`enable/disable/list/status/verify/install/update/auth/prereq`) |
 | `kafclaw group` | Join/leave/status/members for Kafka collaboration group |
 | `kafclaw kshark` | Kafka connectivity and protocol diagnostics |
 | `kafclaw agent -m` | Single-shot direct CLI interaction with agent loop |
@@ -54,6 +56,7 @@ Then verify:
 ./kafclaw onboard --non-interactive --profile local --llm skip
 ./kafclaw onboard --non-interactive --profile local-kafka --kafka-brokers localhost:9092 --group-name kafclaw --agent-id agent-local --role worker --llm skip
 ./kafclaw onboard --non-interactive --profile remote --llm openai-compatible --llm-api-base http://localhost:11434/v1 --llm-model llama3.1:8b
+./kafclaw onboard --non-interactive --accept-risk --skip-skills=false --install-clawhub --skills-node-major 20
 ```
 
 Mode effects applied by onboarding:
@@ -98,6 +101,8 @@ Highlights include:
 ```
 
 `doctor` returns non-zero when failing checks exist.
+When skills are enabled, doctor also checks `node`, `clawhub` (if external installs are enabled), runtime dir permissions, and channel-onboarding readiness.
+Use `kafclaw security` for consolidated security posture and deep skill audits.
 
 ## 5. Config Management
 
@@ -115,8 +120,18 @@ Highlights include:
 ./kafclaw configure
 ./kafclaw configure --subagents-allow-agents agent-main,agent-research --non-interactive
 ./kafclaw configure --clear-subagents-allow-agents --non-interactive
+./kafclaw configure --non-interactive --skills-enabled-set --skills-enabled=true --skills-node-manager npm
+./kafclaw configure --non-interactive --skills-scope selected
+./kafclaw configure --non-interactive --enable-skill github --disable-skill weather
 ```
 
+Skills policy defaults:
+
+- `skills.scope=selected` (least-privilege, recommended)
+- `skills.runtimeIsolation=auto` (use strict if container runtime is mandatory in your environment)
+
+See [Skills](../skills/index.md) for full skill policy details.
+
 ### LLM provider and token management
 
 Interactive (recommended):
@@ -272,6 +287,30 @@ Core runtime files:
 This section applies to **direct HTTP clients** that call KafClaw API endpoints.
 For Slack/Teams/WhatsApp users, authentication is handled by provider bridge + pairing/allowlist controls, not by manually passing the gateway bearer token.
 
+## 12. Security Command Runbook
+
+```bash
+./kafclaw security check
+./kafclaw security audit --deep
+./kafclaw security fix --yes
+```
+
+Recommended usage:
+
+- `security check`: quick operational gate in CI/day-2 operations.
+- `security audit --deep`: include installed skill re-verification.
+- `security fix --yes`: apply safe remediations; re-run check after changes.
+- `doctor --fix`: merges env files, syncs sensitive env keys into tomb-managed encrypted storage, then scrubs those sensitive keys from `~/.config/kafclaw/env`.
+
+For security posture details, see [Security for Operators](../architecture-security/security-for-ops.md).
+For skills policy, OAuth keying, and source pinning syntax, see [Skills](../skills/index.md).
+
+Recommended CI gate:
+
+```bash
+go run ./cmd/kafclaw security check
+```
+
 When `KAFCLAW_GATEWAY_AUTH_TOKEN` (or `gateway.authToken`) is set, direct clients do not auto-receive tokens.
 Operators must distribute tokens out-of-band (secure chat, secret manager, deployment env injection, etc.).
 

docs/skills/channel-onboarding.md

@@ -0,0 +1,48 @@
+---
+title: channel-onboarding
+parent: Skills
+nav_order: 1
+---
+
+# channel-onboarding
+
+Guides setup and verification for Slack, Teams, and WhatsApp channel integrations.
+
+## Default State
+
+- Bundled with KafClaw
+- Enabled by default
+
+## What It Does
+
+- Validates channel prerequisites and required config fields.
+- Guides first-time onboarding for Slack, Teams, and WhatsApp.
+- Produces concrete remediation steps when checks fail.
+
+## Install / Enable
+
+Already bundled and enabled by default. To ensure the skills system is active:
+
+```bash
+kafclaw skills enable
+```
+
+## Usage
+
+- Run onboarding:
+
+```bash
+kafclaw onboard
+```
+
+- Run diagnostics:
+
+```bash
+kafclaw doctor
+```
+
+## Troubleshooting
+
+- If channels do not respond, check channel `enabled` flags and required tokens in config.
+- If onboarding is skipped, rerun with `kafclaw onboard --skip-skills=false`.
+- If diagnostics report missing prerequisites, follow the command hints from `doctor`.

docs/skills/gh-issues.md

@@ -0,0 +1,39 @@
+---
+title: gh-issues
+parent: Skills
+nav_order: 5
+---
+
+# gh-issues
+
+Run issue-driven engineering loops with controlled PR lifecycle.
+
+## Default State
+
+- Bundled with KafClaw
+- Disabled by default
+
+## What It Does
+
+- Selects and executes issue work by priority/label.
+- Drives implementation, PR updates, and review follow-up.
+- Keeps explicit approval gates for merge and high-risk operations.
+
+## Install / Enable
+
+No external install needed (bundled skill). Enable it:
+
+```bash
+kafclaw skills enable-skill gh-issues
+```
+
+## Usage
+
+- Use when running backlog-driven work and shipping issues end-to-end.
+- Works best with `github` skill enabled for full repository operations.
+
+## Troubleshooting
+
+- If issue selection is noisy, tighten labels/milestones before execution.
+- If PR actions fail, verify GitHub auth and repository permissions.
+- If merge actions are blocked, confirm approval workflow requirements.

docs/skills/github.md

@@ -0,0 +1,39 @@
+---
+title: github
+parent: Skills
+nav_order: 4
+---
+
+# github
+
+Operate GitHub issues, pull requests, and checks safely.
+
+## Default State
+
+- Bundled with KafClaw
+- Disabled by default
+
+## What It Does
+
+- Supports issue/PR/check/release workflows with controlled safety gates.
+- Encourages minimal, auditable changes with clear status reporting.
+- Applies approval expectations before merge/release/destructive actions.
+
+## Install / Enable
+
+No external install needed (bundled skill). Enable it:
+
+```bash
+kafclaw skills enable-skill github
+```
+
+## Usage
+
+- Use for repo triage, PR follow-up, and CI signal interpretation.
+- Pair with `gh-issues` for issue-driven execution loops.
+
+## Troubleshooting
+
+- If GitHub actions fail, verify `gh auth status`.
+- If operations are blocked, check your policy/approval settings.
+- If API calls are rate-limited, retry with reduced query scope.

docs/skills/google-cli.md

@@ -0,0 +1,60 @@
+---
+title: google-cli
+parent: Skills
+nav_order: 7
+---
+
+# google-cli
+
+Install and validate the Google Cloud CLI (`gcloud`) for cloud/operator workflows.
+
+## Default State
+
+- Bundled with KafClaw
+- Disabled by default
+
+## Check
+
+```bash
+kafclaw skills prereq check google-cli
+```
+
+## Install Plan
+
+```bash
+kafclaw skills prereq install google-cli --dry-run
+```
+
+## Install
+
+```bash
+kafclaw skills prereq install google-cli --yes
+```
+
+The installer uses Go-native OS routines (APT on Linux, Homebrew on macOS).
+
+## Enable Skill
+
+```bash
+kafclaw skills enable-skill google-cli
+```
+
+## Usage
+
+- Verify auth status:
+
+```bash
+gcloud auth list
+```
+
+- Verify active project:
+
+```bash
+gcloud config get-value project
+```
+
+## Troubleshooting
+
+- If install fails on Linux, run package metadata update and retry.
+- If `gcloud` is not found after install, ensure your shell `PATH` includes the install location.
+- If auth fails in headless environments, use device/browser-based auth flow from Google CLI.