diff --git a/src/docs.json b/src/docs.json
index ee5a301d09..f40719aeb7 100644
--- a/src/docs.json
+++ b/src/docs.json
@@ -631,7 +631,8 @@
                 {
                   "group": "Context engineering",
                   "pages": [
-                    "langsmith/context-engineering-quickstart"
+                    "langsmith/context-engineering-quickstart",
+                    "langsmith/context-engineering-concepts"
                   ]
                 },
                 {
diff --git a/src/langsmith/context-engineering-concepts.mdx b/src/langsmith/context-engineering-concepts.mdx
new file mode 100644
index 0000000000..45f619375e
--- /dev/null
+++ b/src/langsmith/context-engineering-concepts.mdx
@@ -0,0 +1,103 @@
+---
+title: Context engineering concepts
+sidebarTitle: Concepts
+---
+
+Context is the information an agent relies on to act—system instructions,
+tool definitions, reference material, etc. _Context
+engineering_ is the practice of building and optimizing that context to 
+improve agent performance and capabilities.
+
+This guide walks through the core concepts of context engineering in
+LangSmith's context hub, including skills, agents, versioning, and sharing.
+
+
+## Skills
+
+A **skill** packages a single, reusable capability that an agent can
+invoke. Skills are focused on doing one thing well, and they're designed
+to be used by agents.
+
+Skill repos contain:
+
+**Always:**
+- `SKILL.md` file in its root directory (the core content of the skill)
+- Description of what the skill does / when to use it
+
+**Optional:**
+- References (Technical documentation, guides, etc.)
+- Assets (Schema, templates, etc.)
+
+
+Examples: email formatting, code review, web search
+
+## Agents
+
+An **agent** packages an entire agent: its high-level instructions,
+the skills and subagents it can use, and the tools it has access to. 
+Agents are designed to complete tasks end to end.
+
+Agent repos contain:
+
+**Always**
+- `AGENTS.md` — the agent's system prompt and operating instructions
+
+**Optional**
+- `tools.json` — set of tools the agent can call
+- Subagents — smaller agents this agent can delegate to
+- Skills - set of skills the agent can use
+
+
+Examples: email assistant, coding copilot, customer support agent.
+
+### When to use Skills vs Agents
+- Use skills for smaller tasks, reusable context, specifications
+- Use Agents for longer tasks, tool calling, decision making
+<Tip>
+A good rule of thumb: if you find yourself copying the same block of
+context into several agents, pull it out into a skill repo and reference
+it from each agent.
+</Tip>
+
+
+## Hub backend vs store backend
+
+Context in LangSmith can be managed by two different backends: the
+**Context Hub** and a **store backend.** 
+They serve different purposes, and most agents use both.
+
+**The Context Hub is built for versioning, sharing, and continuous
+improvement.** It is the long term context database that your agent can use. 
+Think of it as a Git-like home for your agent's context.
+
+**A store backend is built for runtime state.** It holds the information
+an agent accumulates _while running_: memories, conversation history,
+user preferences, learned facts, and other data that evolves per session
+or per user.
+
+## Versioning
+
+Every change to a repo in the **Context Hub** creates a new commit.
+Commits are immutable, browsable, and comparable, so you can:
+
+- See exactly what changed between two versions of an agent.
+- Revert to any prior commit if a change regresses behavior.
+- Tag important commits (for example, the commit you shipped on a
+  specific date) for easy reference.
+- Promote a commit to an **environment** like `Staging` or `Production`
+  so downstream agents pull a known-good version rather than the latest
+  edit.
+
+## Sharing and permissions
+
+The **Context Hub** is designed for teams. Every repo lives in a
+[workspace](/langsmith/administration-overview#workspaces), and its
+visibility and permissions are managed at the repo level:
+
+- **Private** repos are visible only inside the workspace.
+- **Public** repos can be discovered and pulled by anyone.
+- Per-repo **permissions** control who can view, commit, tag, and
+  promote within a workspace.
+
+This makes the Hub a natural place to collaborate on agents and skills, 
+and improve them over time.