2 added, 0 removed. Audit A to A.
# Skillager Agent Guide
This repository builds Skillager, a local CLI approval and activation layer for agent skills.
## Working Rules
- Treat the CLI as the public API. Prefer behavior-preserving changes and keep user-facing command contracts stable.
+ - Treat the personal library as the canonical ownership path for skills the user creates or explicitly imports. Preserve in-place external discovery; never migrate a project, package, environment, native, or collection skill into the library automatically.
- Treat discovery as part of the public product contract. Skillager should continue to find project skills, child skill repositories, project `.venv`/`venv` environment skills, installed package skills, and relevant native agent skill directories without users hand-wiring paths.
- Keep approval and exposure separate: approval records reviewed content hashes; exposure writes native, stub, or router skills for an agent.
- Do not expose full skill bodies in metadata commands. `working`, `list`, `search`, `show` without `--content`, `tag show`, `tag list`, and summary JSON outputs should stay metadata-only.
- `skillager.yaml` is structured metadata only. Searchable identity and prose come from `SKILL.md` and derived source provenance.
- Lint-blocked skills are quarantined until fixed or approved with an audited override reason.
- Missing compatibility metadata means usable by default. Only explicit incompatibility should block activation or exposure.
## Testing
Run the normal suite before handing off substantive changes:
```bash
uv run python -m unittest discover -s tests
```
For focused checks:
```bash
uv run python -m unittest tests.behavior.test_cli_contracts -v
uv run ruff check
```
Before committing, run the local full check on one interpreter:
```bash
uv run --python 3.13 python scripts/check.py
```
Behavioral tests live under `tests/behavior/`. They should run Skillager through the public CLI with subprocesses and isolated temp `HOME`, project state, catalog state, and cache directories. Prefer asserting stable behavior: exit codes, JSON fields, trust transitions, file creation, and body-leak boundaries.
## Docs Examples
Runnable docs examples should stay opt-in. Use an HTML comment immediately before a normal `bash` fence so rendered GitHub docs keep shell highlighting and hide the marker:
````markdown
<!-- skillager-test fixture=basic_project -->
```bash
skillager working --agent codex --json
```
````
Do not blindly execute every fenced command in docs. Examples with placeholders, installs, network access, global state, or interactive prompts need explicit fixtures or should remain prose-only examples.
## Product Workflows To Protect
- Fresh project safety gate: unreviewed skills are discoverable as metadata but cannot be activated or shown with content.
- Environment and package discovery: skills shipped in a project `.venv`, editable package source tree, or installed package are discovered without importing the package and still go through review before activation.
+ - Personal library lifecycle: owned skills remain pending after creation or edits until their exact hash is accepted; history is append-only, exposure updates are current-project and preview-first, and customized or pinned targets are not overwritten.
- Reviewed project skill path: setup approves low-risk content, search returns trusted metadata, stub/native exposure writes project files, and guarded activation emits the reviewed body.
- Router path: collection or tag inventory can be exposed through one compact router without loading every skill body.
- Working loop: agents run `skillager working` after context resets or resumed sessions; `handoff` is explicit post-setup curation/onboarding, not an automatic first prompt ritual.
- Lookback: session signals are compact behavioral hints, not automatic approval or exposure decisions.
## Release Notes
Keep README and docs aligned with CLI behavior when changing command names, flags, JSON schemas, or setup/handoff flow. The package includes `.agents/skills/simulate-skillager-setup`; changes to discovery, manifests, setup, handoff, exposure, packages, or collections should consider that black-box simulation workflow.