@skill-graph/cli 0.5.6

package/marketplace/skills/security-fundamentals/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: security-fundamentals
+description: "Use when reasoning about the security properties any application must satisfy: threat modeling (assets, threats, adversaries, surfaces), Saltzer and Schroeder's eight design principles (1975), input validation discipline, authentication vs authorization, secrets handling, secure-by-default, least-privilege, the OWASP Top 10 as recurring vulnerability classes, and defense in depth. Covers cross-cutting decisions about trust boundaries, where validation belongs, where authn/authz checks live, and how to bound blast radius. Do NOT use for LLM-specific prompt-injection (use prompt-injection-defense), cryptographic primitive implementation (use vendor libs), security-scanning tools (use security-scanning), credential-encryption schemes (use credential-encryption), GDPR/regulatory compliance (use gdpr-compliance), or the social/organizational side of security (out of scope)."
+license: MIT
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"quality\",\"domain\":\"quality/security\",\"scope\":\"reference\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-16\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-16\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"comprehension_state\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"security fundamentals\\\\\\\",\\\\\\\"threat modeling\\\\\\\",\\\\\\\"input validation\\\\\\\",\\\\\\\"authentication\\\\\\\",\\\\\\\"authorization\\\\\\\",\\\\\\\"authn\\\\\\\",\\\\\\\"authz\\\\\\\",\\\\\\\"least privilege\\\\\\\",\\\\\\\"defense in depth\\\\\\\",\\\\\\\"secure by default\\\\\\\",\\\\\\\"OWASP Top 10\\\\\\\",\\\\\\\"Saltzer and Schroeder\\\\\\\",\\\\\\\"secrets handling\\\\\\\",\\\\\\\"attack surface\\\\\\\",\\\\\\\"trust boundary\\\\\\\",\\\\\\\"principle of least privilege\\\\\\\"]\",\"triggers\":\"[\\\\\\\"is this secure\\\\\\\",\\\\\\\"where should validation happen\\\\\\\",\\\\\\\"authentication vs authorization\\\\\\\",\\\\\\\"what could go wrong here\\\\\\\",\\\\\\\"threat model\\\\\\\",\\\\\\\"OWASP\\\\\\\",\\\\\\\"do I need to check permissions here\\\\\\\"]\",\"examples\":\"[\\\\\\\"audit a route handler for authn, authz, and input validation\\\\\\\",\\\\\\\"decide where to validate inbound data when the same shape comes in through multiple endpoints\\\\\\\",\\\\\\\"decide whether a piece of data is a secret, a credential, or non-sensitive — and what handling each requires\\\\\\\",\\\\\\\"produce a threat model for a new feature before any code is written\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"implement HMAC verification for a Shopify webhook (use webhook-integration)\\\\\\\",\\\\\\\"configure a SAST scanner for the CI pipeline (use security-scanning)\\\\\\\",\\\\\\\"store an OAuth refresh token in an encrypted column (use credential-encryption)\\\\\\\",\\\\\\\"respond to a GDPR data-subject-access request (use gdpr-compliance)\\\\\\\",\\\\\\\"defend an LLM agent against prompt injection (use prompt-injection-defense)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"type-safety\\\\\\\",\\\\\\\"api-design\\\\\\\",\\\\\\\"http-semantics\\\\\\\",\\\\\\\"prompt-injection-defense\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"type-safety\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"type-safety provides compile-time guarantees about the SHAPE of data inside the program; security-fundamentals provides the runtime discipline that decides what to trust and what to validate at the system's TRUST BOUNDARIES. The two compose: validate at the boundary, then trust the type inside.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"api-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"api-design owns the external surface contract (endpoints, methods, schemas); this skill owns the security properties any such surface must enforce regardless of design choices (authn, authz, input validation, rate limiting).\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"prompt-injection-defense\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"prompt-injection-defense owns the LLM-specific threat class where untrusted text is interpreted as instructions by a model; this skill owns the general security framing that prompt injection specializes from. Prompt injection is one row in the OWASP LLM Top 10; this skill covers the broader discipline.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"http-semantics\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"http-semantics owns the protocol-level meaning of methods, status codes, and headers; this skill owns the security properties that protocol must enforce at every endpoint (authn, authz, rate limiting, validation). They compose: HTTP gives the protocol; this skill gives the security discipline applied to it.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"type-safety\\\\\\\",\\\\\\\"api-design\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"Security fundamentals is to a software system what structural engineering is to a building — load-bearing walls, fire egress, electrical isolation, foundation depth are not features added after the building works; they are properties of the design from the first sketch, and retrofitting them costs ten times more and produces worse results than designing them in. A building that survives an earthquake does so because of decisions made at the structural-engineering stage, not because of decorations added later.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"Security fundamentals are the cross-cutting design principles, threat-modeling discipline, and recurring vulnerability classes that determine whether a system can be trusted to handle data, identity, and authority safely under adversarial conditions. The discipline is upstream of any specific vulnerability or vendor tool: it asks 'what are we protecting,' 'from whom,' 'what could go wrong,' and 'what's the cost if it does' before any implementation choice is made. Security fundamentals are not a feature added after the system works; they are a property of the design from the first commit, encoded in trust boundaries, validation choices, default permissions, and the placement of authentication and authorization checks. The discipline acknowledges that perfect security is impossible (any system can be attacked given sufficient resources and time), so the goal is to make attacks expensive, traceable, and limited in blast radius — defense in depth rather than perimeter security, least privilege rather than convenience, secure defaults rather than opt-in protections.\\\\\\\",\\\\\\\"mental_model\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"purpose\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"boundary\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"taxonomy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"analogy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"misconception\\\\\\\":\\\\\\\"|\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/security-fundamentals/SKILL.md\",\"skill_graph_export_description\":\"shortened for Agent Skills 1024-character description limit; canonical source keeps the full routing contract\",\"skill_graph_canonical_description_length\":\"1212\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/security-fundamentals/SKILL.md
+---
+
+# Security Fundamentals
+
+## Coverage
+
+The cross-cutting design principles, threat-modeling discipline, and recurring vulnerability classes that determine whether a system can safely handle data, identity, and authority under adversarial conditions. Covers the foundational discipline upstream of any specific vulnerability or tool: Shostack's four threat-modeling questions, Saltzer and Schroeder's eight design principles (1975), trust boundaries, the authentication/authorization distinction, input validation as a boundary discipline, defense in depth, least privilege, and the OWASP Top 10 as a working enumeration of recurring failure classes. Does NOT cover the implementation of specific cryptographic primitives, the configuration of specific scanners, the regulatory artifacts of compliance regimes, the LLM-specific specialization to prompt injection, or the organizational/social side of security.
+
+## Philosophy
+
+Security is a property of the design, not a feature added after the system works. The cost of designing security in is small; the cost of retrofitting it is order-of-magnitude larger and produces worse results. The discipline of security fundamentals is the discipline of paying these costs early — at the threat-modeling stage, at the trust-boundary stage, at the authentication-design stage — before the system has accumulated the structural debt that makes retrofitting expensive.
+
+The discipline does not promise prevention of attacks. Any non-trivial system will be attacked; some attacks will succeed. The goal is to make attacks expensive, slow, traceable, and limited in blast radius. Every design choice is evaluated by what it costs the defender vs what it costs the attacker. Secure-by-default choices cost the defender slightly more code upfront but cost the attacker a working exploit; opt-in security features cost the defender nothing upfront but cost the attacker very little when the developer inevitably forgets. The discipline is the deliberate placement of costs on the attacker rather than the defender.
+
+For agents writing code, the discipline is what lets the agent reason about a security-relevant change without having to read the entire system. An agent that knows the trust boundaries, the authn/authz distinction, and the input-validation discipline can look at a new endpoint and ask: 'where is this endpoint receiving data from?' 'Is the data validated at the boundary?' 'Is authentication checked?' 'Is authorization checked at the moment of the privileged action?' 'What's the blast radius if any of these fail?' These questions produce the right code without the agent having to recall every OWASP entry.
+
+## The Four Threat-Modeling Questions (Shostack)
+
+| Question | What it produces | Common failure |
+|---|---|---|
+| **What are we working on?** | The system diagram, asset inventory, data classification, trust boundaries | Skipped; analysis proceeds against an unstated model |
+| **What can go wrong?** | The threat list: STRIDE categories, attacker scenarios, abuse cases | Jumped to mitigation without enumerating threats |
+| **What are we going to do about it?** | The mitigations: design choices, controls, monitoring | The bulk of effort goes here; without the first two, mitigations are random |
+| **Did we do a good job?** | Verification: tests, reviews, ongoing monitoring | Declared without testing; threat model never revisited |
+
+A team that answers all four iteratively, with each system change, is doing security fundamentals. A team that answers only three, or answers them once, is doing security theater.
+
+## Saltzer & Schroeder's Eight Principles (1975)
+
+These predate every modern technology and remain canonical because they describe properties, not implementations.
+
+| Principle | One-line gloss | What it forbids |
+|---|---|---|
+| **Economy of mechanism** | Keep it simple | Sprawling, complex security architectures with many components |
+| **Fail-safe defaults** | Deny by default; permit by exception | "is_admin defaults to true" patterns |
+| **Complete mediation** | Check every access; never cache "I checked this earlier" | First-request-only auth checks; trust-on-session |
+| **Open design** | Don't depend on secrecy of the design (Kerckhoffs) | Security through obscurity; secret algorithms |
+| **Separation of privilege** | Require multiple independent conditions for sensitive operations | Single-credential vault access for irreversible actions |
+| **Least privilege** | Minimum permissions per entity | Service accounts with admin keys; over-scoped tokens |
+| **Least common mechanism** | Minimize shared mechanism across users | Global state that leaks information between requests |
+| **Psychological acceptability** | Security users will bypass is not security | Onerous policies that drive workarounds (sticky-note passwords) |
+
+## The Authn / Authz Distinction
+
+| Concern | Question it answers | Verified by | Where it lives | When it runs |
+|---|---|---|---|---|
+| **Authentication** | "Who are you?" | Credentials (password, token, certificate, MFA) | Auth middleware, login flow | At session establishment |
+| **Authorization** | "Are you allowed to do this?" | Policy against identity (RBAC, ABAC, ACLs) | At every privileged action | Every request to a protected resource |
+
+Conflating these is the #1 issue in the OWASP Top 10. The pattern: authenticate at the entry point; authorize at every privileged action. Never short-circuit authorization on the basis of having a valid session.
+
+## Input Validation As Boundary Discipline
+
+The pattern, in order:
+
+1. **Define expectations.** Every input has an explicit shape, range, and meaning expectation. Document it as a schema (Zod, JSON Schema, OpenAPI).
+2. **Validate at the boundary.** Validation happens at the entry point of the request, not three function calls in. The earlier validation fails, the less the system has done with bad data.
+3. **Parse, don't validate (Alexis King).** Convert the untrusted value into a typed, validated value once; trust the typed form everywhere downstream. This composes with `type-safety` — the type system carries the validation forward.
+4. **Treat validation failure as a response-shaped outcome.** Return a structured error (400 Bad Request with field-level detail) rather than throwing in the middle of business logic.
+5. **Log validation failures.** Repeated validation failures from a specific source may be probing for vulnerabilities; logged failures feed monitoring.
+
+| Boundary | Untrusted source | Validation discipline |
+|---|---|---|
+| User → application | HTTP request bodies, form inputs, query params, headers | Schema-based parsing at the entry point |
+| External API → application | Webhook payloads, third-party responses, OAuth callbacks | Signature verification + schema validation |
+| Database → application | (Trust your DB, but validate cross-tenant) | Org-scoped queries; row-level security |
+| Client → server (API) | API requests | Schema validation + authn + authz |
+| Process boundary (microservices) | Inter-service calls | mTLS or signed tokens + schema validation |
+| Untrusted file → application | Uploaded files | Type detection, size limits, sandbox parsing |
+| LLM → application (tool calls) | Tool arguments produced by LLM | Treat as untrusted; validate against tool schema |
+
+## Defense In Depth — Layered Controls
+
+| Layer | Purpose | Failure mode when missing |
+|---|---|---|
+| **Network** | Firewall, segmentation, WAF | Direct exposure of internal services to internet |
+| **Identity** | Authn, MFA, SSO | Credential stuffing, account takeover |
+| **Application authz** | RBAC/ABAC, per-action checks | Broken access control (OWASP A01) |
+| **Input validation** | Schema parse, sanitize | Injection (OWASP A03) |
+| **Data encryption** | At-rest, in-transit, end-to-end | Cryptographic failure (OWASP A02) |
+| **Output encoding** | Escape on output (XSS, log forging) | XSS, log poisoning |
+| **Rate limiting** | Throttling, anomaly detection | Brute force, scraping, DoS |
+| **Logging & monitoring** | Audit trails, alerts | Undetected breach (OWASP A09) |
+| **Incident response** | Playbooks, forensics, recovery | Slow response when attacks succeed |
+
+The property of defense in depth is the *composition* — no single layer is the security; the security is what remains when one layer fails.
+
+## Verification
+
+After applying this skill, verify:
+- [ ] A threat model exists for the system or feature, answering all four Shostack questions; it is dated and reviewed at meaningful intervals.
+- [ ] Trust boundaries are explicitly enumerated; each boundary has a validation discipline applied.
+- [ ] Authentication is required at every entry point that needs identity; authorization is checked at every privileged action — not just at session start.
+- [ ] Input validation happens at the trust boundary, returns structured errors, and is logged.
+- [ ] Sensitive data has been classified (public, internal, confidential, restricted, secrets); each tier has handling rules; secrets are never logged or stored unencrypted.
+- [ ] Service-to-service calls use mTLS or signed tokens; no service trusts another solely on network position.
+- [ ] Defaults are fail-safe (deny by default; permit by explicit exception with justification).
+- [ ] Every entity (user, service, process) has minimum-necessary permissions; service accounts do not have admin keys; tokens are scoped to the minimum action set.
+- [ ] Sensitive actions are logged with sufficient detail to reconstruct what happened; logs are protected from modification.
+- [ ] Monitoring is in place to detect anomalies and failed validations; alerts are tested.
+- [ ] Cryptographic primitives are implemented by well-reviewed libraries, not custom code; keys are managed (rotation, escrow, scoped access).
+- [ ] Compliance documentation (where applicable) is downstream of the security property, not a substitute for it.
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Defending an LLM agent against prompt injection | `prompt-injection-defense` | prompt-injection-defense owns the LLM-specific specialization; this skill is the broader framing |
+| Encrypting stored credentials (envelope encryption, KMS) | `credential-encryption` | credential-encryption owns the specific patterns for stored secrets |
+| Choosing and configuring a SAST/DAST/dependency scanner | `security-scanning` | security-scanning owns the tooling discipline |
+| GDPR / data-subject rights / regulatory artifacts | `gdpr-compliance` | gdpr-compliance owns the legal framing of data protection; this skill owns the underlying security |
+| Implementing a specific cryptographic primitive (AES, RSA, hashing) | Well-reviewed crypto library docs (libsodium, BouncyCastle, native APIs) | Implementation is library territory; this skill is upstream of "which primitive" |
+| Webhook signature verification for a specific platform (Shopify, Stripe) | `webhook-integration` | webhook-integration owns vendor-specific patterns; this skill provides the framing |
+| Social engineering, phishing, organizational security awareness | (no skill — out of scope) | Organizational security is a separate discipline |
+| Penetration testing methodology | (no skill — out of scope) | A specialized professional discipline |
+
+## Key Sources
+
+- Saltzer, J. H., & Schroeder, M. D. (1975). ["The Protection of Information in Computer Systems"](https://www.cs.virginia.edu/~evans/cs551/saltzer/). *Proceedings of the IEEE, 63*(9), 1278–1308. The foundational paper on security design principles; the eight principles articulated here remain canonical across every subsequent technology shift.
+- Shostack, A. (2014). *Threat Modeling: Designing for Security*. Wiley. The canonical modern reference on threat modeling, including the four-question framework and STRIDE (Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege).
+- OWASP. [OWASP Top 10 (2021)](https://owasp.org/Top10/). The most-cited working enumeration of recurring web application vulnerability classes; updated periodically as the threat landscape shifts.
+- OWASP. [OWASP Top 10 for LLM Applications](https://owasp.org/www-project-top-10-for-large-language-model-applications/). The LLM-specific specialization, including prompt injection (LLM01), excessive agency (LLM08), and insecure plugin design (LLM07).
+- Anderson, R. (2020). *Security Engineering: A Guide to Building Dependable Distributed Systems* (3rd ed.). Wiley. The comprehensive treatment of security engineering across cryptography, access control, authentication, and large-system architecture; the discipline's modern textbook.
+- Kerckhoffs, A. (1883). "La cryptographie militaire." *Journal des sciences militaires*, IX, 5–83. The foundational articulation of "security must not depend on the secrecy of the design" — the principle Saltzer & Schroeder generalized as "open design."
+- NIST. [Special Publication 800-63B: Digital Identity Guidelines — Authentication and Lifecycle Management](https://pages.nist.gov/800-63-3/sp800-63b.html). The reference standard for authentication: password requirements, MFA categorization (memorized secrets, OOB devices, OTPs, cryptographic keys), session management.
+- Lampson, B. W. (1973). "A Note on the Confinement Problem." *Communications of the ACM, 16*(10), 613–615. The foundational paper on confinement — the question of whether a program can be prevented from leaking information it has access to.
+- King, A. (2019). ["Parse, don't validate"](https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate/). Modern articulation of the validation discipline: convert untrusted data to typed values once at the boundary, then trust the type.
+- Bell, D. E., & LaPadula, L. J. (1973). "Secure Computer Systems: Mathematical Foundations." MITRE technical report. The Bell-LaPadula model — foundational work on formal access-control models that underpin modern RBAC/ABAC systems.

package/marketplace/skills/semantic-center/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: semantic-center
+description: "Use when you need to explain how parts of a system, feature, concept, page, workflow, or problem connect; identify the single most important part of something; untangle dense dependencies into a core plus typed relations; or answer 'what is the load-bearing part?' without drifting into implementation or task prioritization. Provides a five-step workflow — classify the unit of analysis, find the single primary part using removal/governance/purpose/weight/decision tests, map secondary parts via typed relations (dependency, input/output, parent/child, owner/owned, cause/effect, constraint/enabler, and others), produce a structured output, and reduce the whole to one final sentence — that forces explanation through one-primary reduction rather than flat lists or chronology. Do NOT use for implementation work (use the relevant domain skill), choosing what to do next (use a prioritization skill), or formal architectural-ownership design (use a domain-modeling skill)."
+license: MIT
+compatibility: "Domain-agnostic explanation method. The five-step workflow, the five primary-part tests, and the typed-relation taxonomy apply to systems, features, modules, workflows, concepts, decisions, or problems in any stack — substitute the relevant domain vocabulary for the structural skeleton."
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"workflow\",\"category\":\"foundations\",\"domain\":\"foundations/semantics\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-06\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-06\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"semantic center\\\\\\\",\\\\\\\"semantic-center workflow\\\\\\\",\\\\\\\"one-primary-part reduction\\\\\\\",\\\\\\\"removal test\\\\\\\",\\\\\\\"governance test\\\\\\\",\\\\\\\"load-bearing part\\\\\\\",\\\\\\\"typed relation map\\\\\\\",\\\\\\\"center-finding method\\\\\\\",\\\\\\\"structural importance\\\\\\\",\\\\\\\"single primary part\\\\\\\",\\\\\\\"figure-ground reduction\\\\\\\",\\\\\\\"explanation structure\\\\\\\",\\\\\\\"relation typing rules\\\\\\\",\\\\\\\"supporting-relation map\\\\\\\",\\\\\\\"analysis-vs-prioritization distinction\\\\\\\"]\",\"examples\":\"[\\\\\\\"what is the most important part of this dashboard, and how do the surrounding widgets relate to it?\\\\\\\",\\\\\\\"explain how the order, fulfillment, and payment systems relate — what is the semantic center of that flow?\\\\\\\",\\\\\\\"break down the query-tier system; what is the governing part and how do the others depend on it?\\\\\\\",\\\\\\\"we need to understand the onboarding flow, not implement it — what is the primary part and how do the steps relate around it?\\\\\\\",\\\\\\\"a skill system has frontmatter, body, and references — which part is the semantic center, and what roles do the others play?\\\\\\\",\\\\\\\"untangle these dense module dependencies into one core plus typed relations\\\\\\\",\\\\\\\"explain at a high level how this system hangs together\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"implement the new chart component for the reports page\\\\\\\",\\\\\\\"which task should I work on next from the board?\\\\\\\",\\\\\\\"design bounded contexts and aggregate ownership for the domain\\\\\\\",\\\\\\\"review this PR for code quality and missing tests\\\\\\\",\\\\\\\"decide kebab-case vs camelCase for new database columns\\\\\\\",\\\\\\\"rewrite this UI button label to be specific and action-oriented\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"task-analysis\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"task-analysis decomposes a route or flow around the user's top task and friction dimensions (UX-goal-driven decomposition); semantic-center decomposes a system or concept around its single load-bearing part (structural-importance reduction) — the same 'what's the primary thing on this page?' prompt routes by whether the lens is the user's goal or the structural importance of the parts\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"conceptual-modeling\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"conceptual-modeling builds out a full concept structure (entities, attributes, relationships, invariants); semantic-center reduces a concept structure to one primary part plus typed relations to it — the same 'how do these concepts relate?' prompt routes by whether the user wants the full model or the load-bearing reduction\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"pattern-recognition\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"pattern-recognition surfaces recurring pattern classes across many instances; semantic-center forces one-primary reduction within a single instance — the same 'how does this hang together?' prompt routes by whether the unit of analysis is many instances (pattern) or one instance (center)\\\\\\\"}],\\\\\\\"related\\\\\\\":[\\\\\\\"intent-recognition\\\\\\\",\\\\\\\"diagnosis\\\\\\\",\\\\\\\"knowledge-modeling\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"code-review\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":365,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/semantic-center/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/semantic-center/SKILL.md
+---
+
+# Semantic Center
+
+## Coverage
+
+A structured explanatory workflow for identifying the *semantic center* of any system, feature, concept, page, workflow, decision, or problem and mapping how surrounding parts relate to it. Covers (1) **unit-of-analysis classification** (system / feature / module / page / workflow / concept / data model / decision / problem); (2) **primary-part identification** via the five tests (removal, governance, purpose, weight, decision) ranked by priority; (3) **typed secondary-part relation mapping** using a fixed taxonomy of relation types (dependency, input/output, parent/child, source/consumer, cause/effect, owner/owned, trigger/result, semantic grouping, constraint/enabler, sequence/timeline, contrast/tradeoff); (4) **structured-output production** following a fixed skeleton; and (5) **final one-sentence reduction** in a fixed grammatical form. Includes a "codebase analysis mode" overlay for analyzing a real implementation surface (grep, read primary file, follow data path, read tests) and an anti-pattern catalog (everything-is-important flattening, visibility-as-importance, proximity-as-relation, chronology-instead-of-structure, symmetric-relation blur).
+
+## Philosophy
+
+Most explanations fail because they present everything at the same weight. A user asks "how does this work?" and receives a chronological walkthrough or a laundry list, neither of which tells them what the system *depends on*. Until one part is named as load-bearing, the explanation is not structurally useful — the reader still has to do the reduction work themselves.
+
+The core rule is: **prefer one primary part and typed supporting relations over multiple co-equal "important" parts.** When more than one thing seems important, the removal test or the governance test usually breaks the tie. If it doesn't, state the tension explicitly rather than hiding it behind a list. The five-step workflow exists to force that reduction every time, not as an aesthetic preference but as a structural one.
+
+This skill is for *explanation*, not for execution. It tells you which part of a system carries the most semantic load. It does not tell you which task to start next (a prioritization concern), how to design the bounded contexts and aggregates of the system (a domain-modeling concern), or how to implement any of it (a domain skill concern).
+
+## Workflow
+
+The skill is the five-step workflow below. Each step produces explicit output. Steps run in order; a missing step downstream usually means the analysis short-circuited at the previous step.
+
+```text
+Step 1: Classify the unit of analysis
+Step 2: Find the single most important part
+Step 3: Map secondary parts in relation to the primary part
+Step 4: Produce the structured output
+Step 5: Reduce to one sentence
+```
+
+### Step 1 — Classify the Unit of Analysis
+
+Before analyzing, explicitly state what kind of thing this is. The category shapes which relation types and tests are most likely to matter.
+
+| Category | Examples |
+|----------|---------|
+| **System** | Auth pipeline, reconciliation engine, webhook chain |
+| **Feature** | Order detail page, onboarding flow, CSV export |
+| **Module** | Financial calculator, query-tier system, skill injector |
+| **Page / Screen** | Dashboard, orders list, settings page |
+| **Workflow** | Deploy pipeline, PR review cycle, task protocol |
+| **Concept** | Data provenance, margin calculation, multi-tenancy |
+| **Data model** | Order → line items → costs |
+| **Decision** | Build vs buy, monolith vs microservice |
+| **Problem** | Race condition, data inconsistency, bottleneck |
+
+**Rule:** say explicitly, "This is a [category]." If you cannot pick a category, the unit of analysis is too vague — narrow it before continuing.
+
+### Step 2 — Find the Primary Part
+
+Use these tests, in priority order. The first test that produces a clear winner is the test you cite.
+
+| Test | Question | What it reveals |
+|------|----------|----------------|
+| **Removal test** | If removed, what breaks first? | Load-bearing dependency |
+| **Governance test** | What constrains or governs the rest? | Authority source |
+| **Purpose test** | What best explains the point of the whole? | Semantic anchor |
+| **Weight test** | What carries the most semantic load? | Core concept |
+| **Decision test** | What anchors downstream choices? | Decision root |
+
+**Rules:**
+
+- Prefer one primary part. If the removal test is genuinely tied between two, name the tie explicitly rather than hiding it behind a list.
+- Distinguish importance from visibility — the loudest element is not necessarily the most load-bearing.
+- Distinguish importance from recency — the most recently changed part is rarely the semantic center.
+
+### Step 3 — Map Secondary Parts
+
+List secondary parts only in relation to the primary part. Every secondary part must have an explicit relation type from the taxonomy below.
+
+| Relation Type | Meaning |
+|--------------|---------|
+| **dependency** | Secondary depends on the primary |
+| **input/output** | Primary consumes or produces the secondary |
+| **parent/child** | Structural containment |
+| **source/consumer** | Data or event flow direction |
+| **cause/effect** | Causal chain |
+| **owner/owned** | Authority relationship |
+| **trigger/result** | Event-driven relationship |
+| **semantic grouping** | Family of concepts around the center |
+| **constraint/enabler** | What limits or unlocks the primary |
+| **sequence/timeline** | Temporal ordering only when no stronger structural relation exists |
+| **contrast/tradeoff** | Competing alternative or tension |
+
+**Rules:**
+
+- Every secondary part must have an explicit relation type from this list.
+- Proximity is not a relation. Two parts being "near each other" in the codebase is not a structural relationship — name the actual relation or drop the part.
+- Chronology is not enough when a stronger structural relation exists. Use sequence/timeline only as a last resort.
+- Symmetric "A and B both explain each other" is not allowed — choose the dominant direction.
+
+### Step 4 — Structured Output
+
+Use this output skeleton verbatim. Each `H2:` label below becomes a real `##` heading in the produced analysis document.
+
+```text
+H2: Unit of Analysis
+    [Category]: [Name]
+
+H2: Primary Part
+    [Name of the single most important part]
+
+H2: Why This Is the Primary Part
+    [Which test(s) it passes and why]
+
+H2: Secondary Parts
+    - [Part A] — [role]
+    - [Part B] — [role]
+
+H2: Relation Map
+    - Primary → Part A: [relation type] — [explanation]
+    - Part B → Primary: [relation type] — [explanation]
+
+H2: Simplest Explanation
+    [2-3 sentences]
+
+H2: Important Distinction
+    [What people most often confuse]
+
+H2: Common Misunderstanding
+    [What goes wrong and why]
+
+H2: Naming Recommendation
+    [If naming is misleading, suggest better names]
+```
+
+### Step 5 — Final Reduction
+
+End with exactly one sentence in this form:
+
+> The core is **[X]**, and everything else matters because it [supports / depends on / constrains / expresses / feeds / consumes] **X**.
+
+If you cannot write this sentence in one line, the analysis is not yet finished — return to Step 2.
+
+### Codebase Analysis Mode (Overlay)
+
+When the unit of analysis is a real repo surface rather than a pure concept, add these steps before Step 2:
+
+1. Grep for the entity or surface name across the codebase.
+2. Read the primary implementation file.
+3. Follow the data or event path one hop in each direction.
+4. Read tests if they exist.
+
+Then add to the structured output:
+
+- `## Key Files` — list the files that participate in the analyzed unit
+- `## Verified Against` — list the artifacts that confirmed the analysis (grep results, test names, log lines)
+
+### Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|--------------|---------|-----|
+| **"Everything is important"** | No real reduction happened | Apply the removal test rigorously |
+| **Visibility = importance** | The loudest element gets mistaken for the most load-bearing | Ask what breaks if it disappears |
+| **Relation = proximity** | Nearby parts get treated as semantically connected | Name the actual relation type or drop the part |
+| **Chronology instead of structure** | Timeline replaces architecture | Map dependencies and constraints first; use timeline only as last resort |
+| **Symmetric relation blur** | "A and B both explain each other" | Choose the dominant direction |
+| **Drift into prioritization** | Analysis turns into a what-to-do-next list | Stop at Step 5; prioritization is a different skill |
+
+## Verification
+
+After delivering a semantic-center analysis, verify:
+
+- [ ] Exactly one primary part was identified (a stated tie counts as one, not two)
+- [ ] Every secondary part has an explicit relation type from the taxonomy
+- [ ] No relation is just proximity dressed up as structure
+- [ ] No symmetric "A and B both explain each other" relations remain
+- [ ] The "Important Distinction" is non-obvious rather than a restatement of the primary part
+- [ ] The final reduction is exactly one sentence in the prescribed form
+- [ ] The output stays in explanation mode rather than drifting into implementation or prioritization
+- [ ] If codebase analysis mode was used, `## Key Files` and `## Verified Against` are present and grounded in actual reads
+
+## Do NOT Use When
+
+| Instead, use | Why |
+|---|---|
+| `task-analysis` | The unit of analysis is a route or flow and the question is "what is the user's top task?" Task-analysis owns goal-driven UX decomposition; semantic-center owns structural-importance reduction. |
+| `conceptual-modeling` | You need a *full* concept model (all entities, attributes, relationships, invariants), not a single load-bearing reduction. Conceptual-modeling owns the full model; semantic-center owns the reduction. |
+| `pattern-recognition` | The unit of analysis is *many instances* and the question is "what recurring pattern is this?" Pattern-recognition owns cross-instance pattern classes; semantic-center owns within-instance one-primary reduction. |
+| `intent-recognition` | The task is parsing an ambiguous user prompt to recover the intent, not analyzing a system. Intent-recognition is upstream of any system analysis. |
+| `documentation` | You are writing or restructuring a doc artifact, not analyzing a system. Documentation owns the artifact; semantic-center may produce content that goes into the artifact. |
+| (a prioritization skill) | The question is "what should we work on next?" Prioritization is operational ranking; semantic-center is conceptual load-bearing. |
+| (a domain-modeling skill) | The task is formal architecture: bounded contexts, aggregates, ownership boundaries. Domain-modeling owns formal model design; semantic-center is a quick structural explanation. |
+| (the relevant domain skill) | The task is implementation, debugging, or shipping code. Semantic-center explains structure; it does not build. |

package/marketplace/skills/semantic-relations/SKILL.md

@@ -0,0 +1,250 @@
+---
+name: semantic-relations
+description: "Use when typing edges in a knowledge graph or concept map, resolving synonym/antonym/polysemy/homonym confusion, testing whether a connection is IS-A, PART-OF, causal, thematic, or vague, explaining adjacent concepts, or auditing whether hierarchy and skill-boundary decisions use the wrong relation type. Covers taxonomic, associative, and thematic relations plus symmetry, asymmetry, transitivity, reflexivity, and irreflexivity. Do NOT use for formal ontology axioms with reasoning constraints, database foreign-key or junction-table design, or operational data correspondence across systems."
+license: MIT
+compatibility: "Vocabulary-layer skill, stack- and storage-agnostic. The relation taxonomy and the substitution / property tests apply to any knowledge graph, concept map, taxonomy, or naming system; downstream implementation skills (ontology, ER modeling, relational mapping) consume the typed relations defined here."
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.1.0\",\"type\":\"capability\",\"category\":\"foundations\",\"domain\":\"foundations/semantics\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-16\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-16\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"comprehension_state\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"semantic relations\\\\\\\",\\\\\\\"relation typing\\\\\\\",\\\\\\\"IS-A relation\\\\\\\",\\\\\\\"PART-OF relation\\\\\\\",\\\\\\\"hypernymy hyponymy\\\\\\\",\\\\\\\"meronymy holonymy\\\\\\\",\\\\\\\"synonymy versus polysemy\\\\\\\",\\\\\\\"thematic role analysis\\\\\\\",\\\\\\\"relation property check\\\\\\\",\\\\\\\"knowledge-graph edge typing\\\\\\\",\\\\\\\"substitution test\\\\\\\",\\\\\\\"relation-vocabulary discipline\\\\\\\",\\\\\\\"typed-edge taxonomy\\\\\\\",\\\\\\\"conceptual-relation analysis\\\\\\\",\\\\\\\"adjacency-vs-boundary disambiguation\\\\\\\",\\\\\\\"generic related-to anti-pattern\\\\\\\"]\",\"examples\":\"[\\\\\\\"our codebase uses customer, client, buyer, and user in different modules — which relation analysis tells us whether this is synonymy, near-synonymy, or distinct domain language?\\\\\\\",\\\\\\\"a new graph schema uses related_to for every edge — which semantic relation types should replace it so traversal and reasoning stay meaningful?\\\\\\\",\\\\\\\"is a refund a kind of payment, part of a payment, or the result of a payment action?\\\\\\\",\\\\\\\"two skills seem close: one owns structure design and one owns assignment into that structure — is that adjacency, a boundary, or a deeper taxonomic relation?\\\\\\\",\\\\\\\"the word status appears across payments, orders, and fulfillment — how should relation analysis expose the polysemy and guide disambiguation?\\\\\\\",\\\\\\\"type these knowledge-graph edges so traversal is meaningful instead of generic\\\\\\\",\\\\\\\"test whether 'every line item is an order' passes the IS-A substitution test\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"I need formal OWL axioms, class restrictions, and reasoning semantics on a knowledge base\\\\\\\",\\\\\\\"I need the physical database foreign keys and junction-table design for these relationships\\\\\\\",\\\\\\\"I need to connect external IDs from one platform to canonical IDs in our system operationally\\\\\\\",\\\\\\\"I need the broader representation choice between graph, frames, rules, or hybrid knowledge systems\\\\\\\",\\\\\\\"I need to analyze icon metaphors, color connotation, and UI sign systems\\\\\\\",\\\\\\\"rename this function across all call-sites in the repo\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"linguistics\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"linguistics owns the rules of word form (morphology, polysemy resolution at the identifier level, audience register); semantic-relations owns the typing of meaning connections between concepts (IS-A, PART-OF, thematic roles, relation properties) — the same 'what's the relationship between these two terms?' prompt routes by whether the lens is the term form/morphology or the typed connection between meanings\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"conceptual-modeling\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"conceptual-modeling builds the full concept structure (which entities, which attributes, which relationships exist); semantic-relations supplies the relation-typing vocabulary used inside that structure (whether a relationship is taxonomic, mereological, thematic, causal) — the same 'model these concepts' prompt routes by whether the user wants the structure built or the relation types named\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"knowledge-modeling\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"knowledge-modeling chooses the representation paradigm (graph, frames, rules, hybrid) for a knowledge surface; semantic-relations chooses the relation vocabulary used inside whatever paradigm is picked — the same 'design how to represent this knowledge' prompt routes by whether the trigger is the representation choice or the relation typing\\\\\\\"}],\\\\\\\"related\\\\\\\":[\\\\\\\"linguistics\\\\\\\",\\\\\\\"pattern-recognition\\\\\\\",\\\\\\\"semantic-center\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"linguistics\\\\\\\",\\\\\\\"code-review\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":365,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"Semantic-relations is to a knowledge graph what road-sign verbs are to a transit map — `motorway`, `slip road`, `roundabout`, `level crossing`, `bridge`, `tunnel` are each typed connections with their own rules of traversal (one-way / two-way / yields / stops). A map that labels every road `connector` is nearly useless for navigation; a map that labels them precisely lets the driver reason about which routes are even possible. The vocabulary is not decoration — it is the load-bearing semantics that makes the map a tool rather than an illustration.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"Semantic relations are the *typed connections* between concepts in a meaning structure: IS-A (hypernymy/hyponymy), PART-OF (holonymy/meronymy), synonymy, antonymy, polysemy, homonymy, metonymy, and the thematic role relations (agent, patient, instrument, location, source, goal, cause, result). Drawn from lexical semantics (Lyons, Cruse), Princeton WordNet, the W3C SKOS vocabulary, and cognitive-semantics work on thematic roles (Fillmore 1968, Jackendoff 1990), it treats every edge in a knowledge graph, concept map, or hierarchy as a relation of a *named kind* rather than a generic association.\\\\\\\",\\\\\\\"mental_model\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"purpose\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"boundary\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"taxonomy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"analogy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"misconception\\\\\\\":\\\\\\\"|\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/semantic-relations/SKILL.md\",\"skill_graph_export_description\":\"shortened for Agent Skills 1024-character description limit; canonical source keeps the full routing contract\",\"skill_graph_canonical_description_length\":\"1113\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/semantic-relations/SKILL.md
+---
+
+# Semantic Relations
+
+## Coverage
+
+Semantic relation analysis as a typed-connection discipline. Covers four families of relations and their properties:
+
+- **Taxonomic relations** — hypernymy / hyponymy (IS-A) with the substitution test, transitivity, asymmetry, and inheritance; holonymy / meronymy (PART-OF) with six part-whole types (component-integral, member-collection, portion-mass, stuff-object, feature-activity, place-area)
+- **Associative relations** — synonymy, near-synonymy, antonymy (complementary, gradable, relational), polysemy, homonymy, metonymy
+- **Thematic relations** (role-based) — agent, patient, instrument, location, source, goal, cause, result, temporal, beneficiary
+- **Relation properties** — symmetry, asymmetry, transitivity, reflexivity, irreflexivity
+
+Application surfaces include knowledge-graph edge typing, naming disambiguation (synonymy vs polysemy vs homonymy), skill / module boundary analysis (adjacent vs boundary vs verify-with), category / hierarchy sanity checks, and relation-aware explanation of how concepts connect. Includes a six-item anti-pattern catalog (generic `related_to` edges, circular IS-A, conflated PART-OF and IS-A, synonym sprawl, untyped polysemy, property-free relation definitions) and a six-item verification checklist.
+
+## Philosophy
+
+Every complex system depends on relation quality, not just node quality. Most knowledge-system failures are not failures to name the things; they are failures to *type the connection between things*. A graph with only `related_to` edges is nearly useless for reasoning. A naming audit that cannot separate synonymy from polysemy suggests the wrong fix. A skill system that cannot tell adjacency from boundary loads the wrong context.
+
+The discipline is: **name the relation, then test whether the name is the right kind of relation.** If "A is B" fails the substitution test, it is not hypernymy. If a part-whole relation changes lifecycle semantics, it is not just loose association. If two words share one form but multiple related meanings, that is polysemy, not synonymy. Precision here compounds into every other knowledge and modeling skill — the quality of every downstream representation depends on whether the relations were typed correctly upstream.
+
+This skill is the *vocabulary layer*. It does not own the formal axioms (an ontology skill), the storage shape (an ER-modeling skill), the cross-system data correspondence (a relational-mapping skill), or the broader knowledge-representation paradigm (a knowledge-modeling skill). It owns the question: *what kind of relation is this?*
+
+---
+
+## 1. Taxonomic Relations (Hierarchical)
+
+### Hypernymy / Hyponymy (IS-A)
+
+| Term | Definition | Example |
+|------|-----------|---------|
+| **Hypernym** | The more general category | Vehicle is a hypernym of Car |
+| **Hyponym** | The more specific category | Car is a hyponym of Vehicle |
+| **Co-hyponyms** | Same-level members of a category | Car, Truck, Motorcycle are co-hyponyms of Vehicle |
+
+Properties:
+
+- **Transitive** — if A is-a B and B is-a C, then A is-a C
+- **Asymmetric** — if A is-a B, then B is NOT a A
+- **Inheritance** — hyponyms inherit properties of hypernyms
+
+Rules:
+
+- Every IS-A claim must pass the **substitution test**: "Every [hyponym] is a [hypernym]." If that sentence sounds wrong, it is probably not hypernymy.
+- Distinguish IS-A from role labels. A buyer is not a *type of* order; a buyer is an actor *related to* an order.
+- Co-hyponyms should be mutually exclusive unless the model explicitly allows overlap.
+
+### Holonymy / Meronymy (PART-OF)
+
+| Term | Definition | Example |
+|------|-----------|---------|
+| **Holonym** | The whole | Order is holonym of LineItem |
+| **Meronym** | The part | LineItem is meronym of Order |
+
+Types of part-whole:
+
+| Type | Part can exist alone? | Example |
+|------|----------------------|---------|
+| **Component-integral** | No | Engine is component of Car |
+| **Member-collection** | Yes | Tree is member of Forest |
+| **Portion-mass** | No | Slice is portion of Pie |
+| **Stuff-object** | No | Wood is stuff of Table |
+| **Feature-activity** | No | Payment is feature of Checkout |
+| **Place-area** | Yes | Room is place in Building |
+
+Rules:
+
+- PART-OF is not the same as IS-A. "Every line item is an order" fails; "a line item is part of an order" passes.
+- Part-whole relations carry lifecycle implications that influence later ER modeling and API design, but those implementation choices belong to the downstream implementation skills.
+- Do not assume every part-of relation is fully transitive in practical reasoning.
+
+---
+
+## 2. Associative Relations (Non-Hierarchical)
+
+### Synonymy and Antonymy
+
+| Relation | Definition | Software impact |
+|----------|-----------|-----------------|
+| **Synonymy** | Different words, same meaning | `customer`, `client`, `buyer` may collapse into one canonical term |
+| **Near-synonymy** | Similar but not identical meaning | `error`, `failure`, `fault` may need explicit distinctions |
+| **Antonymy** | Opposite meaning | `credit` vs `debit`, `active` vs `inactive` |
+| **Complementary antonymy** | Binary opposition, no middle | `true` / `false` |
+| **Gradable antonymy** | Scale with degrees | `high` / `low` |
+| **Relational antonymy** | Paired roles | `buyer` / `seller`, `parent` / `child` |
+
+Rules:
+
+- Synonymy is usually a naming-governance problem: pick one canonical label and route aliases to it.
+- Near-synonyms must not be flattened if the codebase or domain uses them differently.
+- Antonym pairs should be consistent within one domain surface; avoid mixing `inactive`, `disabled`, and `off` unless the distinctions are real.
+
+### Polysemy and Homonymy
+
+| Relation | Definition | Software impact |
+|----------|-----------|-----------------|
+| **Polysemy** | One form, multiple related meanings | `order` can mean purchase, sequence, or command |
+| **Homonymy** | One form, unrelated meanings | `bank` as finance vs river bank |
+
+Rules:
+
+- Polysemy is common in code and product language. Qualify the meaning with context when one bare term can mislead.
+- Homonymy usually requires stronger renaming than polysemy because the meanings are unrelated.
+- If two meanings are related and historically or structurally connected, treat it as polysemy, not accidental duplication.
+
+### Metonymy
+
+| Relation | Definition | Example |
+|----------|-----------|---------|
+| **Metonymy** | One concept stands in for a closely related concept | `shipped` used to denote an order's *current state* rather than the act itself |
+
+Rules:
+
+- Metonymic shortcuts are acceptable only when the intended meaning remains obvious in context.
+- Audit status labels and event names for places where a metonym has become more confusing than helpful.
+
+---
+
+## 3. Thematic Relations (Role-Based)
+
+| Role | Definition | Example |
+|------|-----------|---------|
+| **Agent** | The entity that performs the action | Customer places order |
+| **Patient** | The entity affected by the action | Order is placed by customer |
+| **Instrument** | The means by which the action is performed | Payment processed via payment provider |
+| **Location** | Where the action occurs | Order placed in storefront |
+| **Source** | Where something comes from | Shipment from warehouse |
+| **Goal** | Where something goes | Delivery to customer address |
+| **Cause** | What triggers the action | Webhook triggers order sync |
+| **Result** | What the action produces | Payment produces receipt |
+| **Temporal** | When the action occurs | Order placed on 2026-03-29 |
+| **Beneficiary** | Who benefits from the action | Refund issued for customer |
+
+Rules:
+
+- Use thematic roles when an action or event relation is more precise than simple association.
+- Distinguish the actor from the instrument and from the cause; they are often conflated in loose architecture explanations.
+- Event naming and API design improve when the thematic role is clear.
+
+---
+
+## 4. Relation Properties
+
+| Property | Definition | Test |
+|----------|-----------|------|
+| **Symmetric** | If A relates to B, then B relates to A | `sibling_of` |
+| **Asymmetric** | If A relates to B, then B does NOT relate to A the same way | `is_a` |
+| **Transitive** | If A → B and B → C, then A → C | `ancestor_of` |
+| **Reflexive** | A relates to itself | `equal_to` |
+| **Irreflexive** | A cannot relate to itself | `parent_of` |
+
+Rules:
+
+- Relation names are incomplete without relation properties.
+- If the relation direction matters, state it explicitly instead of assuming readers infer it.
+- Property mismatches are a common source of bad graph or hierarchy design.
+
+---
+
+## 5. Application
+
+### Knowledge-Graph Edge Typing
+
+| Bad (vague) | Better (typed) | Why |
+|-------------|----------------|-----|
+| `A -- related_to -- B` | `A -- is_a -- B` | Preserves hierarchy meaning |
+| `A -- linked_to -- B` | `A -- causes -- B` | Preserves causal meaning |
+| `A -- see_also -- B` | `A -- adjacent_to -- B` | Makes proximity type explicit |
+| `A -- has -- B` | `A -- composed_of -- B` | Separates part-whole from loose ownership |
+
+### Skill-Boundary Analysis
+
+| Skill-system relation | Semantic relation analogue |
+|-----------------------|----------------------------|
+| `related` (formerly `adjacent`) | Associative or thematic proximity |
+| `boundary` | Scope separation between neighboring categories or co-hyponyms |
+| `verify_with` | Instrumental relation: one skill is used to validate another |
+
+### Naming Disambiguation
+
+When two names conflict:
+
+1. Identify the relation: synonymy, near-synonymy, polysemy, homonymy, or antonym mismatch.
+2. If synonymy: pick one canonical label and redirect aliases.
+3. If polysemy: qualify with context.
+4. If homonymy: rename one of the terms outright.
+
+---
+
+## 6. Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|--------------|---------|-----|
+| **Generic `related_to` edges** | No semantic information; poor reasoning and poor graph traversal | Type the edge with a specific relation |
+| **Circular IS-A** | A is-a B is-a C is-a A | Keep the hierarchy acyclic and substitution-valid |
+| **Conflated PART-OF and IS-A** | Treating a component as a subtype | Apply the substitution test first |
+| **Synonym sprawl** | Several labels for one concept | Canonical term + explicit aliases |
+| **Untyped polysemy** | One term overloaded across domains | Qualify the term or split the concept |
+| **Property-free relation definitions** | Named relation with no symmetry/transitivity reasoning | State the relation properties explicitly |
+
+---
+
+## Verification
+
+After applying this skill, verify:
+
+- [ ] Every conceptual or graph edge has a typed relation rather than a vague generic link
+- [ ] IS-A relationships pass the substitution test
+- [ ] PART-OF relationships are not being mistaken for type hierarchy
+- [ ] Synonymy, polysemy, and homonymy are distinguished before renaming
+- [ ] Relation properties (symmetry, asymmetry, transitivity, reflexivity) are explicit when they matter
+- [ ] Boundary claims with neighboring skills or modules still hold under the substitution / governance test
+
+## Do NOT Use When
+
+| Instead, use | Why |
+|---|---|
+| `linguistics` | Analyzing word morphology, polysemy at the identifier level, audience register, or blame-free phrasing. Linguistics covers word-form rules; semantic-relations covers meaning-connection types. |
+| `conceptual-modeling` | Building the full concept structure (entities, attributes, relationships, invariants). Conceptual-modeling owns structure; semantic-relations owns the relation-typing vocabulary used inside it. |
+| `knowledge-modeling` | Choosing the representation paradigm — graph vs frames vs rules vs hybrid — for a knowledge surface. Knowledge-modeling chooses the paradigm; semantic-relations chooses the relation vocabulary inside it. |
+| (an ontology skill) | Building formal ontologies with class/property axioms, restrictions, and reasoning semantics. Ontology formalizes; semantic-relations supplies the relation vocabulary before formalization. |
+| (an entity-relationship-modeling skill) | Designing database foreign keys, junction tables, and physical schema constraints. ER modeling implements physical relationships; semantic-relations analyzes conceptual ones. |
+| (a relational-mapping skill) | Mapping entities between different systems or platforms operationally. Relational mapping is operational data correspondence, not conceptual relation typing. |
+| (a taxonomy skill) | Designing hierarchy or facet structures themselves. Taxonomy owns the structural classification system; semantic-relations owns the relation meanings used within and around it. |
+| (a semiotics skill) | Auditing iconography, color connotation, or interface sign systems. Semiotics handles signs in interfaces; semantic-relations handles concept-to-concept meaning relations. |
+
+## Key Sources
+
+- Cruse, D. A. (1986). *Lexical Semantics*. Cambridge University Press. The canonical treatment of word-meaning relationships: synonymy, antonymy, hyponymy, meronymy, and the substitution-test discipline that grounds taxonomic-claim validation.
+- Lyons, J. (1977). *Semantics* (2 vols.). Cambridge University Press. Comprehensive structural-semantics textbook covering sense relations, lexical fields, and the relational view of meaning.
+- Miller, G. A. (1995). "WordNet: A Lexical Database for English." *Communications of the ACM*, 38(11), 39-41. The reference paper for Princeton WordNet — the largest empirically-grounded catalog of semantic relations between English lexemes; the working model for any taxonomic / mereological / antonymy relation system at scale.
+- Fellbaum, C. (Ed.). (1998). *WordNet: An Electronic Lexical Database*. MIT Press. The collected technical account of WordNet's relation set, design decisions, and applications.
+- Winston, M. E., Chaffin, R., & Herrmann, D. (1987). "A Taxonomy of Part-Whole Relations." *Cognitive Science*, 11(4), 417-444. The reference paper for the six PART-OF subtypes (component-integral, member-collection, portion-mass, stuff-object, feature-activity, place-area). Foundation for any mereological analysis.
+- Fillmore, C. J. (1968). "The Case for Case." In E. Bach & R. T. Harms (Eds.), *Universals in Linguistic Theory*. Holt, Rinehart and Winston. The foundational paper for thematic / case roles (agent, patient, instrument, location, source, goal); the linguistics origin of the role catalog still used in event modeling.
+- Jackendoff, R. (1990). *Semantic Structures*. MIT Press. Modern cognitive-semantics treatment of thematic roles, conceptual structure, and the relationship between semantic and syntactic categories.
+- W3C. [SKOS Simple Knowledge Organization System Reference](https://www.w3.org/TR/skos-reference/) (2009). The lightweight RDF vocabulary for broader/narrower/related and prefLabel/altLabel; the minimum-viable formalism for transmissible semantic relations.
+- W3C. [OWL 2 Web Ontology Language: Primer (Second Edition)](https://www.w3.org/TR/owl2-primer/) (2012). Object properties and their characteristics — functional, inverse-functional, transitive, symmetric, asymmetric, reflexive, irreflexive — for the formal end of the relation-typing spectrum.
+- Storey, V. C. (1993). "Understanding Semantic Relationships." *VLDB Journal*, 2(4), 455-488. Survey of semantic relations in data-modeling contexts; the bridge from linguistic relation analysis to information-systems design.