[RFC]: Terminology glossary and inclusive language sweep

[rosspeili]

Summary

Open discussion and follow-up work to consolidate Skillware vocabulary and apply an inclusive language pass across the repository.

Today the same concepts appear under many names — operator, human, contributor, user, agent, calling agent, host agent, supervised agent; skill, registry skill, skill bundle, bundle, skill package; Mind / Body / Conscience vs instructions.md / skill.py / manifest.yaml — and some terms are reused for different meanings (eg. operator as runtime person vs operator in ops/security docs).

This RFC does not require one giant PR. It defines principles, a canonical glossary, inclusive-language guidance, and a sweep scope so whoever picks up implementation can systematically review docs, comments, issue/PR templates, examples, and code-facing strings (renaming public APIs only when justified).

Reference (starting point, not exhaustive): Khronos Inclusive Language — block/allow-list, placeholder vs dummy, gender-neutral phrasing, avoid master/slave metaphors, sanity check → confidence check, etc. Apply where relevant; add Skillware-specific terms Khronos does not cover.

Motivation

Problems

1. Terminology drift — New contributors, skill authors, and agents reading docs hit inconsistent words for the same role or artifact. That slows onboarding, causes wrong assumptions (e.g. “agent” = LLM vs autonomous coding agent vs SkillLoader consumer), and makes cross-doc links harder to maintain.

2. Same word, different meaning — Example tensions to resolve:

   • Operator — person running Skillware in production vs person configuring paths vs security “operator checklist”
   • Agent — LLM with tools vs human-supervised coding agent vs “host agent” in skill instructions
   • Bundle — dict returned by load_skill() vs directory on disk vs “skill package” in CONTRIBUTING
   • Skill — registry ID (category/name) vs folder vs Python class vs tool exposed to an LLM

3. Inclusive language — Some repo prose and comments use casual terms (e.g. dummy in tests/comments, master in marketing copy, gendered defaults) that we can improve without changing behavior. Khronos provides a practical baseline; we should adopt what fits and document exceptions (e.g. tool names like black that we do not rename).

4. Ripple effects — Terminology choices affect [RFC]: Skill identity and registry architecture #234 identity RFC, trust model, CLI help, skill catalog pages, and agent-native workflow. A single glossary reduces future doc debt.

Goals

• One canonical glossary (preferred term → definition → deprecated synonyms → when to use each).
• Inclusive language guidelines for Skillware (with Khronos as reference + local additions).
• Sweep checklist covering all file classes.
• Phased implementation (docs first, comments second, code identifiers only when necessary and semver-aware).

Non-goals

• Renaming PyPI package, CLI command names, or registry skill IDs for wording alone.
• Rewriting all skill instructions.md voice/persona unless a term is objectively wrong or exclusive.
• Blocking skill or framework shipping on completion of this RFC (implementation is follow-up work).

Detailed Design

1. Principles (proposed — open to comment)

1. One concept, one primary term — Synonyms allowed once per doc for readability, but link to glossary on first use.
2. Context-specific terms are OK if defined — e.g. host agent (LLM runtime hosting tools) vs contributor (person/agent opening PRs) — but must not collide with operator without disambiguation.
3. Code wins for APIs — Glossary follows public names (SkillLoader.load_skill, bundle["class"]()); docs align to code, not the reverse, unless a planned rename is approved.
4. Inclusive by default — Prefer neutral, precise language in docs and comments; avoid ableist, racialized, or gendered metaphors where alternatives exist (Khronos list).
5. Pragmatic exceptions — Third-party tool names (black, whitelist in upstream docs we quote), skill domain vocabulary (e.g. clinical terms in mental_coach KB sources), and historical CHANGELOG entries may stay unchanged or be noted as exceptions.
6. Behavior unchanged — Wording-only unless a separate issue approves identifier renames.

2. Terminology map (draft — RFC should refine)

Concept	Preferred term(s)	Avoid / clarify	Notes
Person running skills in their environment	Operator	“user” (too generic), “admin”	Security/trust docs
Person or agent opening PRs	Contributor	“human operator” except when contrasting with autonomous agents	CONTRIBUTING, ai_native_workflow
LLM + tool loop consuming skills	Agent (or host agent when distinguishing from contributor agents)	“AI”, “model” alone	usage/, agent_loops.md
Agent under human oversight in repo workflow	Supervised agent	“bot”, “AI contributor”	ai_native_workflow, vision
load_skill() return value	Skill bundle or bundle	“package” alone (PyPI confusion)	Code + docs
Directory under skills/category/name/	Skill directory / registry skill	“the skill” when ambiguous	CONTRIBUTING
Registry ID string	Skill ID	“name” alone (manifest name vs tool name)	cli.md, #201
instructions.md + manifest cognitive layer	Instructions (not mandatory to drop Mind/Body metaphor)	Inconsistent “Mind” without definition	Catalog pages — decide: keep metaphor with glossary entry or standardize
Executable Python module	skill.py / skill class	“the body” without context
manifest.yaml governance fields	Manifest

Open RFC questions

• Retain Mind / Body / Conscience branding in catalog pages or migrate to neutral Instructions / Implementation / Manifest?
• Standardize operator vs contributor in README Contributing section?
• How to refer to Cursor / Copilot / coding agents in one phrase?
• Community Qs?

3. Inclusive language (Khronos-aligned + Skillware)

Reference: https://www.khronos.org/about/inclusive-language

If you find	Consider	Example in repo (illustrative)
dummy (placeholder)	mock, stub, placeholder, fake	test comments, dummy_key_for_ci
master (dominance / main copy)	primary, main, source	README “master a domain” → “learn a domain” or “use a skill proficiently”
sanity check	confidence check, smoke check, quick check	docs, comments
guys / he default	they, contributors, folks	prose
whitelist / blacklist	allow-list / block-list	if any appear in our text (not upstream tool names)
man-in-the-middle	on-path attacker, PITM	security docs if applicable

Not in scope to rename

• Dependency and CLI tool names (black, etc.)
• Skill domain content quoted from external standards (unless we control the wording)
• Git history / old CHANGELOG bullets (optional forward-only rule)

Deliverable: short docs/contributing/inclusive-language.md or section in CONTRIBUTING linking Khronos + Skillware exceptions.

4. Sweep scope (implementer checklist)

Whoever implements after RFC approval should search and reconcile:

Area	Examples
Root + docs/**	README, introduction, vision, trust model, usage guides, skill catalog, TESTING, CONTRIBUTING, ai_native_workflow
skills/**	instructions.md, comments in skill.py, manifest descriptions
skillware/**	docstrings, inline comments (not public API unless approved)
tests/**, examples/**	comments, fixture names
.github/**	issue templates, PR template, labels.json descriptions
templates/python_skill/**	new-skill scaffold wording
CHANGELOG.md	forward entries only

Search patterns (starting set)

operator|human operator|contributor|supervised agent|host agent|calling agent
skill bundle|bundle\[|skill package|registry skill|skill directory
Mind|Body|Conscience
dummy|sanity|master a|whitelist|blacklist|guys\b|he/she

5. Proposed deliverables (implementation — follow-up issue(s))

• docs/glossary.md (or docs/contributing/glossary.md) — canonical terms + deprecated synonyms
• Inclusive language section (CONTRIBUTING or linked doc) — Khronos reference + exceptions
• CONTRIBUTING / ai_native_workflow — point contributors to glossary before writing docs
• Sweep PR(s) — docs-first; group by directory to keep reviewable
• tests/test_registry_docs.py or new guard (optional) — ban deprecated terms in new docs? (Discuss — may be too strict initially)
• CHANGELOG under [Unreleased] when contributor-facing docs change

6. Phasing

Phase	Scope	Risk
0 — RFC	Agree glossary + policy	—
1 — Glossary doc	No mass edits	Low
2 — Core docs	README, CONTRIBUTING, introduction, trust, usage index, agent_loops	Low
3 — Catalog + skills instructions	Per-skill PRs or one sweep	Medium
4 — Comments / tests	dummy → mock/placeholder where readable	Low
5 — Code identifiers	Only with explicit approval + semver note	High — defer by default

7. Suggested RFC outcomes (when ready to close)

• Approved glossary (or approved draft with owner)
• Decision on Mind/Body/Conscience vs neutral terms in catalog template
• Inclusive language policy location and Khronos reference
• Sweep scope + phasing agreed
• One or more implementation issues filed (good candidate for help wanted)

Drawbacks

• Large surface area — Easy to scope-creep into rewrites that do not improve clarity.
• Bike-shedding — Terminology debates (agent vs operator) can stall without a decision record.
• Churn for contributors — Open PRs may conflict with glossary edits; coordinate or batch merges.
• Imperfect automation — Grep-based sweeps miss context; human judgment required (especially skill domain language).
• Khronos is not complete — Graphics/API bias; Skillware needs its own agent/skill/bundle vocabulary beyond Khronos.
• API renames are costly — Temptation to “fix” code identifiers should be resisted unless separately approved.

Mitigation: RFC locks vocabulary first; implementation is phased; docs-only default; no mandatory rename of registry IDs or CLI; exception list published upfront.