[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6JW0SP7M016RJ8Y5KE7BQK2":3,"skill-same:01M6JW0SP7M016RJ8Y5KE7BQK2":75},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":40,"linkOnly":41,"markdownContent":42,"markdownBody":43,"frontMatter":44,"refName":45,"commitSha":46,"skillDirectory":47,"forksCount":48,"repositoryHtmlUrl":49,"repositoryHomepageUrl":50,"ownerHtmlUrl":51,"ownerBlogUrl":52,"ownerDescription":53,"updatedAt":54,"install":55,"resources":68},"01M6JW0SP7M016RJ8Y5KE7BQK2","mental-model-system-vs-interaction",null,"Use this skill when distinguishing the two mental-model types — system models (how the user thinks the system works) and interaction models (how the user thinks they should use it). Trigger when designing onboarding (which model to teach), reviewing user confusion (which model is wrong), or building documentation (which model to explain). Sub-aspect of `mental-model`; read that first.","hashgraph-online\u002Fawesome-codex-plugins","hashgraph-online","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F160371962?v=4","01M6CNB6NRJVNNGN14TR01Q6D3","HOL (Hashgraph Online)","01M6JT1HSKKG9V68KQAQGBA7XP",1575,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FHDeibler\u002Funiversal-design-principles\u002Fplugins\u002Fcognition-and-learnability-principles\u002Fskills\u002Fmental-model-system-vs-interaction\u002FSKILL.md",[],[19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39],"mental model system vs interaction","mental model","system","model","interaction","use","when","Wrong","which","types","it","trigger","models","teach","user","read","explain","how","first","onboarding","documentation","2026-11-10 10:12:30",false,"---\nname: mental-model-system-vs-interaction\ndescription: 'Use this skill when distinguishing the two mental-model types — system models (how the user thinks the system works) and interaction models (how the user thinks they should use it). Trigger when designing onboarding (which model to teach), reviewing user confusion (which model is wrong), or building documentation (which model to explain). Sub-aspect of `mental-model`; read that first.'\n---\n\n# System models vs. interaction models\n\nThe book's distinction matters in practice because the two model types are formed differently and need different design responses.\n\n## System models\n\nHow the user thinks the system works internally. Components, mechanisms, causal logic.\n\nExamples:\n\n- \"The cloud\" stores my files; they're somewhere on the internet.\n- \"The recommendation algorithm\" looks at what I clicked.\n- \"Two-factor authentication\" sends a code to verify it's me.\n\nSystem models are often inaccurate without consequence. Most users don't know how email actually routes (SMTP, MX records); their model — \"I type address, click send, message arrives\" — is sufficient. The system doesn't *need* an accurate user system model unless the user must reason about edge cases.\n\nWhen system models matter:\n\n- **Troubleshooting** — when something goes wrong, users with better system models recover faster.\n- **Privacy and security** — users with realistic models of how their data flows make better choices.\n- **Power use** — users with accurate models can use features beyond the basic.\n\nDesigners tend to have rich system models (they built it); users tend to have simplified or wrong ones. The gap is acceptable up to a point.\n\n## Interaction models\n\nHow the user thinks they should use the system. Actions, sequences, expected responses.\n\nExamples:\n\n- To save: Cmd-S or click File → Save.\n- To navigate: click links, use back button.\n- To delete: select item, press Delete or click trash icon.\n\nInteraction models are what designers must align to. A system whose interaction model the user can't form is unusable, regardless of how cleverly its system model is conceived.\n\nWhen interaction models matter:\n\n- **Always.** Every interaction is a moment when the user's interaction model is tested.\n- **Particularly** for first-use; subsequent use refines the model through experience.\n- **Critically** for destructive or irreversible actions.\n\nUsers tend to have weak interaction models initially; with use, they accumulate accurate models through trial. Designers often have weak interaction models because they know \"how it really works\" rather than \"how to use it.\" Bridging the gap requires user testing.\n\n## Asymmetry between designers and users\n\nThe book makes this point compactly: designers tend to have complete system models but weak interaction models. Users have weak system models but, with use, develop accurate interaction models.\n\nThe implication: designers can't infer the user's interaction model from their own. They must test with real users.\n\n## How to design for each\n\n### For system models\n\n- **Faithful system images** that surface the system's actual state.\n- **Conceptual onboarding** that teaches the model when accuracy matters.\n- **Documentation** that explains underlying mechanisms for users who care.\n- **Visualizations** of internal state when relevant (sync status, processing pipelines).\n\n### For interaction models\n\n- **Conventional patterns** so users transfer prior interaction models.\n- **Affordances** that signal what to do.\n- **Feedback** that confirms the action did what the user expected.\n- **Recovery** when the interaction didn't match expectation.\n\n## When to invest in which\n\nFor most products, **interaction models** are the higher-priority investment. Most users don't need accurate system models; all users need accurate interaction models.\n\nExceptions:\n\n- **Power-user tools** (developer tools, admin consoles) — power users benefit from system-model accuracy.\n- **Privacy-sensitive products** — users need to understand the system to consent meaningfully.\n- **Educational products** — teaching the system model is the point.\n\n## Worked examples\n\n### Example 1: a calendar app\n\nSystem model: events stored in a database; synced across devices via cloud.\n\nInteraction model: click date to create event; drag to move; click event to edit.\n\nMost users only need the interaction model. The system model can be opaque (\"it just syncs\"). Investment: interaction-model design and testing.\n\n### Example 2: a developer tool\n\nSystem model: code runs in a sandboxed environment; logs stream from server; deploys are versioned.\n\nInteraction model: type code in editor; click run; see output; click deploy.\n\nPower users (developers) benefit from the system model. Investment: both. The IDE's UI handles interaction; documentation, error messages, and visible state handle the system model.\n\n### Example 3: a privacy-affecting feature\n\nSystem model: data is shared with third parties for ad personalization.\n\nInteraction model: toggle in settings.\n\nUsers *must* understand the system model to consent meaningfully. Investment: clear explanation of what the toggle actually does, in plain language, at the point of decision.\n\n## Anti-patterns\n\n- **Optimizing for system-model purity at the expense of interaction usability.** \"Our metaphor is technically accurate but users can't find anything.\"\n- **Hiding the system model when users need it.** Privacy disclosures buried; sync status invisible; error messages that don't explain causes.\n- **Designer's interaction model substituted for user's.** Designers ship a clever flow that they themselves can navigate; users can't.\n\n## Heuristics\n\n1. **The \"what model do users need?\" check.** For each feature, ask: what does the user need to know about how this works (system) vs. how to use it (interaction)?\n2. **The user-test-vs-self-test.** Designers walking through their own design test the designer's model, not the user's. Watch real users.\n3. **The first-error analysis.** When a user encounters their first error, was it a system-model failure (they didn't know how it works) or interaction-model failure (they didn't know what to do)? Different fixes.\n\n## Related sub-skills\n\n- **`mental-model`** (parent).\n- **`mental-model-mismatch-and-onboarding`** — bridging the gaps when models diverge.\n- **`affordance`** — interaction models at the per-element level.\n- **`mimicry`** — borrowing models from familiar systems.\n","# System models vs. interaction models\n\nThe book's distinction matters in practice because the two model types are formed differently and need different design responses.\n\n## System models\n\nHow the user thinks the system works internally. Components, mechanisms, causal logic.\n\nExamples:\n\n- \"The cloud\" stores my files; they're somewhere on the internet.\n- \"The recommendation algorithm\" looks at what I clicked.\n- \"Two-factor authentication\" sends a code to verify it's me.\n\nSystem models are often inaccurate without consequence. Most users don't know how email actually routes (SMTP, MX records); their model — \"I type address, click send, message arrives\" — is sufficient. The system doesn't *need* an accurate user system model unless the user must reason about edge cases.\n\nWhen system models matter:\n\n- **Troubleshooting** — when something goes wrong, users with better system models recover faster.\n- **Privacy and security** — users with realistic models of how their data flows make better choices.\n- **Power use** — users with accurate models can use features beyond the basic.\n\nDesigners tend to have rich system models (they built it); users tend to have simplified or wrong ones. The gap is acceptable up to a point.\n\n## Interaction models\n\nHow the user thinks they should use the system. Actions, sequences, expected responses.\n\nExamples:\n\n- To save: Cmd-S or click File → Save.\n- To navigate: click links, use back button.\n- To delete: select item, press Delete or click trash icon.\n\nInteraction models are what designers must align to. A system whose interaction model the user can't form is unusable, regardless of how cleverly its system model is conceived.\n\nWhen interaction models matter:\n\n- **Always.** Every interaction is a moment when the user's interaction model is tested.\n- **Particularly** for first-use; subsequent use refines the model through experience.\n- **Critically** for destructive or irreversible actions.\n\nUsers tend to have weak interaction models initially; with use, they accumulate accurate models through trial. Designers often have weak interaction models because they know \"how it really works\" rather than \"how to use it.\" Bridging the gap requires user testing.\n\n## Asymmetry between designers and users\n\nThe book makes this point compactly: designers tend to have complete system models but weak interaction models. Users have weak system models but, with use, develop accurate interaction models.\n\nThe implication: designers can't infer the user's interaction model from their own. They must test with real users.\n\n## How to design for each\n\n### For system models\n\n- **Faithful system images** that surface the system's actual state.\n- **Conceptual onboarding** that teaches the model when accuracy matters.\n- **Documentation** that explains underlying mechanisms for users who care.\n- **Visualizations** of internal state when relevant (sync status, processing pipelines).\n\n### For interaction models\n\n- **Conventional patterns** so users transfer prior interaction models.\n- **Affordances** that signal what to do.\n- **Feedback** that confirms the action did what the user expected.\n- **Recovery** when the interaction didn't match expectation.\n\n## When to invest in which\n\nFor most products, **interaction models** are the higher-priority investment. Most users don't need accurate system models; all users need accurate interaction models.\n\nExceptions:\n\n- **Power-user tools** (developer tools, admin consoles) — power users benefit from system-model accuracy.\n- **Privacy-sensitive products** — users need to understand the system to consent meaningfully.\n- **Educational products** — teaching the system model is the point.\n\n## Worked examples\n\n### Example 1: a calendar app\n\nSystem model: events stored in a database; synced across devices via cloud.\n\nInteraction model: click date to create event; drag to move; click event to edit.\n\nMost users only need the interaction model. The system model can be opaque (\"it just syncs\"). Investment: interaction-model design and testing.\n\n### Example 2: a developer tool\n\nSystem model: code runs in a sandboxed environment; logs stream from server; deploys are versioned.\n\nInteraction model: type code in editor; click run; see output; click deploy.\n\nPower users (developers) benefit from the system model. Investment: both. The IDE's UI handles interaction; documentation, error messages, and visible state handle the system model.\n\n### Example 3: a privacy-affecting feature\n\nSystem model: data is shared with third parties for ad personalization.\n\nInteraction model: toggle in settings.\n\nUsers *must* understand the system model to consent meaningfully. Investment: clear explanation of what the toggle actually does, in plain language, at the point of decision.\n\n## Anti-patterns\n\n- **Optimizing for system-model purity at the expense of interaction usability.** \"Our metaphor is technically accurate but users can't find anything.\"\n- **Hiding the system model when users need it.** Privacy disclosures buried; sync status invisible; error messages that don't explain causes.\n- **Designer's interaction model substituted for user's.** Designers ship a clever flow that they themselves can navigate; users can't.\n\n## Heuristics\n\n1. **The \"what model do users need?\" check.** For each feature, ask: what does the user need to know about how this works (system) vs. how to use it (interaction)?\n2. **The user-test-vs-self-test.** Designers walking through their own design test the designer's model, not the user's. Watch real users.\n3. **The first-error analysis.** When a user encounters their first error, was it a system-model failure (they didn't know how it works) or interaction-model failure (they didn't know what to do)? Different fixes.\n\n## Related sub-skills\n\n- **`mental-model`** (parent).\n- **`mental-model-mismatch-and-onboarding`** — bridging the gaps when models diverge.\n- **`affordance`** — interaction models at the per-element level.\n- **`mimicry`** — borrowing models from familiar systems.\n",{"name":5,"description":7},"main","b0f0a87593c578a7898eccaf1b363f7f87c1f99b","plugins\u002FHDeibler\u002Funiversal-design-principles\u002Fplugins\u002Fcognition-and-learnability-principles\u002Fskills\u002Fmental-model-system-vs-interaction",491,"https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins","https:\u002F\u002Fhol.org\u002Fplugins\u002Fbest-codex-plugins","https:\u002F\u002Fgithub.com\u002Fhashgraph-online","https:\u002F\u002Fhol.org","Open-source standards and developer tools for interoperable AI agents: discovery, identity, communication, payments, privacy and security.","2026-11-14 14:06:13",{"source":8,"skillName":5,"commands":56,"prompt":66,"zipAvailable":67},[57,60,63],{"tool":58,"command":59},"npx","npx skills add hashgraph-online\u002Fawesome-codex-plugins --skill mental-model-system-vs-interaction",{"tool":61,"command":62},"bunx","bunx skills add hashgraph-online\u002Fawesome-codex-plugins --skill mental-model-system-vs-interaction",{"tool":64,"command":65},"pnpm","pnpm dlx skills add hashgraph-online\u002Fawesome-codex-plugins --skill mental-model-system-vs-interaction","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FHDeibler\u002Funiversal-design-principles\u002Fplugins\u002Fcognition-and-learnability-principles\u002Fskills\u002Fmental-model-system-vs-interaction\u002FSKILL.md",true,[69],{"path":70,"resourceType":71,"resourceTypeDesc":72,"sizeBytes":73,"sourceHtmlUrl":74},"references\u002Ftwo-models-research.md","REFERENCE","参考文档",1609,"https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FHDeibler\u002Funiversal-design-principles\u002Fplugins\u002Fcognition-and-learnability-principles\u002Fskills\u002Fmental-model-system-vs-interaction\u002Freferences\u002Ftwo-models-research.md",[76,86,94,102,110,118],{"skillNo":77,"name":78,"nameZh":6,"description":79,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":80,"licenseFileUrl":81,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":85},"01M7DV332YQMGD8WTRJ9DZQXTB","worktable-review-with-annotations","Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.","MIT","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-review-with-annotations\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-review-with-annotations\u002FSKILL.md",[],[],"2026-11-15 14:19:17",{"skillNo":87,"name":88,"nameZh":6,"description":89,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":80,"licenseFileUrl":90,"sourceHtmlUrl":91,"categories":92,"keywords":93,"publishedAt":85},"01M7DV2YGHCZVBEB1AHYB6CGHE","worktable-find-and-synthesize-context","Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-find-and-synthesize-context\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-find-and-synthesize-context\u002FSKILL.md",[],[],{"skillNo":95,"name":96,"nameZh":6,"description":97,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":80,"licenseFileUrl":98,"sourceHtmlUrl":99,"categories":100,"keywords":101,"publishedAt":85},"01M7DV2TQN1H11ME2SAF9MXN7V","worktable-create-or-update-docs","Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-update-docs\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-update-docs\u002FSKILL.md",[],[],{"skillNo":103,"name":104,"nameZh":6,"description":105,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":80,"licenseFileUrl":106,"sourceHtmlUrl":107,"categories":108,"keywords":109,"publishedAt":85},"01M7DV2NE452NEA8TXATKSNAJH","worktable-create-or-manage-records","Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-manage-records\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-manage-records\u002FSKILL.md",[],[],{"skillNo":111,"name":112,"nameZh":6,"description":113,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":80,"licenseFileUrl":114,"sourceHtmlUrl":115,"categories":116,"keywords":117,"publishedAt":85},"01M7DV2HENRBR2KSCVM064WH0Y","worktable-create-or-manage-interactive-html","Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-manage-interactive-html\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-manage-interactive-html\u002FSKILL.md",[],[],{"skillNo":119,"name":120,"nameZh":6,"description":121,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":80,"licenseFileUrl":122,"sourceHtmlUrl":123,"categories":124,"keywords":125,"publishedAt":85},"01M7DV2CADR5R7RQFFYPNAGR9Y","worktable-collaborate-threads","Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-collaborate-threads\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-collaborate-threads\u002FSKILL.md",[],[]]