skillager 0.1.0__tar.gz

skillager-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Skillager Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

skillager-0.1.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.1
+Name: skillager
+Version: 0.1.0
+Summary: A Python environment skill registry and activation layer for coding agents.
+Requires-Python: >=3.11
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: rich>=15.0.0
+Provides-Extra: test
+License: MIT
+Keywords: agents,skills,codex,claude,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development
+Author: Skillager Contributors
+Description-Content-Type: text/markdown
+
+
+# Skillager
+
+Agent skills are useful. Loading all of them into every chat is not.
+
+Skillager is a local CLI that lets projects, Python libraries, tools, and personal skill repos ship useful agent skills without turning every session into a wall of instructions. It discovers skills, scans them, asks for human approval, and gives agents a small, fast way to find the right skill only when the task needs it.
+
+```text
+install package -> discover skills -> approve safety -> agent uses approved metadata -> expose only what matters
+```
+
+## Quickstart
+
+```bash
+uv tool install skillager
+cd my-project
+skillager status
+skillager setup
+```
+
+No uv:
+
+```bash
+pipx install skillager
+# or
+python -m pip install --user skillager
+python -m skillager setup
+```
+
+`setup` is the approval gate. It discovers skills in the current project and environment, scans them, asks what audience you care about, and never trusts a skill unless you approve it.
+
+After setup, restart Codex or Claude in the same directory and tell it what you are doing. Skillager installs a tiny project handoff so the agent knows to run `skillager status` once, use approved metadata, and avoid loading unapproved skill bodies.
+
+## The Problem
+
+Skills want to live everywhere:
+
+- inside libraries, next to the APIs they explain
+- inside projects, next to team workflows
+- inside global agent directories
+- inside personal or community skill repos
+
+But agents should not see every skill all the time. Irrelevant skills burn context. Unreviewed skills are a safety risk. Similar skills compete. Package-installed skills are hard for agents to discover.
+
+Skillager gives that ecosystem a local registry and approval gate.
+
+## The Mental Model
+
+Skillager keeps two decisions separate:
+
+- **Approval:** the user reviewed a skill at its current content hash.
+- **Exposure:** the skill is available to an agent in the current project.
+
+An approved skill does not have to be loaded into the agent. It can stay in Skillager's index until a task needs it. When it should be available, Skillager writes one of three project-level representations:
+
+- `native`: the full reviewed skill directory copied into the agent's project skill directory
+- `stub`: a tiny native handle that activates the full skill through Skillager on demand
+- `router`: one compact native skill for a curated tag like `gis`, `workflows`, or `release`
+
+This keeps the default context small while still giving agents a deterministic path to approved skills.
+
+## For Library Authors
+
+If you maintain a Python library, Skillager gives you a way to ship agent-facing guidance with the package itself. Users can discover those skills after install, review them locally, and expose all, or just the ones relevant to their project.
+
+Example:
+
+```text
+your_package/
+  __init__.py
+  .skills/
+    data-cleaning/
+      SKILL.md
+      skillager.yaml
+      references/
+      scripts/
+```
+
+When a user installs your package, Skillager can discover those skills without importing your library. The user still reviews and approves them before any agent can activate them.
+
+This lets a library ship:
+
+- user-facing skills for using the API well
+- maintainer skills for internal development workflows
+- domain skills that explain correctness rules and edge cases
+- migration skills for version upgrades
+
+See the [library author guide](docs/LIBRARY_AUTHORS.md) for metadata and packaging details.
+
+## What Skillager Does
+
+- Discovers skills from projects, `.venv`, installed packages, global agent dirs, and skill repos.
+- Scans full skill directories before approval.
+- Tracks trust by skill ID and content hash.
+- Keeps search/list/show metadata safe and compact for agents.
+- Materializes only reviewed skills into Codex or Claude native skill directories.
+- Supports stubs and routers for large skill collections.
+- Records compact local usage signals for lookback, without storing transcripts or skill bodies.
+- Treats manually installed native skills as user-installed while still warning on risk.
+
+## Safety Shape
+
+The built-in scanner is deterministic and local. It looks for common agent-risk patterns like instruction override attempts, hidden prompt requests, secret exfiltration language, credential paths, download-and-execute flows, network callbacks involving secrets, unattended approval language, shell execution requests, hidden control characters, encoded blobs, and oversized content.
+
+**It is not a proof of safety. It is a review aid.**
+
+The hard rule is simpler: agents should not activate, materialize, or rely on skills that have not been approved by the user or project trust store.
+
+## Skill Repos Without Context Flooding
+
+Skill repositories are collections. Collections are inventory; tags are curation; project attachment is intent.
+
+```bash
+skillager collection add ~/skills/workflows --name workflows
+skillager tag create workflows
+skillager tag add workflows workflows/diffuse workflows/brainstorm
+skillager project attach-tag workflows
+skillager setup
+skillager materialize --tag workflows --mode index --agent codex --scope project
+```
+
+The agent sees one router skill, not the whole repo. It activates a specific reviewed skill only when the task calls for it.
+
+## Lookback
+
+Skillager learns from usage as a local feedback loop. It records compact events such as search result IDs, activations, materialization status, and explicit feedback. It does not store chat transcripts or skill bodies.
+
+The next `skillager status` can tell the agent that lookback is pending. Then the user can decide whether to promote a repeatedly useful skill, keep a broad skill route-only, block an unwanted one, or resolve overlapping skills.
+
+## More Docs
+
+- [User guide](docs/USER_GUIDE.md)
+- [Agent CLI guide](docs/AGENT_CLI_GUIDE.md)
+- [Skill repositories](docs/SKILL_REPOSITORIES.md)
+- [Library author guide](docs/LIBRARY_AUTHORS.md)
+- [Safety model](docs/SAFETY_MODEL.md)
+- [Security policy](SECURITY.md)
+
+External contributions are not being accepted yet while the 0.1 API and workflow settle.
+
+## Development
+
+```bash
+uv run python -m unittest discover -s tests
+uv build
+```
+
+Skillager is released under the [MIT License](LICENSE).

skillager-0.1.0/README.md

@@ -0,0 +1,147 @@
+# Skillager
+
+Agent skills are useful. Loading all of them into every chat is not.
+
+Skillager is a local CLI that lets projects, Python libraries, tools, and personal skill repos ship useful agent skills without turning every session into a wall of instructions. It discovers skills, scans them, asks for human approval, and gives agents a small, fast way to find the right skill only when the task needs it.
+
+```text
+install package -> discover skills -> approve safety -> agent uses approved metadata -> expose only what matters
+```
+
+## Quickstart
+
+```bash
+uv tool install skillager
+cd my-project
+skillager status
+skillager setup
+```
+
+No uv:
+
+```bash
+pipx install skillager
+# or
+python -m pip install --user skillager
+python -m skillager setup
+```
+
+`setup` is the approval gate. It discovers skills in the current project and environment, scans them, asks what audience you care about, and never trusts a skill unless you approve it.
+
+After setup, restart Codex or Claude in the same directory and tell it what you are doing. Skillager installs a tiny project handoff so the agent knows to run `skillager status` once, use approved metadata, and avoid loading unapproved skill bodies.
+
+## The Problem
+
+Skills want to live everywhere:
+
+- inside libraries, next to the APIs they explain
+- inside projects, next to team workflows
+- inside global agent directories
+- inside personal or community skill repos
+
+But agents should not see every skill all the time. Irrelevant skills burn context. Unreviewed skills are a safety risk. Similar skills compete. Package-installed skills are hard for agents to discover.
+
+Skillager gives that ecosystem a local registry and approval gate.
+
+## The Mental Model
+
+Skillager keeps two decisions separate:
+
+- **Approval:** the user reviewed a skill at its current content hash.
+- **Exposure:** the skill is available to an agent in the current project.
+
+An approved skill does not have to be loaded into the agent. It can stay in Skillager's index until a task needs it. When it should be available, Skillager writes one of three project-level representations:
+
+- `native`: the full reviewed skill directory copied into the agent's project skill directory
+- `stub`: a tiny native handle that activates the full skill through Skillager on demand
+- `router`: one compact native skill for a curated tag like `gis`, `workflows`, or `release`
+
+This keeps the default context small while still giving agents a deterministic path to approved skills.
+
+## For Library Authors
+
+If you maintain a Python library, Skillager gives you a way to ship agent-facing guidance with the package itself. Users can discover those skills after install, review them locally, and expose all, or just the ones relevant to their project.
+
+Example:
+
+```text
+your_package/
+  __init__.py
+  .skills/
+    data-cleaning/
+      SKILL.md
+      skillager.yaml
+      references/
+      scripts/
+```
+
+When a user installs your package, Skillager can discover those skills without importing your library. The user still reviews and approves them before any agent can activate them.
+
+This lets a library ship:
+
+- user-facing skills for using the API well
+- maintainer skills for internal development workflows
+- domain skills that explain correctness rules and edge cases
+- migration skills for version upgrades
+
+See the [library author guide](docs/LIBRARY_AUTHORS.md) for metadata and packaging details.
+
+## What Skillager Does
+
+- Discovers skills from projects, `.venv`, installed packages, global agent dirs, and skill repos.
+- Scans full skill directories before approval.
+- Tracks trust by skill ID and content hash.
+- Keeps search/list/show metadata safe and compact for agents.
+- Materializes only reviewed skills into Codex or Claude native skill directories.
+- Supports stubs and routers for large skill collections.
+- Records compact local usage signals for lookback, without storing transcripts or skill bodies.
+- Treats manually installed native skills as user-installed while still warning on risk.
+
+## Safety Shape
+
+The built-in scanner is deterministic and local. It looks for common agent-risk patterns like instruction override attempts, hidden prompt requests, secret exfiltration language, credential paths, download-and-execute flows, network callbacks involving secrets, unattended approval language, shell execution requests, hidden control characters, encoded blobs, and oversized content.
+
+**It is not a proof of safety. It is a review aid.**
+
+The hard rule is simpler: agents should not activate, materialize, or rely on skills that have not been approved by the user or project trust store.
+
+## Skill Repos Without Context Flooding
+
+Skill repositories are collections. Collections are inventory; tags are curation; project attachment is intent.
+
+```bash
+skillager collection add ~/skills/workflows --name workflows
+skillager tag create workflows
+skillager tag add workflows workflows/diffuse workflows/brainstorm
+skillager project attach-tag workflows
+skillager setup
+skillager materialize --tag workflows --mode index --agent codex --scope project
+```
+
+The agent sees one router skill, not the whole repo. It activates a specific reviewed skill only when the task calls for it.
+
+## Lookback
+
+Skillager learns from usage as a local feedback loop. It records compact events such as search result IDs, activations, materialization status, and explicit feedback. It does not store chat transcripts or skill bodies.
+
+The next `skillager status` can tell the agent that lookback is pending. Then the user can decide whether to promote a repeatedly useful skill, keep a broad skill route-only, block an unwanted one, or resolve overlapping skills.
+
+## More Docs
+
+- [User guide](docs/USER_GUIDE.md)
+- [Agent CLI guide](docs/AGENT_CLI_GUIDE.md)
+- [Skill repositories](docs/SKILL_REPOSITORIES.md)
+- [Library author guide](docs/LIBRARY_AUTHORS.md)
+- [Safety model](docs/SAFETY_MODEL.md)
+- [Security policy](SECURITY.md)
+
+External contributions are not being accepted yet while the 0.1 API and workflow settle.
+
+## Development
+
+```bash
+uv run python -m unittest discover -s tests
+uv build
+```
+
+Skillager is released under the [MIT License](LICENSE).

skillager-0.1.0/build_backend/_skillager_build.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import base64
+import csv
+import hashlib
+import io
+import tarfile
+import zipfile
+from email.message import Message
+from pathlib import Path
+
+NAME = "skillager"
+VERSION = "0.1.0"
+DIST = f"{NAME}-{VERSION}"
+DIST_INFO = f"{NAME}-{VERSION}.dist-info"
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def build_wheel(wheel_directory, config_settings=None, metadata_directory=None):
+    wheel_name = f"{NAME}-{VERSION}-py3-none-any.whl"
+    wheel_path = Path(wheel_directory) / wheel_name
+    records: list[tuple[str, bytes]] = []
+    with zipfile.ZipFile(wheel_path, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+        for path in sorted((ROOT / "src" / NAME).rglob("*.py")):
+            arcname = f"{NAME}/{path.relative_to(ROOT / 'src' / NAME).as_posix()}"
+            data = path.read_bytes()
+            zf.writestr(arcname, data)
+            records.append((arcname, data))
+        metadata = _metadata().encode()
+        wheel = "Wheel-Version: 1.0\nGenerator: skillager-build\nRoot-Is-Purelib: true\nTag: py3-none-any\n".encode()
+        entry_points = "[console_scripts]\nskillager = skillager.cli:main\n".encode()
+        license_data = (ROOT / "LICENSE").read_bytes()
+        for arcname, data in (
+            (f"{DIST_INFO}/METADATA", metadata),
+            (f"{DIST_INFO}/WHEEL", wheel),
+            (f"{DIST_INFO}/entry_points.txt", entry_points),
+            (f"{DIST_INFO}/LICENSE", license_data),
+        ):
+            zf.writestr(arcname, data)
+            records.append((arcname, data))
+        record_path = f"{DIST_INFO}/RECORD"
+        zf.writestr(record_path, _record(records, record_path))
+    return wheel_name
+
+
+def build_editable(wheel_directory, config_settings=None, metadata_directory=None):
+    wheel_name = f"{NAME}-{VERSION}-py3-none-any.whl"
+    wheel_path = Path(wheel_directory) / wheel_name
+    records: list[tuple[str, bytes]] = []
+    with zipfile.ZipFile(wheel_path, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+        pth = str((ROOT / "src").resolve()) + "\n"
+        license_data = (ROOT / "LICENSE").read_bytes()
+        for arcname, data in (
+            (f"{NAME}.pth", pth.encode()),
+            (f"{DIST_INFO}/METADATA", _metadata().encode()),
+            (f"{DIST_INFO}/WHEEL", "Wheel-Version: 1.0\nGenerator: skillager-build\nRoot-Is-Purelib: true\nTag: py3-none-any\n".encode()),
+            (f"{DIST_INFO}/entry_points.txt", "[console_scripts]\nskillager = skillager.cli:main\n".encode()),
+            (f"{DIST_INFO}/LICENSE", license_data),
+        ):
+            zf.writestr(arcname, data)
+            records.append((arcname, data))
+        record_path = f"{DIST_INFO}/RECORD"
+        zf.writestr(record_path, _record(records, record_path))
+    return wheel_name
+
+
+def build_sdist(sdist_directory, config_settings=None):
+    sdist_name = f"{DIST}.tar.gz"
+    sdist_path = Path(sdist_directory) / sdist_name
+    include_roots = ["build_backend", "docs", "examples", "src", "tests"]
+    include_files = ["pyproject.toml", "README.md", "LICENSE"]
+    with tarfile.open(sdist_path, "w:gz", format=tarfile.PAX_FORMAT) as tf:
+        for filename in include_files:
+            path = ROOT / filename
+            if path.exists():
+                tf.add(path, arcname=f"{DIST}/{filename}")
+        for root_name in include_roots:
+            root = ROOT / root_name
+            if root.exists():
+                for path in sorted(item for item in root.rglob("*") if item.is_file() and not _excluded(item)):
+                    tf.add(path, arcname=f"{DIST}/{path.relative_to(ROOT).as_posix()}")
+        pkg_info = _metadata().encode()
+        info = tarfile.TarInfo(f"{DIST}/PKG-INFO")
+        info.size = len(pkg_info)
+        tf.addfile(info, io.BytesIO(pkg_info))
+    return sdist_name
+
+
+def prepare_metadata_for_build_wheel(metadata_directory, config_settings=None):
+    dist_info = Path(metadata_directory) / DIST_INFO
+    dist_info.mkdir(parents=True, exist_ok=True)
+    (dist_info / "METADATA").write_text(_metadata(), encoding="utf-8")
+    (dist_info / "WHEEL").write_text("Wheel-Version: 1.0\nGenerator: skillager-build\nRoot-Is-Purelib: true\nTag: py3-none-any\n", encoding="utf-8")
+    (dist_info / "entry_points.txt").write_text("[console_scripts]\nskillager = skillager.cli:main\n", encoding="utf-8")
+    return DIST_INFO
+
+
+def get_requires_for_build_wheel(config_settings=None):
+    return []
+
+
+def get_requires_for_build_editable(config_settings=None):
+    return []
+
+
+def get_requires_for_build_sdist(config_settings=None):
+    return []
+
+
+def _metadata() -> str:
+    message = Message()
+    message["Metadata-Version"] = "2.1"
+    message["Name"] = NAME
+    message["Version"] = VERSION
+    message["Summary"] = "A Python environment skill registry and activation layer for coding agents."
+    message["Requires-Python"] = ">=3.11"
+    message["Requires-Dist"] = "pyyaml>=6.0.3"
+    message["Requires-Dist"] = "rich>=15.0.0"
+    message["Provides-Extra"] = "test"
+    message["License"] = "MIT"
+    message["Keywords"] = "agents,skills,codex,claude,llm"
+    for classifier in (
+        "Development Status :: 3 - Alpha",
+        "Environment :: Console",
+        "License :: OSI Approved :: MIT License",
+        "Programming Language :: Python :: 3",
+        "Topic :: Software Development",
+    ):
+        message["Classifier"] = classifier
+    message["Author"] = "Skillager Contributors"
+    message["Description-Content-Type"] = "text/markdown"
+    body = (ROOT / "README.md").read_text(encoding="utf-8")
+    return message.as_string() + "\n" + body
+
+
+def _excluded(path: Path) -> bool:
+    if any(part in {".git", ".venv", ".skillager", ".codex", ".claude", ".agents"} for part in path.parts):
+        return True
+    if any(part.endswith(".egg-info") for part in path.parts):
+        return True
+    if any(part == "__pycache__" for part in path.parts):
+        return True
+    return path.suffix in {".pyc", ".pyo"}
+
+
+def _record(records: list[tuple[str, bytes]], record_path: str) -> str:
+    output = io.StringIO()
+    writer = csv.writer(output, lineterminator="\n")
+    for arcname, data in records:
+        digest = base64.urlsafe_b64encode(hashlib.sha256(data).digest()).decode().rstrip("=")
+        writer.writerow([arcname, f"sha256={digest}", str(len(data))])
+    writer.writerow([record_path, "", ""])
+    return output.getvalue()

skillager-0.1.0/docs/AGENT_CLI_GUIDE.md

@@ -0,0 +1,148 @@
+# Agent CLI Guide
+
+This document is for coding agents reading a project that uses Skillager.
+
+Projects may expose a first-party `skillager-working` skill. Treat it as the bootstrap workflow for Skillager-managed projects: check status, respect the user approval gate, ask what the user plans to do, then expose only the narrow router or native skills that fit the session.
+
+## Rules
+
+- Start with `skillager status` once per session.
+- If status reports `lookback_pending`, ask the user whether to review `skillager lookback` before starting. Do not apply recommendations without user approval.
+- Do not run `skillager setup`, `review`, `trust`, or `block` unless the user asked for setup or approval changes.
+- Do not run `skillager materialize` until you have asked what the user plans to do and can justify the narrow router/native exposure.
+- Do not run `skillager activate` or `skillager show --content` for a skill that is not already reviewed, trusted, or pinned.
+- Do not use `--force` unless the user explicitly instructs you to override Skillager's gate.
+- Prefer `--json` when parsing output.
+- Do not search Skillager on every user message. Search only when the task/domain changes, specialized help is likely useful, you are unsure how to proceed and an approved skill may contain the right workflow, status changed, or the user asks about skills.
+- Once you choose a native skill or router path for a task, keep using it until the task changes.
+
+## Safe Metadata Commands
+
+These commands do not expose full skill bodies. In a project, normal `list`, `search`, and `show` use effective project inventory: project skills, package/environment skills, and attached collection-tag skills with project-local trust state. `list` hides global native skills by default; pass `--include-global` only when the user is asking about global inventory.
+
+```bash
+skillager status --json
+skillager list --json
+skillager list --no-packages --json
+skillager search "<query>" --json
+skillager show <skill-id> --json
+skillager review --summary --json
+skillager search "<user goal>" --trusted-only --json
+skillager tag show <tag> --json
+```
+
+Use `collection search/show` only for catalog management or debugging. For project work, prefer the normal project-aware commands above.
+`status --json` and `search --json` are intentionally compact for agent use. Use `--full-json` only when debugging Skillager metadata itself.
+`status --json` includes `lookback_pending` and `lookback_summary`; these are next-session hints only. Ask the user before running the full lookback or changing exposure.
+
+Project-aware JSON includes:
+
+- `availability`: where the skill comes from in this project context.
+- `trust`: effective project-local trust state.
+- `trust_reason`: why Skillager treats a skill as trusted, when relevant. `user-installed` means the user placed it directly in an agent-native skill directory.
+- `exposure`: `hidden`, `native`, `stub`, `router`, or `multiple`.
+- `materialized_targets`: agent/scope/path/status records for native or router exposure.
+- `compatibility`: negative-only compatibility metadata. Missing metadata means "assume usable." `problem` is set only when the skill explicitly excludes the requested `--agent`.
+
+Do not treat `trust_reason=user-installed` as suspicious by itself. The user installed that native skill. Still respect scanner findings and high-risk warnings.
+
+## Compatibility
+
+Skillager defaults to compatibility. Do not hide a skill just because it was written in another agent's style.
+
+Use compatibility metadata this way:
+
+- If `skillager search --agent codex --json` reports `compatibility.problem`, do not activate or materialize that skill for Codex unless the user explicitly approves `--allow-incompatible`.
+- If `activation_warnings` are present without `problem`, the skill is still available. Treat the warning as adaptation guidance.
+- Prefer `--compatible-only --agent <agent>` only when the user asks for skills that can be used without adaptation.
+- Do not infer incompatibility from advisory warnings alone.
+
+Activation and native/stub materialization refuse explicit incompatibility by default:
+
+```bash
+skillager activate <skill-id> --agent codex
+skillager materialize <skill-id> --agent codex
+```
+
+The explicit override is:
+
+```bash
+skillager activate <skill-id> --agent codex --allow-incompatible
+skillager materialize <skill-id> --agent codex --allow-incompatible
+```
+
+## Agentic Setup Flow
+
+After the user approves skills, setup installs or refreshes the `skillager-working` bootstrap skill for the chosen agent. The user may also have materialized a small always-relevant native set during setup. In the next agent session, ask what the user plans to do in the repo. Then use approved metadata to decide whether to expose:
+
+- a narrow native skill for a specific recurring workflow
+- a stub for an approved command the user wants easy access to by name
+- a router skill for a broad attached collection
+- nothing, if the existing project handoff is enough
+
+Prefer router materialization for broad skill repositories:
+
+```bash
+skillager materialize --tag workflows --mode index --agent codex --scope project
+```
+
+Prefer native materialization for narrow, high-signal project skills:
+
+```bash
+skillager materialize project/gis-domain --agent codex --scope project
+```
+
+Prefer stub materialization for approved commands the user wants discoverable without loading full instructions:
+
+```bash
+skillager materialize personal/deploy-preview --mode stub --agent codex --scope project
+```
+
+When a stub tells you to activate a skill, use the exact guarded command from the stub:
+
+```bash
+skillager activate <skill-id> --from-stub <stub-slug>
+```
+
+Do not materialize every approved skill just because it is approved. Approval means a skill is allowed to be considered; exposure should still be scoped to the user's stated work.
+
+At lookback time, prefer aggregate recommendations over single-session instinct. `skillager lookback` considers the recent session window plus active sessions and reports the sessions behind each recommendation. Do not promote or demote shared project-native exposure based on one isolated session unless the user explicitly asks.
+
+Lookback may include `observed_overlaps`. Treat these as behavioral hints, not decisions. They mean skills repeatedly co-occurred in searches or sessions. Ask the user whether to pin a winner, keep the skills route-only, stub commands, block old skills, or ignore the overlap.
+
+Search records compact local telemetry for lookback by default: query hash, short query preview, top result IDs, and filters. It does not record skill bodies, chat transcripts, or command output. Use `skillager search ... --no-session-record` for one-off searches that should not affect lookback.
+
+## User-Gated Commands
+
+These commands change approval state, write skill files, or expose full instructions:
+
+```bash
+skillager setup
+skillager setup --source collection --yolo
+skillager review <skill-id> --trust-selected reviewed
+skillager trust <skill-id>
+skillager block <skill-id>
+skillager materialize --agent codex --scope project
+skillager activate <skill-id>
+skillager show <skill-id> --content
+```
+
+## Router Skills
+
+A Skillager router skill is a compact project skill that lists reviewed skill IDs and author summaries. It does not contain the hidden skill bodies.
+
+When a router tells you to activate a skill, use:
+
+```bash
+skillager activate <skill-id> --from-router skillager-<tag>
+```
+
+This command refuses skills outside the attached tag, blocked skills, and unreviewed skills.
+
+## If Status Reports New Skills
+
+Tell the user exactly what happened and ask them to run setup:
+
+```text
+Skillager reports new or changed skills. Please run `skillager setup` from this project directory before I use Skillager-managed skills.
+```