universal-memory 0.2.1__tar.gz → 0.3.0__tar.gz

{universal_memory-0.2.1 → universal_memory-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: universal-memory
-Version: 0.2.1
+Version: 0.3.0
 Summary: Vendor-agnostic cognitive persistence layer for AI agents.
 Keywords: agent-memory,ai,ai-agents,agent-skills,claude-code,codex,context-engineering,developer-tools,llm,mcp,memory
 Author: Yan L. Amorelli
@@ -171,21 +171,37 @@ umem context --scope project
 
 ### 4. Adopt or create an Agent Skill
 
-If a skill already exists in a native runtime directory, import it into UMEM and sync it
-back out to configured runtimes:
+If a skill already exists, choose the safest adoption path first. Use `adopt` for an
+existing `.umem/skills/<slug>` directory; use `import` for native runtime directories
+such as `.agents/skills/<slug>` and sync it back out to configured runtimes:
 
 ```bash
+umem skills adopt .umem/skills/review-protocol --scope project
 umem skills import .agents/skills/review-protocol --scope project --sync
 umem skills detail review-protocol
 ```
 
-If you are starting from scratch, create the canonical skill first:
+If you are starting from scratch, draft and publish it without native side effects:
 
 ```bash
-umem skills create \
+umem skills draft create \
   --name "Review Protocol" \
   --description "Reusable review workflow" \
   --trigger "when reviewing code"
+umem skills draft validate review-protocol
+umem skills publish review-protocol --format summary
+```
+
+For a one-step workflow, create the canonical skill. It is canonical-only by default;
+request sync explicitly when native runtime targets should be written:
+
+```bash
+umem skills create \
+  --name "Review Protocol" \
+  --description "Reusable review workflow" \
+  --trigger "when reviewing code" \
+  --format summary
+umem skills sync review-protocol --check-gitignore --format summary
 ```
 
 After editing `.umem/skills/review-protocol/SKILL.md`, refresh one runtime skill with:
@@ -291,7 +307,7 @@ your shell `PATH`.
 
 ## Managing Agent Skills
 
-You can create, import, list, inspect, and sync specialized behaviors:
+You can draft, create, adopt, import, validate, maintain, and sync specialized behaviors:
 ```bash
 # List all active skills
 umem skills list
@@ -299,14 +315,30 @@ umem skills list
 # Inspect one skill
 umem skills detail review-protocol
 
-# Create a new canonical skill
-umem skills create --name "Review Protocol" --description "Reusable review workflow"
+# Draft, validate, and publish without native runtime writes
+umem skills draft create --name "Review Protocol" --description "Reusable review workflow"
+umem skills draft validate review-protocol
+umem skills publish review-protocol
+
+# Create a new canonical skill and explicitly sync native targets
+umem skills create --name "Review Protocol" --description "Reusable review workflow" --sync
 
-# Adopt an existing native skill and distribute complete runtime copies
+# Adopt existing canonical work
+umem skills adopt .umem/skills/review-protocol --scope project
+
+# Import an existing native skill and distribute complete runtime copies
 umem skills import .agents/skills/review-protocol --scope project --sync
 
+# Validate and maintain canonical skills
+umem skills validate review-protocol
+umem skills canonical update review-protocol --file .umem/skills/review-protocol/SKILL.md
+umem skills rename review-protocol --slug review-checklist
+umem skills cleanup review-checklist --targets --format summary
+umem skills cleanup review-checklist --targets --apply
+umem skills repair --remove-orphan-targets --format summary
+
 # Synchronize one canonical skill into active native runtime folders
-umem skills sync review-protocol
+umem skills sync review-protocol --check-gitignore --format summary
 
 # Synchronize all active canonical skills during maintenance
 umem update --skills

{universal_memory-0.2.1 → universal_memory-0.3.0}/README.md

@@ -143,21 +143,37 @@ umem context --scope project
 
 ### 4. Adopt or create an Agent Skill
 
-If a skill already exists in a native runtime directory, import it into UMEM and sync it
-back out to configured runtimes:
+If a skill already exists, choose the safest adoption path first. Use `adopt` for an
+existing `.umem/skills/<slug>` directory; use `import` for native runtime directories
+such as `.agents/skills/<slug>` and sync it back out to configured runtimes:
 
 ```bash
+umem skills adopt .umem/skills/review-protocol --scope project
 umem skills import .agents/skills/review-protocol --scope project --sync
 umem skills detail review-protocol
 ```
 
-If you are starting from scratch, create the canonical skill first:
+If you are starting from scratch, draft and publish it without native side effects:
 
 ```bash
-umem skills create \
+umem skills draft create \
   --name "Review Protocol" \
   --description "Reusable review workflow" \
   --trigger "when reviewing code"
+umem skills draft validate review-protocol
+umem skills publish review-protocol --format summary
+```
+
+For a one-step workflow, create the canonical skill. It is canonical-only by default;
+request sync explicitly when native runtime targets should be written:
+
+```bash
+umem skills create \
+  --name "Review Protocol" \
+  --description "Reusable review workflow" \
+  --trigger "when reviewing code" \
+  --format summary
+umem skills sync review-protocol --check-gitignore --format summary
 ```
 
 After editing `.umem/skills/review-protocol/SKILL.md`, refresh one runtime skill with:
@@ -263,7 +279,7 @@ your shell `PATH`.
 
 ## Managing Agent Skills
 
-You can create, import, list, inspect, and sync specialized behaviors:
+You can draft, create, adopt, import, validate, maintain, and sync specialized behaviors:
 ```bash
 # List all active skills
 umem skills list
@@ -271,14 +287,30 @@ umem skills list
 # Inspect one skill
 umem skills detail review-protocol
 
-# Create a new canonical skill
-umem skills create --name "Review Protocol" --description "Reusable review workflow"
+# Draft, validate, and publish without native runtime writes
+umem skills draft create --name "Review Protocol" --description "Reusable review workflow"
+umem skills draft validate review-protocol
+umem skills publish review-protocol
+
+# Create a new canonical skill and explicitly sync native targets
+umem skills create --name "Review Protocol" --description "Reusable review workflow" --sync
 
-# Adopt an existing native skill and distribute complete runtime copies
+# Adopt existing canonical work
+umem skills adopt .umem/skills/review-protocol --scope project
+
+# Import an existing native skill and distribute complete runtime copies
 umem skills import .agents/skills/review-protocol --scope project --sync
 
+# Validate and maintain canonical skills
+umem skills validate review-protocol
+umem skills canonical update review-protocol --file .umem/skills/review-protocol/SKILL.md
+umem skills rename review-protocol --slug review-checklist
+umem skills cleanup review-checklist --targets --format summary
+umem skills cleanup review-checklist --targets --apply
+umem skills repair --remove-orphan-targets --format summary
+
 # Synchronize one canonical skill into active native runtime folders
-umem skills sync review-protocol
+umem skills sync review-protocol --check-gitignore --format summary
 
 # Synchronize all active canonical skills during maintenance
 umem update --skills

{universal_memory-0.2.1 → universal_memory-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "universal-memory"
-version = "0.2.1"
+version = "0.3.0"
 description = "Vendor-agnostic cognitive persistence layer for AI agents."
 readme = "README.md"
 license = { text = "Apache-2.0" }

{universal_memory-0.2.1 → universal_memory-0.3.0}/src/universal_memory/__init__.py

@@ -5,4 +5,4 @@ from importlib.metadata import PackageNotFoundError, version
 try:
     __version__ = version("universal-memory")
 except PackageNotFoundError:
-    __version__ = "0.2.1"
+    __version__ = "0.3.0"

{universal_memory-0.2.1 → universal_memory-0.3.0}/src/universal_memory/application/onboarding/setup_project.py

@@ -273,7 +273,9 @@ approval, generation, activation, deactivation, and updates.
 ## Use Cases
 
 - Track a recurring workflow or methodology as a latent skill candidate.
+- Draft a skill when content may need validation before publish.
 - Create a skill directly when the user already knows the desired skill.
+- Adopt existing canonical work in place when it already lives under `.umem/skills/<slug>/`.
 - Import an existing local or native skill directory into the canonical `.umem/skills`
   registry.
 - Sync canonical skills into supported native runtime targets after import or changes.
@@ -290,8 +292,20 @@ approval, generation, activation, deactivation, and updates.
 ```bash
 umem skills list --format json
 umem skills detail <skill-id-or-name> --format json
-umem skills create --name "Skill name" --description "What the skill does." --scope project --trigger "when to use it" --format json
+umem skills draft create --name "Skill name" --description "What the skill does." --scope project --trigger "when to use it" --format json
+umem skills draft validate <draft-or-path> --format json
+umem skills publish <draft-or-path> --format summary
+umem skills create --name "Skill name" --description "What the skill does." --scope project --trigger "when to use it" --format summary
+umem skills adopt .umem/skills/<skill-name> --scope project --format summary
 umem skills import .agents/skills/<skill-name> --scope project --sync --format json
+umem skills validate <skill-id-or-name-or-path> --format json
+umem skills canonical update <skill-id-or-name> --file <relative-markdown-path> --format json
+umem skills rename <skill-id-or-name> --slug <new-slug> --format json
+umem skills cleanup <skill-id-or-name> --targets --format summary
+umem skills cleanup <skill-id-or-name> --targets --apply --format summary
+umem skills repair --remove-orphan-targets --format summary
+umem skills repair --remove-orphan-targets --apply --format summary
+umem skills sync <skill-id-or-name> --check-gitignore --format summary
 umem skills import .agents/skills/<skill-name>/SKILL.md --scope project --replace-native --sync --format json
 umem skills sync <skill-id-or-name> --format json
 umem skills track --name "Skill name" --description "What the skill does." --scope project --evidence-summary "Why this pattern recurred." --tag workflow --format json
@@ -336,13 +350,27 @@ and does not prompt for overwrite. Use explicit `umem skills sync <skill-id-or-n
 - `--trigger <text>`: repeatable trigger used in generated skill frontmatter.
 - `--file <relative-markdown-path>`: complete replacement markdown for `SKILL.md`.
 - `--format json`: canonical automation output.
+- `--format summary`: concise human and agent-facing output with status, paths, warnings,
+  dry-run/apply status, and next steps.
+- `--check-gitignore`: sync diagnostic that warns when generated native runtime targets
+  are tracked by git or not covered by ignore rules. The check runs after target planning/writes
+  and is diagnostic only: do not edit `.gitignore` or untrack files from this warning alone.
+  In automation, report the warning and let repository policy decide whether ignore rules should change.
 
 ## MCP Equivalents
 
 - `list_skills()`
 - `get_skill_detail(name_or_id="<skill-id-or-name>")`
-- `create_skill(name="Skill name", description="What the skill does.", scope="project", raw_markdown="<complete SKILL.md content>")`
+- `create_skill_draft(name="Skill name", description="What the skill does.", scope="project")`
+- `validate_skill(skill_or_path="<skill-id-or-name-or-path>")`
+- `publish_skill(draft_or_path="<draft-or-path>", sync=false)`
+- `create_skill(name="Skill name", description="What the skill does.", scope="project", raw_markdown="<complete SKILL.md content>", sync=false)`
+- `adopt_skill(path=".umem/skills/<skill-name>", scope="project", sync_after_adopt=false)`
 - `import_skill(path=".agents/skills/<skill-name>", scope="project", replace_native=false, sync_after_import=true)`
+- `update_canonical_skill(skill_id_or_name="<skill-id-or-name>", raw_markdown="<complete SKILL.md content>", sync=false)`
+- `rename_skill(skill_id_or_name="<skill-id-or-name>", slug="<new-slug>")`
+- `cleanup_skill(skill_id_or_name="<skill-id-or-name>", targets=true, dry_run=true)`
+- `repair_skills(remove_orphan_targets=true, dry_run=true)`
 - `sync_skills(skill_id_or_name="<skill-id-or-name>", targets=null, drift_decision="keep")`
 - `track_latent_skill(name="Skill name", description="What the skill does.", scope="project", evidence_summary="Why this pattern recurred.", tags=["workflow"])`
 - `recommend_skills(scope="project", min_recurrence=null, dry_run=true)`
@@ -361,14 +389,25 @@ and does not prompt for overwrite. Use explicit `umem skills sync <skill-id-or-n
 - `skills list` returns active, candidate, and disabled skills with relative paths when
   materialized.
 - `skills detail` returns triggers and metadata without loading large references.
-- `skills create` writes a requested canonical skill directly; use it when the user asks
-  for a known skill instead of routing through latent tracking.
+- `skills draft create` writes editable draft content only; validate and publish before sync.
+- `skills create` writes a requested canonical skill directly and does not sync native
+  targets unless `--sync` is present.
+- `skills publish` converts a draft to canonical and does not sync native targets unless
+  `--sync` is present.
+- `skills adopt` registers existing `.umem/skills/<slug>` work in place without creating a suffixed duplicate.
+- Use `skills import`, not `skills adopt`, for existing native runtime directories such
+  as `.agents/skills/<slug>` or `.opencode/skills/<slug>`.
+- `skills validate`, `skills canonical update`, `skills rename`, `skills cleanup`, and
+  `skills repair` are the supported maintenance path for canonical skills.
 - `skills import` is the normal path for an existing `.agents/skills/...`, `.opencode/skills/...`,
   or other local Agent Skills directory. It registers a canonical UMEM skill and copies
   the source directory into `.umem/skills/<slug>/`.
 - `skills sync` materializes canonical skills into configured native runtime targets;
   importing a skill does not necessarily make it available to every runtime until sync
   runs.
+- `skills sync --check-gitignore --format summary` is the preferred interactive safety
+  check when a user wants actionable warnings about tracked or unignored runtime targets.
+  It warns after sync planning/writes and never edits `.gitignore` or untracks files.
 - `skills sync` can create or update runtime directories such as `.opencode/skills/...`,
   `.agents/skills/...`, or `.antigravity/...` depending on configured runtimes. Treat these
   as intentional worktree changes and review whether repository ignore rules should include
@@ -386,10 +425,13 @@ and does not prompt for overwrite. Use explicit `umem skills sync <skill-id-or-n
 - `skills generate` creates canonical files under `.umem/skills/` for project skills.
 - `skills deactivate` preserves files and changes status to disabled.
 - `skills activate` requires a readable, valid `SKILL.md`.
-- `skills update`, `activate`, and `deactivate` currently operate on latent/generated skill
-  IDs, not the canonical `skill_id` returned by imported Agent Skills. If you have a
-  canonical skill under `.umem/skills/<slug>/`, edit that `SKILL.md` through the normal file
-  workflow, then run `umem skills sync <slug> --format json` to refresh native targets.
+- `skills update`, `activate`, and `deactivate` operate on latent/generated skill IDs.
+  For canonical Agent Skills, use `skills canonical update`, `skills rename`, `skills cleanup`,
+  `skills repair`, and `skills sync`.
+- `skills cleanup` previews cleanup for one canonical skill by default; add `--apply`
+  only after reviewing removable and blocked paths.
+- `skills repair` previews project-wide orphan target cleanup by default; add
+  `--remove-orphan-targets --apply` only after reviewing the summary.
 - `host sync --apply` should be non-interactive in agent automation: use
   `umem host sync --apply --yes --format json`.
 
@@ -618,6 +660,15 @@ CLI commands with `--format json` and MCP tools should return equivalent payload
 | Host sync | `umem host sync --apply --yes --format json` | `sync_instructions(apply=true)` |
 | Skills list | `umem skills list --format json` | `list_skills()` |
 | Skill detail | `umem skills detail <skill-id-or-name> --format json` | `get_skill_detail(name_or_id="<skill-id-or-name>")` |
+| Skill draft create | `umem skills draft create ... --format json` | `create_skill_draft(...)` |
+| Skill validate | `umem skills validate <skill-or-path> --format json` | `validate_skill(skill_or_path="<skill-or-path>")` |
+| Skill publish | `umem skills publish <draft-or-path> --format json` | `publish_skill(draft_or_path="<draft-or-path>")` |
+| Skill create | `umem skills create ... --format json` | `create_skill(...)` |
+| Skill adopt | `umem skills adopt <path> --format json` | `adopt_skill(path="<path>")` |
+| Skill canonical update | `umem skills canonical update <skill> --file <path> --format json` | `update_canonical_skill(...)` |
+| Skill rename | `umem skills rename <skill> --slug <slug> --format json` | `rename_skill(...)` |
+| Skill cleanup | `umem skills cleanup <skill> --targets --format json` | `cleanup_skill(...)` |
+| Skill repair | `umem skills repair --remove-orphan-targets --format json` | `repair_skills(...)` |
 | Track skill | `umem skills track ... --format json` | `track_latent_skill(...)` |
 | Recommend skills | `umem skills recommend --scope project --format json` | `recommend_skills(scope="project", dry_run=true)` |
 | Propose skill | `umem skills propose <latent-skill-id> --decision yes --format json` | `propose_skill(latent_skill_id="<latent-skill-id>", decision="yes")` |
@@ -625,7 +676,7 @@ CLI commands with `--format json` and MCP tools should return equivalent payload
 | Generate skill | `umem skills generate <latent-skill-id> --yes --format json` | `generate_skill(latent_skill_id="<latent-skill-id>")` |
 | Activate skill | `umem skills activate <latent-skill-id> --format json` | `activate_skill(latent_skill_id="<latent-skill-id>")` |
 | Deactivate skill | `umem skills deactivate <latent-skill-id> --format json` | `deactivate_skill(latent_skill_id="<latent-skill-id>")` |
-| Update skill | `umem skills update <latent-skill-id> ... --format json` | `update_skill(...)` |
+| Update latent/generated skill | `umem skills update <latent-skill-id> ... --format json` | `update_skill(...)` |
 
 ## Error Mapping
 

{universal_memory-0.2.1 → universal_memory-0.3.0}/src/universal_memory/application/skills/__init__.py

@@ -1,8 +1,30 @@
+from universal_memory.application.skills.adopt_skill import (
+    AdoptSkillCommand,
+    AdoptSkillResult,
+    AdoptSkillUseCase,
+)
+from universal_memory.application.skills.cleanup_skill import (
+    CleanupPlan,
+    CleanupSkillCommand,
+    CleanupSkillResult,
+    CleanupSkillUseCase,
+    RepairSkillsCommand,
+    RepairSkillsResult,
+    RepairSkillsUseCase,
+)
 from universal_memory.application.skills.create_skill import (
     CreateSkillCommand,
     CreateSkillResult,
     CreateSkillUseCase,
 )
+from universal_memory.application.skills.draft_skill import (
+    CreateSkillDraftCommand,
+    CreateSkillDraftUseCase,
+    DraftSkillResult,
+    PublishSkillCommand,
+    PublishSkillResult,
+    PublishSkillUseCase,
+)
 from universal_memory.application.skills.generate_skill import (
     GenerateSkillCommand,
     GenerateSkillResult,
@@ -39,6 +61,11 @@ from universal_memory.application.skills.recommend_skills import (
     RecommendSkillsUseCase,
     SkillRecommendationItem,
 )
+from universal_memory.application.skills.rename_skill import (
+    RenameSkillCommand,
+    RenameSkillResult,
+    RenameSkillUseCase,
+)
 from universal_memory.application.skills.sync_skills import (
     SyncSkillResult,
     SyncSkillsCommand,
@@ -57,21 +84,41 @@ from universal_memory.application.skills.update_skill import (
     DeactivateSkillCommand,
     DeactivateSkillResult,
     DeactivateSkillUseCase,
+    UpdateCanonicalSkillCommand,
+    UpdateCanonicalSkillResult,
+    UpdateCanonicalSkillUseCase,
     UpdateSkillCommand,
     UpdateSkillResult,
     UpdateSkillUseCase,
 )
+from universal_memory.application.skills.validate_skill import (
+    SkillValidationCheck,
+    SkillValidationReport,
+    ValidateSkillCommand,
+    ValidateSkillResult,
+    ValidateSkillUseCase,
+)
 
 __all__ = [
     "ActivateSkillCommand",
     "ActivateSkillResult",
     "ActivateSkillUseCase",
+    "AdoptSkillCommand",
+    "AdoptSkillResult",
+    "AdoptSkillUseCase",
+    "CleanupPlan",
+    "CleanupSkillCommand",
+    "CleanupSkillResult",
+    "CleanupSkillUseCase",
     "CreateSkillCommand",
+    "CreateSkillDraftCommand",
+    "CreateSkillDraftUseCase",
     "CreateSkillResult",
     "CreateSkillUseCase",
     "DeactivateSkillCommand",
     "DeactivateSkillResult",
     "DeactivateSkillUseCase",
+    "DraftSkillResult",
     "GenerateSkillCommand",
     "GenerateSkillResult",
     "GenerateSkillUseCase",
@@ -91,11 +138,22 @@ __all__ = [
     "ProposeSkillDecision",
     "ProposeSkillResult",
     "ProposeSkillUseCase",
+    "PublishSkillCommand",
+    "PublishSkillResult",
+    "PublishSkillUseCase",
     "RecommendSkillsCommand",
     "RecommendSkillsResult",
     "RecommendSkillsUseCase",
+    "RenameSkillCommand",
+    "RenameSkillResult",
+    "RenameSkillUseCase",
+    "RepairSkillsCommand",
+    "RepairSkillsResult",
+    "RepairSkillsUseCase",
     "SkillListItem",
     "SkillRecommendationItem",
+    "SkillValidationCheck",
+    "SkillValidationReport",
     "SyncSkillResult",
     "SyncSkillsCommand",
     "SyncSkillsResult",
@@ -103,7 +161,13 @@ __all__ = [
     "TrackLatentSkillCommand",
     "TrackLatentSkillResult",
     "TrackLatentSkillUseCase",
+    "UpdateCanonicalSkillCommand",
+    "UpdateCanonicalSkillResult",
+    "UpdateCanonicalSkillUseCase",
     "UpdateSkillCommand",
     "UpdateSkillResult",
     "UpdateSkillUseCase",
+    "ValidateSkillCommand",
+    "ValidateSkillResult",
+    "ValidateSkillUseCase",
 ]

universal_memory-0.3.0/src/universal_memory/application/skills/adopt_skill.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from universal_memory.application.security import SafeWriteUseCase
+from universal_memory.application.skills.create_skill import _hash_text
+from universal_memory.application.skills.import_skill import ImportSkillCommand, ImportSkillUseCase
+from universal_memory.application.skills.update_skill import _parse_skill_markdown, _slug
+from universal_memory.application.skills.validate_skill import (
+    assert_validation_passes,
+    validate_skill_tree,
+    validate_slug,
+)
+from universal_memory.domain import ValidationFailedError
+from universal_memory.domain.entities import (
+    AgentSkill,
+    AgentSkillStatus,
+    LatentSkillScope,
+    RuntimeRegistry,
+)
+from universal_memory.domain.ports import AgentSkillRepository
+
+
+@dataclass(frozen=True, slots=True)
+class AdoptSkillCommand:
+    path: str | Path
+    scope: LatentSkillScope
+    origin: str
+    slug: str | None = None
+    replace_native: bool = False
+    sync_after_adopt: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class AdoptSkillResult:
+    agent_skill: AgentSkill
+    slug: str
+    skill_dir: str
+    skill_file: str
+    adopted_source: str
+    affected_paths: list[str]
+    audit_reference: str
+    snapshot_reference: str
+    native_installations: list[dict[str, Any]] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+    def to_payload(self) -> dict[str, Any]:
+        return {
+            "skill_id": self.agent_skill.id,
+            "name": self.agent_skill.name,
+            "slug": self.slug,
+            "skill_dir": self.skill_dir,
+            "skill_file": self.skill_file,
+            "adopted_source": self.adopted_source,
+            "affected_paths": self.affected_paths,
+            "audit_reference": self.audit_reference,
+            "snapshot_reference": self.snapshot_reference,
+            "native_installations": self.native_installations,
+            "warnings": self.warnings,
+            "canonical_skill": {
+                "id": self.agent_skill.id,
+                "name": self.agent_skill.name,
+                "description": self.agent_skill.description,
+                "scope": self.agent_skill.scope.value,
+                "status": self.agent_skill.status.value,
+                "canonical_path": self.agent_skill.canonical_path,
+                "origin": self.agent_skill.origin,
+                "content_hash": self.agent_skill.content_hash,
+            },
+        }
+
+
+class _AdoptSkillSchema(BaseModel):
+    model_config = ConfigDict(extra="forbid", from_attributes=True)
+
+    path: str | Path
+    scope: LatentSkillScope
+    origin: str = Field(min_length=1)
+    slug: str | None = None
+    replace_native: bool = False
+    sync_after_adopt: bool = False
+
+
+class AdoptSkillUseCase:
+    def __init__(
+        self,
+        *,
+        project_root: Path,
+        repository: AgentSkillRepository,
+        safe_write_use_case: SafeWriteUseCase,
+        global_safe_write_use_case: SafeWriteUseCase | None = None,
+        runtime_registry: RuntimeRegistry | None = None,
+    ) -> None:
+        self.project_root = project_root.resolve()
+        self.repository = repository
+        self.safe_write_use_case = safe_write_use_case
+        self.global_safe_write_use_case = global_safe_write_use_case or safe_write_use_case
+        self.import_use_case = ImportSkillUseCase(
+            project_root=project_root,
+            repository=repository,
+            safe_write_use_case=safe_write_use_case,
+            global_safe_write_use_case=global_safe_write_use_case,
+            runtime_registry=runtime_registry,
+        )
+
+    def execute(self, command: AdoptSkillCommand) -> AdoptSkillResult:
+        validated = _AdoptSkillSchema.model_validate(command)
+        source_dir = _source_dir(self.project_root, Path(validated.path))
+        skill_file = source_dir / "SKILL.md"
+        markdown = skill_file.read_text(encoding="utf-8")
+        parsed = _parse_skill_markdown(markdown)
+        slug = validate_slug(validated.slug.strip() if validated.slug else _slug(parsed.name))
+        canonical_dir = _skill_dir_for(validated.scope, slug)
+        canonical_file = f"{canonical_dir}/SKILL.md"
+        report = validate_skill_tree(skill_file, project_root=self.project_root, subject=slug)
+        assert_validation_passes(report)
+        for existing in self.repository.list(scope=validated.scope):
+            if existing.slug == slug:
+                raise ValidationFailedError(f"Skill slug already exists: {slug}")
+
+        if _is_canonical_source(self.project_root, source_dir, canonical_dir):
+            now = datetime.now(UTC)
+            skill = AgentSkill(
+                id=str(uuid4()),
+                created_at=now,
+                updated_at=now,
+                name=parsed.name,
+                slug=slug,
+                description=parsed.description,
+                scope=validated.scope,
+                status=AgentSkillStatus.active,
+                canonical_path=canonical_file,
+                origin=validated.origin,
+                audit_reference="",
+                content_hash=_hash_text(markdown),
+                metadata={
+                    "triggers": parsed.triggers,
+                    "creation_flow": "adopt",
+                    "adopt_source": _relative_display(self.project_root, source_dir),
+                    "validation": report.to_payload(),
+                },
+            )
+            registry_write = self.repository.write(skill, origin=validated.origin)
+            return AdoptSkillResult(
+                agent_skill=skill,
+                slug=slug,
+                skill_dir=canonical_dir,
+                skill_file=canonical_file,
+                adopted_source=_relative_display(self.project_root, source_dir),
+                affected_paths=[canonical_file],
+                audit_reference=registry_write.audit_reference
+                if registry_write is not None
+                else "",
+                snapshot_reference=registry_write.snapshot_reference
+                if registry_write is not None
+                else "",
+                warnings=report.warnings,
+            )
+
+        imported = self.import_use_case.execute(
+            ImportSkillCommand(
+                path=source_dir,
+                scope=validated.scope,
+                origin=validated.origin,
+                replace_native=validated.replace_native,
+                sync_after_import=validated.sync_after_adopt,
+                slug=slug,
+            )
+        )
+        skill = imported.agent_skill.model_copy(
+            update={"metadata": {**imported.agent_skill.metadata, "creation_flow": "adopt"}}
+        )
+        self.repository.replace(skill, origin=validated.origin)
+        return AdoptSkillResult(
+            agent_skill=skill,
+            slug=imported.slug,
+            skill_dir=imported.skill_dir,
+            skill_file=imported.skill_file,
+            adopted_source=_relative_display(self.project_root, source_dir),
+            affected_paths=imported.affected_paths,
+            audit_reference=imported.audit_reference,
+            snapshot_reference=imported.snapshot_reference,
+            native_installations=imported.native_installations,
+            warnings=[*report.warnings, *imported.warnings],
+        )
+
+
+def _source_dir(project_root: Path, path: Path) -> Path:
+    source = path if path.is_absolute() else project_root / path
+    if source.is_file():
+        source = source.parent
+    if not (source / "SKILL.md").is_file():
+        raise ValidationFailedError("Adopt path must be a skill directory or SKILL.md file.")
+    return source.resolve()
+
+
+def _is_canonical_source(project_root: Path, source_dir: Path, canonical_dir: str) -> bool:
+    return source_dir == (project_root / canonical_dir).resolve()
+
+
+def _skill_dir_for(scope: LatentSkillScope, slug: str) -> str:
+    return f"skills/{slug}" if scope == LatentSkillScope.global_ else f".umem/skills/{slug}"
+
+
+def _relative_display(project_root: Path, path: Path) -> str:
+    try:
+        return path.resolve().relative_to(project_root.resolve()).as_posix()
+    except ValueError:
+        return path.as_posix()