[Docs]: Consolidate skill anatomy narrative (Logic/Cognition/Governance/Interface vs Mind/Body/Conscience)

[rosspeili]

Type of fix

Doc drift (catalog, examples index, agent loops)

What needs to be fixed?

Problem summary

Skillware’s public story of what a Skill is is inconsistent across the repo and the marketing site, and several passages overstate what the framework enforces at runtime. Contributors, operators, and future Aura integration docs need one canonical anatomy with honest enforcement language.

This is not a code change — it is a documentation consolidation RFC with a defined decision and a cross-surface sync checklist.

---

Disparity inventory (today)

A. Two competing top-level models

Surface	Model	Count	Labels
README.md	Four pillars	4	Logic, Cognition, Governance, Interface
skillware.site (homepage)	Four pillars (matches README)	4	Logic, Cognition, Governance, Interface — same copy intent as README
docs/introduction.md	“Triad” (heading bug)	3	Heading says Mind, Body, Language; sections are Body, Mind, Conscience
Per-skill catalog pages (docs/skills/*.md)	Mind / Body sections	2	“The Mind (instructions.md)”, “The Body (skill.py)” — no Governance or Interface sections
Provider usage guides (gemini.md, claude.md, …)	Mind + Body colloquial	2	“Inject the Mind”, “Bind the Body”
docs/vision.md	Points to introduction triad	—	“Mind, Body, Conscience architecture in depth”
CONTRIBUTING.md	Bundle file list + instructions guidance	—	Accurate files; “constitution enforced at prompt level” (overstates loader behavior)
docs/security/skill-trust-model.md	Honest correction	—	Constitution is guidance, not isolation or runtime enforcement — contradicts marketing “hard limits baked in”

Net: README + website agree on 4 pillars. Introduction + vision + many skill pages use Mind/Body (3-way conscience/governance folded differently). Interface and card.json appear in README architecture tree but not in the four homepage cards’ mental model explicitly (Interface ≈ manifest/adapters).

B. Heading / naming bugs

• docs/introduction.md § title: “Mind, Body, Language” vs §3 title “Conscience (Governance)” — “Language” is orphaned/wrong.
• Logic (README) = Body (introduction) = skill.py — three names, one file.
• Cognition (README) = Mind (introduction) = instructions.md.
• Governance (README) = Conscience (introduction) = manifest.yaml constitution + issuer — but issuer is catalog/human metadata, not LLM governance.

C. Overstatement vs code (loader + BaseSkill)

Doc claim	Code reality
“When you load the skill, you load its mind into the agent” (introduction.md)	load_skill() reads instructions.md into bundle["instructions"]. Host must pass it to system context — not automatic.
“Governance… hard limits baked into the bundle” (README.md, skillware.site)	Hard limits live in skill.py (execute, gates like dry_run / confirmed, deterministic guardrail skills). manifest.constitution is YAML prose — not read or enforced by loader/BaseSkill (trust model).
“Conscience… Enforced at the prompt level” (introduction.md)	Only if host/instructions surface it. Loader does not merge constitution into tool schema or auto-inject.
“Interface… standardized tool schemas”	True — to_*_tool() uses manifest.description + parameters. Does not include instructions or constitution.

D. Missing from all public narratives

Artifact	Role today	Mentioned in README 4?	In intro triad?
card.json	UI surface (icon, color, ui_schema); loaded in bundle; not consumed by core agent loop; CI validates output keys	Architecture tree only	No
kb/	Body data (lexicons, benchmarks, corpora)	No	No
test_skill.py	Bundle contract tests	Listed in tree	No
Host app	Load / wire / compose instructions / chain execute()	Diagram only (“Host”)	Underplayed
Aura stack alignment	Skillware = Tools layer; host loop = Body in Aura stack-position	No	No

E. Website vs repo

Item	README / repo	skillware.site (Aug 2026)
Four cards	Logic, Cognition, Governance, Interface	Same four (screenshot parity)
Governance copy	“Constitution, safety boundaries, and hard limits baked into the bundle”	Same intent (shield icon)
card.json / Surface	In README architecture tree	Not on homepage cards
Introduction triad	Still linked from vision	Site likely links to docs — may expose triad vs homepage 4

Action: Any doc fix in this repo should include a website sync checklist (skillware.site — separate deploy; maintainer confirms repo or CMS source).

---

Why this matters

1. Contributors write Mind/Body sections on catalog pages while README says Logic/Cognition — reviewers lack a single vocabulary.
2. Operators believe constitution = enforced guardrails; trust model doc says otherwise — liability/confusion.
3. Multi-skill / chaining ([Docs]: add dedicated skill chaining guide under docs/usage #297) needs honest Load → Wire → Run → Compose language; “load = inject mind” blocks that.
4. Aura pairing — Aura uses Body = runtime loop, Tools = Skillware; calling skill.py “the Body” collides with Aura vocabulary.

---

Proposed direction (maintainer recommendation)

Adopt one canonical model for all user-facing surfaces, with a short enforcement table so we stop conflating declared policy with runtime guardrails.

Recommended canonical model: Four layers + Host (evolve current README/website 4)

Map homepage pillars to files and enforcement explicitly:

Pillar (public name)	Bundle files	Enforced by
Logic	skill.py, kb/	Yes — execute()
Cognition	instructions.md	If host wires — system context
Governance	manifest.constitution, issuer, catalog disclaimers	Declared — agents/reviewers; hard rules only if coded in Logic
Interface	manifest (name, description, parameters, outputs) → adapters	Tool schema — partial param validation if host calls validate_params()
Surface (add 5th in architecture docs only, optional on homepage)	card.json	UI hosts — not LLM tool wire

Retire the introduction “Triad: Mind, Body, Language” section — replace with a link to the canonical page. Allow Mind/Body as inline aliases on skill catalog pages only if a one-line mapping is shown (“Mind = Cognition = instructions.md”).

Replace overstated phrases:

Remove / soften	Replace with
“load its mind into the agent”	“load makes Cognition available; the host wires it into system context”
“hard limits baked into Governance”	“Governance declares limits; Logic enforces guardrails; the host orders middleware chains”
“enforced at the prompt level” (constitution)	“constitution guides agents and reviewers; see trust model for enforcement boundaries”

Add one stack diagram (README + introduction + optional vision) aligned with Aura:

Brain (LLM) → Interface (tool schema) → Logic (execute) → JSON back to Brain
                    ↑ Wire: Cognition (instructions, host-injected)
Governance: declared in manifest; hard gates in Logic
Host: owns loop, composition, chaining
Aura (optional): coat around Host — audit / egress policy

---

Alternatives to consider (pick one in the PR)

Alt A — Four pillars only (minimal change)

• Keep README + website Logic / Cognition / Governance / Interface unchanged in naming.
• Fix introduction triad → four pillars; add enforcement table; fix overstatements.
• Skill pages: optional rename “Mind/Body” → “Cognition/Logic” or add mapping line.

Pros: Lowest churn; website already aligned.
Cons: “Governance” still overloaded (issuer + constitution + guardrails).

---

Alt B — Neural module (Aura-aligned branding)

• Public: Effector / Map / Ethos / Synapse / Surface with glossary mapping to files.
• README/website cards updated together.
• Explicit: Skillware bundle = Tool module in Aura stack, not “Body”.

Pros: Strong ARPA ecosystem story; fixes Aura collision.
Cons: Higher marketing churn; steeper for newcomers unless glossary is prominent.

---

Alt C — Operator model: Load / Wire / Run / Compose (usage-first)

• Philosophy pages de-emphasize pillars; docs/usage/skill_anatomy.md (or expanded introduction) teaches operations.
• Homepage keeps four cards but footnote links to anatomy + enforcement table.

Pros: Matches agent_loops.md and #297 chaining work.
Cons: Weaker marketing punch; website may still want four icons.

---

Alt D — Hybrid (recommended for vote)

• Marketing (README, skillware.site): keep Logic / Cognition / Governance / Interface four cards.
• Deep dive (docs/introduction.md rewrite): four layers + Host + enforcement table + Aura stack note.
• CONTRIBUTING + trust model: engineering vocabulary (declared vs enforced).
• Catalog pages: tolerate Mind/Body subheadings with a standard mapping block at top of Internal Architecture sections.

---

Suggested deliverables (acceptance criteria)

• grep docs/skills/*.md for Mind/Body headers — normalize or add mapping block.
• Canonical doc: rewrite docs/introduction.md — remove triad heading bug; four pillars + files + enforcement table + Host + optional Surface (card.json); fix persona injection example (align CONTRIBUTING append-only guidance).
• README.md — soften Governance “baked in”; add one-line “declared vs enforced” pointer to trust model; link canonical anatomy.
• docs/vision.md — update link text (no “triad” without mapping).
• CONTRIBUTING.md §instructions + §constitution — align enforcement language with trust model.
• Provider guides (gemini.md, claude.md, …) — keep “Mind” colloquial or add “(Cognition)” once; add note that Wire is host responsibility.
• Optional: docs/usage/skill_anatomy.md stub if introduction stays long — linked from usage README.
• Catalog template / skill_usage_template.md — standard “Internal architecture” mapping block (Logic/Cognition/Governance/Interface ↔ files).
• Website checklist (in PR description): update skillware.site four cards + any /docs routes that still say triad — same enforcement wording as README.
• CHANGELOG.md [Unreleased] docs entry.
• No code changes unless optional future SkillLoader.agent_context() is split to a separate RFC/issue.

Rationale

• One vocabulary reduces contributor drift and review bikeshedding.
• Honest enforcement language aligns marketing with skill-trust-model.md and prevents operators treating constitution YAML as sandboxing.
• Four pillars already won on README + website; introduction triad is the outlier.
• Host + Compose belongs in the anatomy before [Docs]: add dedicated skill chaining guide under docs/usage #297 chaining guide lands.
• Aura alignment avoids teaching two different meanings of “Body.”

Related issues

• [Docs]: add dedicated skill chaining guide under docs/usage #297 — skill chaining guide (should link canonical anatomy)
• Trust model / constitution docs (already correct; reference, don’t rewrite)
• Future: optional loader helper for instruction + constitution composition (separate RFC)

Out of scope for this issue:

• Framework API changes (compose_system_context, auto-inject constitution).
• Rewriting every skill catalog page Mind/Body section (follow-up grep pass acceptable as phase 2).
• Aura repo changes (link only).

Affected Page(s)

README.md docs/introduction.md docs/vision.md CONTRIBUTING.md docs/security/skill-trust-model.md (cross-link only; already correct) docs/usage/README.md docs/usage/gemini.md docs/usage/claude.md docs/usage/openai.md docs/usage/deepseek.md docs/usage/agent_loops.md docs/usage/skill_usage_template.md CHANGELOG.md skillware.site (homepage four cards + docs routes — external sync checklist)