feat(skills): add atomic skill design and global store

.docs/index.md

@@ -12,3 +12,7 @@ title: Documentation Index
 - [Config Matching](technical/config-matching.md): How agnos resolves glob-aware documentation ignores and rule fragments.
 - [MCP Env Resolution](technical/mcp-env-resolution.md): How MCP env key declarations are resolved into secret-bearing agent files.
 - [Skills Reconciliation](technical/skills-reconciliation.md): How declared skill sources are reconciled with materialized skills and lock entries.
+
+### technical-decisions
+
+- [Global Skill Store](technical-decisions/global-skill-store.md): Records why Agnos shares verified skill content globally while keeping project materializations independent.

.docs/technical-decisions/global-skill-store.md

@@ -0,0 +1,32 @@
+---
+type: Technical Decision
+title: Global Skill Store
+description: Records why Agnos shares verified skill content globally while keeping project materializations independent.
+resource: ""
+tags: [skills, storage, caching]
+timestamp: 2026-08-13T00:00:00Z
+---
+
+# Global Skill Store
+
+## Decision
+
+Agnos uses one versioned content-addressed skill store per user. Projects import independent materializations from that store and use their lockfiles to select exact content hashes and commits.
+
+## Rationale
+
+- Identical locked skills are downloaded and stored once across repositories.
+- Hash verification makes shared reuse deterministic and detects accidental corruption.
+- Independent project materializations continue working after the store is removed or pruned.
+- Exact commit fetches reproduce missing entries after a tracked branch advances.
+
+## Consequences
+
+- The global store is part of the current user's trust boundary.
+- Cross-project offline reuse requires a committed lockfile.
+- Project materialization consumes filesystem metadata and may consume full file data when cloning and hard links are unavailable.
+- Machine-specific store placement remains outside project configuration.
+
+## References
+
+- Reconciliation behavior: [Skills Reconciliation](../technical/skills-reconciliation.md).

.docs/technical/skills-reconciliation.md

@@ -27,9 +27,48 @@ timestamp: 2026-07-09T00:00:00Z
 - The skills domain prunes before installing or updating skills.
 - A normal `agnos` run prunes before materializing declared skills.
 - If no skills are declared, pruning still runs so stale materialized skills can be removed.
+- Skill reconciliation runs with bounded concurrency while preserving declaration order in its result.
+- Concurrent requests for the same Git source are coalesced into one fetch.
+- Git checkouts use an isolated per-run workspace under `.agnos/tmp/repos`.
+- Repository workspaces are removed at the end of each command or domain run, including when skills are moved, changed, or fail to install.
+
+## Content-addressed storage
+
+- Skill content is stored once per user in a global, versioned store selected from the operating system data directory.
+- `AGNOS_STORE_DIR` overrides the global store base for installations that need a custom location.
+- Every store reuse recomputes the skill hash. Invalid entries are replaced through atomic publication.
+- The configured skills route contains an independent project materialization imported with copy-on-write cloning, hard links, or copies.
+- Project materializations remain usable if the global store is removed.
+- A pinned remote skill can be restored from its lock entry and global stored content without a Git operation.
+- Local skill sources are still hashed on each reconciliation so local edits are detected.
+- `agnos skills integrity` explicitly hashes project materializations instead of trusting tool-managed state.
+- Updates bypass any checkout already staged during the current run before computing and accepting a new hash.
+- Store publication never deletes the final hash path, tolerates concurrent publishers, and retries transient Windows filesystem errors.
+- Lock updates use temporary files and atomic publication so concurrent readers never observe partial JSON.
+
+## Reproducible fetches
+
+- New remote lock entries record the commit SHA returned by the checkout that supplied the accepted content.
+- A missing global entry is refetched at the locked commit rather than the current branch head.
+- Legacy lock entries without a commit fetch their tracked ref once and are backfilled only when the content hash still matches.
+
+## Legacy migration
+
+- Referenced entries from `.agnos/cache/skills` are verified and promoted into the global store.
+- Existing project links are replaced with independent materializations before the legacy cache is removed.
+- A failed or incomplete migration retains the project cache and reports a warning.
+
+## Progress reporting
+
+- Interactive installs show a live completion percentage.
+- The progress line reports the declared skill total, content-store reuses, and source fetches.
+- A content-store hit increments `reused`. A skill loaded successfully from its declared source increments `fetched`.
+- Quiet and non-interactive runs omit the transient progress line.
+- Successful interactive and non-interactive installs emit a final 100 percent summary with the same counters.
 
 ## References
 
 - Skills command surface: [index.ts](../../src/domains/skills/index.ts).
 - Skills steps: [steps.ts](../../src/domains/skills/steps.ts).
 - Skills pipeline tests: [skills-pipeline.test.ts](../../test/domains/skills-pipeline.test.ts).
+- Global store decision: [Global Skill Store](../technical-decisions/global-skill-store.md).

.env.example

@@ -0,0 +1,20 @@
+# ——————————————————————————————————————————————————————————————————————————
+# ——— Agnos: Local CLI configuration
+
+# Use   : Override the user-level content-addressed skill store location.
+# Source: Choose a writable directory trusted by the current user.
+# Path  : Local filesystem > Agnos store
+# E.g.  : C:\Users\name\AppData\Local\agnos\store
+AGNOS_STORE_DIR=
+
+# Use   : Enable diagnostic CLI logging.
+# Source: Set locally when troubleshooting Agnos.
+# Path  : Local shell > Environment
+# E.g.  : 1
+AGNOS_DEBUG=
+
+# Use   : Override the Model Context Protocol registry endpoint.
+# Source: Use the endpoint supplied by the registry operator.
+# Path  : MCP registry > API endpoint
+# E.g.  : https://registry.modelcontextprotocol.io
+AGNOS_MCP_REGISTRY=https://registry.modelcontextprotocol.io

.gitignore

@@ -13,6 +13,7 @@ scratch/
 
 # ENV
 .env*
+!.env.example
 
 # AGENTS
 .agents/

.prettierignore

@@ -7,3 +7,4 @@ pnpm-lock.yaml
 test-output
 scratch
 packages/*/dist
+.env.example

README.md

@@ -221,7 +221,7 @@ Injects titled sections (by frontmatter `title`) from fragment files into your c
 
 ### `skills`
 
-Fetches, pins, verifies, and installs skills into the canonical skills dir (linked per-agent by `agents`).
+Fetches, pins, verifies, and installs skills into the canonical skills dir (linked per-agent by `agents`). Install work is concurrent, with live percentage, total, reused, and fetched counters. Each unique locked skill tree is stored once in a user-level content store shared across repositories. Projects receive independent materializations, so removing the store does not break installed skills. Git checkouts are isolated under `.agnos/tmp/repos/` for the current run and always removed afterward. Set `AGNOS_STORE_DIR` to override the operating system data location used by the store.
 
 | Subcommand  | Args / Flags                                                                                  | Description                                                                                                                                                                                                                                                |
 | ----------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

skills/atomic-design/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: atomic-design
+description: Atomic design methodology with type-filtered slot composition for UI implementation, validation, review, and audits. Use when implementing, validating, reviewing, or auditing frontend/UI code through atomic design principles, component hierarchy, atoms, molecules, organisms, templates, pages, reusable design systems, React-style compound components, named slots, child filtering by type, fixed slot positioning, Storybook or component state coverage, content structure, and page variation resilience.
+---
+
+# Atomic Design
+
+Apply atomic design as a UI design-system mental model, not as a rigid build sequence. Organize components by logical responsibility using atomic design, then compose their variable regions through slots.
+
+Read [Atomic Design Methodology](references/atomic-design-methodology.md) when you need the stage taxonomy, React-oriented placement rules, source notes, or detailed audit prompts.
+
+Read [Slot-Based Composition](references/slot-based-composition.md) when you need compound component exports, child filtering by type, fixed slot positioning, or review prompts for slot composition.
+
+## Workflow
+
+1. Inspect the existing UI architecture before introducing atomic vocabulary.
+2. Preserve the repo's naming, routing, styling, testing, and component patterns unless the user explicitly asks for a reorganization.
+3. Map the target code to the smallest atomic stage that can own the responsibility.
+4. Expose variable regions as slots when a component has stable structure but flexible content.
+5. Check the same component in isolation and in its composed page context.
+6. Validate with the repo's normal commands and with rendered UI inspection when visual behavior matters.
+
+## Stage Ownership
+
+| Stage    | Owns                                                                                                                                                        | Avoid                                                                      |
+| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| Atom     | Primitive UI elements, design tokens in use, accessible base controls, typographic primitives, icons, inputs, buttons.                                      | Page-specific layout, margins, route data, application workflows.          |
+| Molecule | Small functional groups of atoms, such as search fields, form rows, nav items, summary badges, or card headers.                                             | Full page sections, global data fetching, unrelated optional regions.      |
+| Organism | Distinct interface sections composed of atoms, molecules, or other organisms, such as headers, product grids, checkout forms, sidebars, and feature panels. | Route ownership, full-page layout skeletons, hard-coded page-only content. |
+| Template | Page-level layout and content structure, including grid regions, slots, skeletons, and constraints for dynamic content.                                     | Final production copy, business-specific records, route side effects.      |
+| Page     | Real representative content, route integration, application state wiring, user-role or data-volume variations, and final resilience checks.                 | Reusable component internals that belong lower in the hierarchy.           |
+
+## Implementation Rules
+
+- Prefer the existing component taxonomy. Introduce `atoms`, `molecules`, `organisms`, `templates`, and `pages` folders only when that matches or improves the local system.
+- Keep dependencies flowing upward through the hierarchy: atoms should not import molecules, molecules may import atoms, organisms may import molecules and atoms, templates may import organisms and lower stages, and pages may wire all stages together.
+- Keep atoms portable. They can expose variants and states, but they must not assume where they sit on a page.
+- Compose molecules from atoms to create one focused function. Split a molecule when independent concerns start sharing props, state, or styles.
+- Compose organisms as reusable interface sections. They may coordinate child layout but should stay independent enough to work in multiple page contexts.
+- Keep templates about structure. They arrange regions and define content constraints without binding final records, permissions, or navigation behavior.
+- Use pages to connect templates and components to real app data, routing, representative content, and meaningful variations.
+- Centralize design tokens or variables according to the repo's existing style system. Do not duplicate token values inside components.
+- Cover meaningful states where the repo supports component examples, stories, screenshots, or interaction tests.
+
+## Slot-Based Composition Rules
+
+- Use slots when props like `headerContent`, `footerActions`, `leftIcon`, or `descriptionNode` begin to multiply or when callers need to provide real JSX while the component owns structure.
+- Prefer semantic compound slots such as `Card.Header`, `Card.Body`, `Card.Footer`, `Dialog.Title`, or `Toolbar.Action` for reusable molecules and organisms.
+- Colocate slot components inside the owning component folder and export them from the root component API.
+- Put generic child filtering in a shared `prepareComponentSlots` helper, then wrap it in a colocated hook named like `use<Component>Slots`.
+- Let slot components import lower-stage components when needed. For example, a molecule slot may import an atom, but an atom slot must not import a molecule.
+- Define slot components as function components. Type filtering compares `child.type` with the function reference registered in the slot map.
+- Keep slot names semantic, not incidental. Prefer `Title`, `Description`, `Actions`, `Media`, and `Footer` over `Top`, `Left`, or `BlueArea` unless the component is explicitly a layout primitive.
+- Filter slot children by component type when the parent owns positioning. The consumer may write slots in a readable order, but the parent renders each recognized slot into its defined region.
+- Preserve DOM reading order and accessibility. Do not visually reorder slots in a way that creates a different keyboard or screen-reader order.
+
+Example organization:
+
+```text
+src/
+  components/
+    atoms/
+      component-a/
+        index.tsx
+    molecules/
+      component-b/
+        title.tsx
+        body.tsx
+        use-component-b-slots.ts
+        index.tsx
+```
+
+Example slot hook:
+
+```ts
+import type { ReactNode } from "react";
+
+import { prepareComponentSlots } from "../../hooks/prepare-component-slots.js";
+import { Body } from "./body.js";
+import { Title } from "./title.js";
+
+const usePreparedComponentBSlots = prepareComponentSlots({
+  body: [Body],
+  title: Title,
+});
+
+export function useComponentBSlots(children: ReactNode) {
+  return usePreparedComponentBSlots(children);
+}
+```
+
+Example root export:
+
+```tsx
+import type { ReactNode } from "react";
+
+import { Body } from "./body.js";
+import { Title } from "./title.js";
+import { useComponentBSlots } from "./use-component-b-slots.js";
+
+export interface ComponentBProps {
+  children: ReactNode;
+}
+
+export function ComponentBRoot({ children }: ComponentBProps) {
+  const { body, title } = useComponentBSlots(children);
+
+  return (
+    <section>
+      {title}
+      <div>{body}</div>
+    </section>
+  );
+}
+
+export const ComponentB = Object.assign(ComponentBRoot, {
+  Body,
+  Title,
+});
+```
+
+## Review And Audit Rules
+
+- Report misplaced responsibilities as concrete code findings: atom with page layout, molecule doing route work, organism hard-coding one page, template owning production content, or page duplicating component internals.
+- Check whether components remain reusable with different content lengths, empty states, disabled states, roles, and data volumes.
+- Flag styling that breaks portability, especially margins and positioning buried in low-level atoms.
+- Look for duplicate primitives or one-off components that should share an atom or molecule.
+- Flag prop-heavy components that should expose named slots or compound subcomponents.
+- Flag slots that break atomic dependency direction, hide business logic in reusable component internals, or require consumers to know private child ordering.
+- Verify that templates expose content structure and that pages prove the structure with real representative content.
+- Treat atomic design as a communication and resilience model. Do not require the exact stage names if the repo uses another clear taxonomy.