Document skill trust model and operator security warnings

[mrmasa88]

Summary

Resolves #109 (Phase 0 — docs only). Adds an operator-facing document explaining Skillware's skill trust model, and wires links to it from the security-relevant files.

This is documentation only. It does not change SkillLoader, add flags, or implement sandboxing (those remain in #110–#114). It documents the current state honestly.

Fixes #109

What's included

• New: docs/security/skill-trust-model.md — the operator mental model:
  1. Executive summary — loading a skill runs its skill.py in the host process with full filesystem + os.environ access.
  2. On-disk resolution order (SKILLWARE_SKILL_PATH → cwd ./skills/ and parents → bundled) and shadowing.
  3. Provenance tiers (A/B/C — Bundled / Project / External), with an explicit "Sandboxed? No" for every tier.
  4. constitution is agent guidance, not Python isolation (with the defi/evm_tx_handler example).
  5. Concrete flows (pip-only, dev with ./skills/, external path) and what can go wrong.
  6. Operator checklist.
  7. Roadmap pointer ([Feat]: Skill load trust tiers — origin metadata and warnings for non-bundled skills (sub-issue of #17) #110, [Feat]: Scoped environment injection for skill execution (sub-issue of #17; complements #39) #111 + [RFC]: Pluggable Secret Management Architecture & Context Binding #39, [Feat]: Research spike — subprocess worker isolation for skill execute() (sub-issue of #17) #112–[Feat]: Optional container-backed skill execution for high-risk domains (sub-issue of #17) #114, parent [RFC]: Security Sandboxing Strategies for Untrusted Skills #17).
• New: docs/security/README.md — index for the new folder.
• Wiring: SECURITY.md (skill execution model section), docs/usage/README.md (security note on "Finding skills on disk"), CONTRIBUTING.md (registry review ≠ runtime isolation), CODE_OF_CONDUCT.md (replaced the undefined "sandboxing rules" reference with a link to the trust doc), CHANGELOG.md ([Unreleased] Documentation entry).

Acceptance bar

The doc leads with "None of these tiers are sandboxed today," and a new operator comes away understanding: no default sandbox, where code came from matters, and constitution ≠ isolation. No claim that sandboxing exists today.

Naming

The provenance tiers are labeled A/B/C in the doc, but Bundled / Project / External may read more clearly. Happy to rename to whichever you prefer before merge — flagged here rather than in the doc body so the page stays clean.

Made with Cursor

[rosspeili]

Hey @mrmasa88 thanks a lot for picking this up, and for staying strictly in Phase 0 scope, this is a strong starting point.

A few small notes before merge:

1. Rebase on current main, there’s a loader/docs entry in [Unreleased] from [Feat]: Loader validates manifest.name matches skill folder path (#101 Option A) #200/feat(loader): validate manifest name against registry path (#200) #213, so CHANGELOG.md will need a quick merge.
2. Cross-links, consider a one-liner from README.md or docs/introduction.md pointing operators at docs/security/skill-trust-model.md (not sure it woudl be needed everywhere, but maybe would make sense).
3. Flat vs registry layout, a short note that private skills can live as skills/<name>/ (flat) as well as skills/<category>/<name>/, and that skillware list only discovers the two-level layout, might help operators who wonder why a local skill loads but doesn’t appear in list.
4. Tier labels, Bundled / Project / External reads clearly, I would go with that.

Happy to merge as-is after rebase, or with the optional doc tweaks if you want them in this PR. I’ll pin a link from #17 once this lands. Thanks again <3

[mrmasa88]

Thanks for the review @rosspeili — addressed all four:

1. Synced with current main (merge), so the [Feat]: SkillLoader.load_skill() should auto-discover and expose the BaseSkill subclass #89/[Feat]: Loader validates manifest.name matches skill folder path (#101 Option A) #200/[Feat]: Update supported-version policy / security #192/[Feat]: Migrate legacy short manifest names to category/skill_name paths #201 loader and docs entries in [Unreleased] are all kept alongside the [Docs]: Document skill trust model and operator security warnings (sub-issue of #17) #109 doc entry.
2. Added a cross-link from docs/introduction.md (Step 1: Discovery & Loading) to the trust doc.
3. Added a short "Flat vs registry layout" note in the resolution section: flat skills (<root>/<name>/) load fine but don't show up in skillware list (which only walks the two-level layout) — the usual reason a local skill loads but is missing from list.
4. Renamed the tiers to Bundled / Project / External throughout — agreed it reads clearer.

Still Phase 0 docs only, no loader/CLI changes. Ready for your re-review whenever. Thanks again <3

[rosspeili]

LGTM @mrmasa88, all review notes addressed. Merging, I'll pin from #17 after this lands. Thanks again!