[RFC]: unified `skillware config` hub — env, skill settings, and paths

[rosspeili]

Summary

Design RFC for a future unified skillware config CLI hub that consolidates operator setup: merged YAML inspection, .env management (scoped by skill in UX, single project file on disk), per-skill non-secret settings, and absorption of today’s paths editor.

Out of scope for this RFC’s implementation: #292 and #293 proceed as filed (gmail operator UX + gmail v2). This issue captures the longer-term CLI/config architecture to review before a follow-up epic replaces or extends piecemeal approaches.

Ask: agree on command shape, YAML layout (skills.<id>), manifest convention, precedence, phased rollout, and what we explicitly defer (instruction overlays, KB expansion, per-skill .env files).

Motivation

After v0.4.9 (#246, #247) the CLI split is awkward:

• skillware config show — read-only; only paths / resolution / legacy are active
• skillware paths (splash menu 4) — writes .skillware.yaml but is not under config
• Secrets — root .env + .env.example; no CLI; load_env_file() is minimal
• Skill operator settings — ad hoc per skill: office/gmail_handler (data/config.yaml, addressbook, signature), defi/evm_tx_handler (skill-dir config.yaml), bundled KB/data elsewhere

#292 proposes gmail-focused CLI/config/docs. #293 covers gmail runtime v2 (OAuth, API, attachments). Both are right-sized for fast merge. Without a shared design, we risk:

• Top-level verbs per skill (skillware mail, …) that do not scale
• Parallel config namespaces (mail: vs skills.office/gmail_handler)
• Duplicate env UX vs skill UX
• Each new skill reimplementing CLI wiring

This RFC defines one framework-level operator model for discussion and later implementation.

Detailed Design

---

1. Principles

Principle	Rule
Top-level CLI stays framework	list, test, doctor, examples, config — not skillware mail
One project .env	Per-skill env is a CLI filter, not separate files
Secrets → env only	Never persist API keys / App Passwords / private keys in YAML
Non-secrets → YAML + files	Paths, signatures, address books, evm preferences
Manifest-driven discovery	env_vars + optional future operator block
Graceful empty states	Skills with nothing to configure still show env checklist + doctor + docs

Precedence (single story):

env var  >  project .skillware.yaml  >  global config.yaml  >  skill bundled default

---

2. Proposed CLI shape

Top-level: skillware config (interactive splash entry + non-interactive subcommands).

skillware config
├── show              # merged global + project YAML (framework + skills.*)
├── paths             # today’s paths submenu (alias skillware paths)
├── env               # project .env management
│   ├── status [--skill ID]
│   ├── set KEY [VALUE] [--skill ID]
│   ├── unset KEY
│   └── init [--merge] [--force]   # from .env.example or generated manifest union
└── skill [ID]
    ├── (pick skill if no ID)
    └── skill-specific items (manifest-driven; gmail pilot in #292 may precede generic layer)

Non-interactive examples:

skillware config show
skillware config env status --skill office/gmail_handler
skillware config env init --merge
skillware config skill office/gmail_handler
skillware config skill office/gmail_handler addressbook init

Interactive menus mirror the same tree (max depth ~4). skillware paths remains an alias during transition.

Relationship to open issues:

Issue	This RFC
#292	May ship gmail-specific UX first; should not block RFC merge; align follow-up refactors to §3–§4
#293	Runtime/oauth in skill bundle; CLI only surfaces auth paths when OAuth lands

---

3. Persistence layout

Files (unchanged locations):

• Global: ~/.config/skillware/config.yaml
• Project: .skillware.yaml
• Secrets: project .env (cwd / repo root)

New active section (today reserved in extra):

skills:
  "office/gmail_handler":
    addressbook_path: ~/.config/skillware/gmail/addressbook.yaml
    signature_plain: |
      —
      Agent mailbox
  "defi/evm_tx_handler":
    default_chain: ethereum
    confirm_before_send: true
    slippage_bps: 50
paths:
  project: auto
  external: []
resolution:
  order: [project, external, bundled]

Framework helper (future): get_skill_settings(skill_id) in skillware/core/config.py — skills stop parsing YAML ad hoc.

Env init safety:

• Default: merge missing keys from template
• --force: overwrite entire .env — require confirmation if file exists
• Warn if .env not gitignored
• Status/show: set / missing / redacted *** — no echo of secrets by default

Env discovery: union of manifest env_vars across installed skills; root .env.example when present; generated stub for pip-only installs. Follow-up: backfill manifest env_vars on skills that use keys but do not declare them today.

---

4. Manifest convention (future)

Optional block to avoid per-skill CLI code forever:

operator:
  env: true
  settings:
    - key: addressbook_path
      type: path
      file_template: data/addressbook.yaml
    - key: signature_plain
      type: text

Generic CLI renders operator.settings; skills read merged skills.<id>.<key>.

Pilot without schema: #292 gmail items can be hardcoded first; second consumer (likely defi/evm_tx_handler) should force generalization.

---

5. Skill tiers (what config skill exposes)

Tier	Behavior	Examples
0 — env only	env status, doctor, docs link	pii_masker, bg_remover, prompt_injection_firewall
1 — env + YAML/files	addressbook, signature, evm prefs	office/gmail_handler, defi/evm_tx_handler
2 — project scaffolds	init files in cwd	dev_tools/issue_resolver → .github/ISSUE_RESOLVER.md
3 — deferred / RFC each	KB overlays, instruction append	prompt_injection_firewall patterns; instruction_overlay on loader

Explicitly not CLI-configurable: bundled sanction/regulatory datasets (wallet_screening, mica corpus), unless a separate governed process exists.

Instruction overlay idea (append to instructions): host-level customization vs bundle integrity — defer; if ever, apply at load time with clear “not part of signed bundle” labeling; separate RFC.

---

6. Phased rollout (post-RFC agreement)

Phase	Deliverable
A	RFC accepted; #292 / #293 merge as scoped
B	skillware config interactive entry; show; env status/set/init; paths under config (alias)
C	skills.<id> merge + get_skill_settings(); gmail + evm wired
D	manifest operator block; backfill env_vars; generic config skill
E	Tier-2 scaffolds (issue_resolver profile); optional Tier-3 items per skill RFC

---

7. Open questions for maintainers

1. Absorb paths fully under config in splash menu, or keep parallel menu 4 until users adapt?
2. Global vs project: should any skill settings be global-only, or always project-first with global fallback?
3. Accept skills."category/name" quoted keys in YAML vs slug office_gmail_handler internally?
4. Minimum manifest operator schema for v1 generic CLI?
5. Should skillware config env init write commented stubs for optional keys only, or all keys?
6. When [CLI]: mail addressbook + signature config, CLI submenu, and operator docs for office/gmail_handler #292 lands with a gmail-specific surface, deprecation path to generic config skill?

---

8. Acceptance for closing this RFC

• Maintainers agree on CLI tree (§2) and YAML layout (§3)
• Decision on manifest operator vs hardcoded pilot (§4)
• Tier list accepted or amended (§5)
• Phase plan (§6) mapped to follow-up issues (not blocking [CLI]: mail addressbook + signature config, CLI submenu, and operator docs for office/gmail_handler #292 / [Skill Upgrade]: office/gmail_handler v2 — OAuth/Gmail API, attachments, signatures, and provider tier #293)
• Open questions (§7) resolved or explicitly deferred

Drawbacks

• Scope creep: a full config hub is large; phasing badly could delay simple [CLI]: mail addressbook + signature config, CLI submenu, and operator docs for office/gmail_handler #292 wins.
• Migration cost: evm and gmail today use different config patterns; unification touches skill code + tests.
• Manifest contract: adding operator is a registry standard change — needs CI guards and contributor docs.
• Security UX: .env CLI must not encourage committing secrets or printing them to logs/history.
• False generality: not every skill benefits from config skill; empty menus annoy if not designed well.
• Overlap confusion: paths + config + env + skill submenus — needs crisp docs or users get lost.
• Instruction overlay / KB editing: tempting shortcuts undermine trust model; deferral may frustrate power users.