From 2affefe1a0517be04ebcd7729d0fb95d98fef2b8 Mon Sep 17 00:00:00 2001 From: Aaron Stannard Date: Wed, 22 Jul 2026 04:16:13 +0000 Subject: [PATCH] docs(skills): fix skill-authoring accuracy in Overview and External Skills Small correctness + clarity fixes surfaced while auditing the skills docs against the netclaw 0.25.0 source: - External Skills wrongly claimed external skills skip the prompt-injection scanner. They don't - skill_load scans every skill at load regardless of source; external skills only skip the write-time scan (they're authored in another tool). Corrected. - Overview said 'create, edit ... with netclaw skill', but there are no such subcommands. You create a native skill by dropping a SKILL.md or via the agent's skill_manage tool; netclaw skill inspects/removes/validates. - Name the system-skill source: 'a CDN' -> 'netclaw's own feed', so it reads as first-party rather than an unspecified third party. - Define 'prompt injection' inline on first use. - Remove a shipped placeholder TODO comment. Chips at #104. --- src/content/docs/skills/external-skills.md | 2 +- src/content/docs/skills/overview.md | 12 +++++------- 2 files changed, 6 insertions(+), 8 deletions(-) diff --git a/src/content/docs/skills/external-skills.md b/src/content/docs/skills/external-skills.md index 911f0b7..1e06fe6 100644 --- a/src/content/docs/skills/external-skills.md +++ b/src/content/docs/skills/external-skills.md @@ -138,7 +138,7 @@ External skills loaded from disk go through: - **Symlink/path safety** — blocked unless `AllowSymlinks: true` for that source - **[Tool access policies](/security/security-model/)** — same restrictions as native skills; the `allowed-tools` frontmatter field is informational only and doesn't grant tool access -External skills do NOT go through the prompt injection content scanner (that only runs on skills authored through the `skill_manage` tool). The assumption is that external skill files are user-curated. +External skills are scanned for prompt injection at load time, the same as every other skill - `skill_load` always scans before returning content. They skip only the write-time scan that runs when you create or edit a skill through netclaw, since you author these files yourself in another tool. ## Validating External Skills diff --git a/src/content/docs/skills/overview.md b/src/content/docs/skills/overview.md index e5bc8fd..7f41ae0 100644 --- a/src/content/docs/skills/overview.md +++ b/src/content/docs/skills/overview.md @@ -13,7 +13,7 @@ All skills follow the [AgentSkills.io](https://agentskills.io) format: a `SKILL. The lifecycle has four phases: -1. **Sync** — at startup, the daemon pulls system skills from a CDN and (optionally) syncs skills from private [skill servers](/skills/skill-server/). These land in read-only directories under `~/.netclaw/skills/`. +1. **Sync** - at startup, the daemon pulls netclaw's built-in skills from netclaw's own feed and (optionally) syncs skills from private [skill servers](/skills/skill-server/). These land in read-only directories under `~/.netclaw/skills/`. 2. **Scan** — the daemon walks all skill directories (native, server feeds, external), validates frontmatter, and merges results. Native skills take precedence over server feeds, which take precedence over external sources. Netclaw logs name collisions from lower-precedence sources as issues and skips the duplicates. Run `netclaw skill issues` to see them. @@ -97,16 +97,14 @@ Four source types, each with different trust and management: | Source | Location | Managed by | Mutable? | |--------|----------|-----------|----------| -| **system** | `~/.netclaw/skills/.system/` | Daemon (CDN sync) | No | +| **system** | `~/.netclaw/skills/.system/` | Daemon (netclaw's feed) | No | | **native** | `~/.netclaw/skills/` | You | Yes | | **server feeds** | `~/.netclaw/skills/.server-feeds/` | Private [skill servers](/skills/skill-server/) | No | | **external** | Configured directories | Source tool (Claude Code, etc.) | At source | -Drop a `SKILL.md` into `~/.netclaw/skills/` and it appears on the next scan — that's a native skill. Create, edit, and remove them with [`netclaw skill`](/cli/skill/). Run `netclaw skill validate` to check a skill's frontmatter before using it. +Drop a `SKILL.md` into `~/.netclaw/skills/` and it appears on the next scan - that's a native skill. You can also ask netclaw's agent to write one for you - it has a `skill_manage` tool for creating and editing skills. Inspect or remove skills with [`netclaw skill`](/cli/skill/), and run `netclaw skill validate` to check a skill's frontmatter before using it. -System skills ship from a CDN feed and are read-only. Built-in skills like `netclaw-memory` and `netclaw-operations` land here on first run. For a fully offline setup, set `SkillSync.DisableSystemSkillSync: true` in your `netclaw.json` (see [Configuration](/configuration/models/) for file location). - - +System skills ship from netclaw's own feed and are read-only. Built-in skills like `netclaw-memory` and `netclaw-operations` land here on first run. For a fully offline setup, set `SkillSync.DisableSystemSkillSync: true` in your `netclaw.json` (see [Configuration](/configuration/models/) for file location). External skills let netclaw read skill directories from other AI tools. Add a local folder via `netclaw config` → Skill Sources or wire up a well-known alias via the CLI. @@ -131,7 +129,7 @@ A native skill named `commit` shadows any `commit` from a server feed or externa ## Security -Skills are just text, but text that lands in an agent's instructions can carry prompt injection. Netclaw runs a content scanner on both write operations (create, edit, sync) and at load time (every `skill_load` call scans before returning content): +Skills are just text, but text that lands in an agent's instructions can carry prompt injection - hidden text that tries to hijack the agent's instructions. Netclaw runs a content scanner on both write operations (create, edit, sync) and at load time (every `skill_load` call scans before returning content): | Verdict | Risk | Action | |---------|------|--------|