feat(skills): adopt multi-file skill packages

AGENTS.md

@@ -198,6 +198,7 @@ packages/agent-core/src/
 ├── automations/                # Canonical Automation schemas, schedule, durable Invocation, Session dispatch
 ├── todos/                      # ProjectTodo schema, serialized state, and narrow Session-entry coordination
 ├── lsp/                        # LspClientPool (acquire/release, idle timeout, crash detection), StdioLspTransport, auto-installer, 18 language servers, 50+ ext mappings
+├── skills/                     # Standard local Skill packages: schema, package reader, source resolver, embedded builtin manifest
 ├── llm/                        # Managed LLM runtime: runLlmStream/runLlmText/runLlmObject, retry/recovery, adapter test seam
 ├── projects/                   # ProjectRegistry + per-workspace HITL/memory/approval context resolver
 ├── prompt/                     # PromptContractCompiler V2: typed kernel/runtime/role/collaboration/context/overlay layers + trace/eval
@@ -396,6 +397,10 @@ All six implement `Agent`: `store: StoreApi<SessionStoreState>`, `run(options) 
 - Ordinary root Lead activates `orchestrate-work`; active Goal activates `run-goal`; root Discussion activates `shape-todo`, derived from authoritative runtime facts on every Execution.
 - `plan-work` writes one ordinary Markdown Plan per Todo under `.archcode/plans/`. Plan has no service, state, ID, API, dedicated page, or Goal link. `execute-plan` is activated only by the Todo-to-work handoff when that file exists.
 - `review-work` guides Lead review orchestration. Analyst analysis/review Skills include `analyze-work`, `review-change`, and the reserved `goal-review` final gate.
+- A Skill is one package: required `SKILL.md`; optional `scripts/`, `references/`, `assets/`, and other contained resources. Its strict YAML frontmatter accepts `name`, `description`, optional `license`, `compatibility`, and `metadata`; `description` states both method and activation timing.
+- Discovery (`skill_list` and available Prompt metadata) returns exactly name, description, and source. Entry activation (`skill_read({ name })`) returns the entry plus sorted resource descriptors; `skill_read({ name, resource })` reads exactly one listed text resource on demand. Binary assets are valid package resources but are not returned by the text-only tool.
+- Project `.archcode/skills/<name>/` > user `~/.archcode/skills/<name>/` > embedded builtin is whole-package precedence: bodies and resources never merge or fall through. Reserved lifecycle builtins remain unshadowable and Agent-gated.
+- Skills remain guidance only: their package metadata and resources cannot grant tools or permissions, execute scripts automatically, change Agent/Profile/MCP/workspace scope/delegation, or grant completion authority. Scripts use only existing Bash permissions.
 
 **MCP visibility by agent:**
 

CHANGELOG.md

@@ -7,6 +7,24 @@ and this project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 
 ## [Unreleased]
 
+### Changed
+
+- Replace single-file workflow Skills with standard local Skill packages:
+  `SKILL.md` plus optional `scripts/`, `references/`, `assets/`, and other
+  contained resources. Skill discovery is metadata-only; entry and listed
+  resources are disclosed progressively.
+
+### Breaking Changes
+
+- Project and user Skills must use one directory per Skill:
+  `<skills-root>/<name>/SKILL.md`. Manually update existing entries to use only `name` and `description`
+  (required), with optional `license`, `compatibility`, and string-map
+  `metadata`. Move former activation guidance into `description`; move
+  supporting files beneath the package and reference them with package-relative
+  paths. `when_to_use`, `allowed_tools`, and all other
+  top-level frontmatter fields are rejected. There is no migration, fallback,
+  compatibility reader, or resource merge with lower-precedence packages.
+
 ## [0.0.8] - 2026-08-04
 
 ### Added

README.md

@@ -142,8 +142,8 @@ workbench.
 ## Built in
 
 - Structured file, shell, Git, search, LSP, Web, memory, and MCP tools
-- Built-in and project workflow Skills for Todo shaping, planning, review, and
-  repeatable working methods
+- Built-in and project workflow Skill packages for Todo shaping, planning,
+  review, and repeatable working methods
 - Project memory and context compaction
 - Optional Git worktree execution
 - GitHub and custom MCP integrations