skills-manual · v1.4.0 · 2026-10-17 · sha256 9a19113a3ffddeeb
skills-manual v1.4.0A
Immutable. This exact content never changes and is served at /api/v1/blob/9a19113a3ffddeeb.
---
name: skills-manual
description: >
Read before authoring, installing, or sharing a skill in
`.library/custom/<name>/`, adding configured skill roots, or diagnosing a
catalog entry; this teaches the Skills system, not bundled skill procedures.
version: 1.4.0
last_changed_at: "2026-10-17T00:00:00Z"
related_files:
- src/lingtai/tools/skills/manual/reference/cleanup-footprint-contract.md
- src/lingtai/tools/skills/manual/assets/skill-template.md
- src/lingtai/tools/skills/manual/scripts/validate.py
- src/lingtai/tools/skills/__init__.py
- src/lingtai/tools/skills/ANATOMY.md
- src/lingtai/tools/skills/CONTRACT.md
maintenance: |
Keep this router aligned with the Skills capability, its installed template and
validator, the nested-reference routing shape, and the cleanup reference.
---
# Skills Manual
Skills are reusable, portable procedures. The capability scans `.library/` plus
configured and automatically discovered standard roots, builds a compact YAML
catalog, and injects that catalog into the prompt. A skill is usable only after it is installed in a scanned root **and** a
catalog rebuild (or passive refresh/molt) has picked it up. A URL, temporary clone,
or newly written file is not loaded yet.
## Sources and roots
```text
<agent>/.library/
├── intrinsic/ # CLI-managed; rewritten on refresh; do not edit
│ ├── capabilities/<cap>/ # installed capability manuals
│ └── addons/<addon>/
└── custom/ # agent-owned skills
```
Additional roots are `manifest.capabilities.skills.paths` in `init.json` (the
configuration ground truth). A plain rebuild rescans already configured roots; it
does not reread changed configuration. To add a root, obtain authorization, exact
edit `init.json`, then apply the full refresh envelope:
```text
system(action="refresh",
input={"reason": "pick up new skills paths", "preset": null, "revert_preset": null},
reasoning="apply changed skills configuration")
```
`.library_shared/` is opt-in, not a default; ordinary sharing installs into each
receiver's `custom/`. If Skills is disabled, files remain on disk but no catalog is
injected.
## Automatic standard folders
No configuration or copying is needed for an existing vanilla skill in these
folders. Setup and full-context rebuild/refresh discover them in this order,
after `.library/intrinsic`, `.library/custom`, and configured roots:
1. `.agents/skills`, then `.claude/skills` in the agent working directory.
2. The same two roots at each parent through the nearer of a `.git` boundary
(directory or worktree file) or the project above a literal `.lingtai`
ancestor, the latter only when the current working directory has `init.json`.
This is LingTai's bounded project convention, not Codex outside-repo search.
**Without either valid boundary, parents are not eligible**.
3. `~/.agents/skills`, then `~/.claude/skills` for the process user.
Missing folders are normal. This uses the Agent's working directory, not shell
cwd, and never searches sibling projects or recursively searches all of home.
Canonical root aliases are scanned once, first occurrence retained. Symlinked
skill folders use the existing scanner; distinct roots with the same skill name
remain separate catalog entries, not a vendor-specific override/merge. Keep
`description` frontmatter (an omitted `name` uses its containing directory): malformed/read-failed entries retain the
usual problems report. Rebuilds rescan files, not changed configuration.
This adds folder conventions only: no `/etc/codex/skills`, vendor bundled,
managed/cloud skills, plugin synchronization, Claude `!` shell substitutions,
hooks/commands, or per-turn filesystem watcher.
Registered plugin skills stay in the separate plugin field and do not enter
this vanilla catalog. Discovery does not install, execute, or authorize a skill.
Read the cataloged `location` on demand and review external content before use.
Convention references (checked 2026-10-17):
[Codex skills](https://developers.openai.com/codex/skills/), currently redirecting
to [Build skills](https://learn.chatgpt.com/docs/build-skills), and
[Claude Code skills](https://code.claude.com/docs/en/skills).
## Public route and first action
```text
psyche(action="skills", input={}, reasoning="load skills guidance")
```
This strict-empty signpost performs no scan, injection, create, edit, or load.
Routine schema-sufficient calls need no ritual manual reload; read this route when
the catalog, roots, or skill lifecycle is unfamiliar. To inspect a cataloged body,
use its `location` with a bounded `shell` read:
```text
shell(action="run", input={"command": "sed -n '1,120p' -- \"<location>\"", "timeout": null, "working_dir": null, "async": null, "reminder": null}, reasoning="read cataloged skill, bounded")
```
A rebuild rescans `.library/`, configured roots, and automatic standard folders
and recomposes the Skills section, but a manual rebuild is strongly discouraged as routine (costly full
replay): prefer the next natural refresh/molt, and make one targeted
`context(action="rebuild", input={}, reasoning="rescan skills catalog")` only when
the catalog must change in this conversation and a molt is unsuitable. A degraded
manual result usually means the intrinsic manual was not installed correctly.
## Nested reference pattern
Use the **Nested skill/reference pattern for umbrella manuals** only when one
parent must route to substantial children. The catalog scanner treats a directory that already has a `SKILL.md` as a skill boundary, so the parent must inject children's routing metadata explicitly. Every parent carries both:
1. a `## Nested reference catalog` fenced YAML list (`name`, relative `location`,
`description`) for each child; and
2. a human-readable `## Routing table` mapping the same needs to the same paths.
The YAML is a machine-readable routing table, not decoration. Do not leave the parent as only a prose list of links. Child locations are relative to the parent
and each nested child has its own frontmatter:
```yaml
- name: parent-topic-a
location: reference/topic-a/SKILL.md
description: Nested child for the topic-a route
```
Keep this catalog and the human routing table in sync. For the broader example, enter `system-manual` →
`reference/substrate-manual/SKILL.md`. Validate the parent **and each child**
separately using the installed validator’s full path and each folder as its argument.
For example, from the parent folder:
`python3 <agent>/.library/intrinsic/capabilities/skills/scripts/validate.py reference/topic-a/`.
Child names must be unique within the parent; describe the parent and read trigger.
Verify the installed/copied child tree as well as parent metadata. Independent
workflows should remain top-level skills, not hidden children.
## External skill intake (default flow)
A shared URL or temporary clone is not installed: the skill is
only a file on disk until a reviewed copy reaches a scanned root. Copy/clone
into `<agent>/.library/custom/<skill-name>/`, retain useful upstream metadata, and
inspect `SKILL.md` plus referenced scripts/assets/references. For each install, run the bundled validator, then read the cataloged location after the next natural refresh/molt (a manual rebuild is a rare, discouraged exception when the skill must be cataloged in this conversation). Each receiving agent clones/copies it into its own `.library/custom/<name>`. Do not assume `.library_shared` is loaded by default. If a shared root is explicitly chosen, add `../.library_shared` to each participating agent's configured paths:
```text
python3 .library/intrinsic/capabilities/skills/scripts/validate.py .library/custom/<skill-name>/
# Only for the rare immediate-activation exception above, not every install:
context(action="rebuild", input={}, reasoning="rescan skills catalog")
```
`last_changed_at` is optional for custom/external skills. Add
`--require-last-changed-at` when validating a LingTai-maintained bundle; this is
not the default for third-party intake. Record the reviewed source URL/commit.
A quarantine copy is for inspection only; install the reviewed copy into `custom/`
before relying on it. To check for a name collision first, use the complete shell
call `shell(action="run", input={"command": "grep -rh '^name:' .library/", "timeout": null, "working_dir": null, "async": null, "reminder": null}, reasoning="check for skill-name collision")`. Check already configured extra roots too;
rename or reuse an existing skill on a collision. The example only scans `.library/`.
Installation never authorizes side effects described by the skill. For sharing, send the source URL or artifact path and this local-install /
validate / next-natural-reload recipe; each receiver owns its copy and rollback.
To author a skill, write it with `shell` from your working directory
(`mkdir -p .library/custom/<skill-name>`, then a quoted heredoc into
`.library/custom/<skill-name>/SKILL.md`, then `cat` it back to verify), and
put at least this frontmatter in the file:
```yaml
---
name: <skill-name>
description: What it does, when to use it, and when not to use it
version: 1.0.0
last_changed_at: "2026-09-09T00:00:00Z"
---
```
Use the bundled `assets/skill-template.md` as a starting point. Maintained bundles
must update `last_changed_at` with substantive edits. Validate frontmatter,
placeholders, referenced files, and script executability; warnings do not turn a
failed frontmatter or broken-reference check into a pass. The validator exits 0
only when required checks pass.
For maintained metadata-only/backfill changes, derive `last_changed_at` from
`git log -1 --format=%cI -- path/to/SKILL.md`, not the bookkeeping date. Required
frontmatter is `name` and `description`; version/author/tags remain optional.
Keep simple linear procedures flat; use a small router with self-contained
references for multi-topic work. Put brittle repeated operations in scripts and
concrete templates in assets. Create skills for reusable competence, not one-off
tasks or personality/style preferences (those belong in character/covenant).
A standalone published skill also needs a human-facing README (status, license,
contributors), separate from agent instructions. Publishing requires separate
authorization: copy authored content to a task-owned export directory before
initializing its repository; do not initialize a new repository inside the
existing agent tree. Retain reviewed upstream metadata for future sync/rollback.
Before publishing or trusting a skill, walk every routing branch, verify paths and
API claims against the code/filesystem, and repeat after corrections. This catches
stale signatures and fictional references that structural validation cannot.
## Catalog scope and settings
The catalog contains each entry's `name`, `description`, and `location`; read its
body only on demand. There is no Skills-owned settings file and no
`settings/psyche.skills.json`; Psyche's owner document does not configure Skills.
Pin a relevant body in Pad only through the Pad manual; let the next natural
reload activate it unless the rare immediate-activation exception applies.
## Cleanup / Footprint
Skills leave intrinsic and custom libraries plus any configured extra roots. Never
blindly delete intrinsic runtime state. For a read-only footprint report, load the
[shared recipe](reference/cleanup-footprint-contract.md#shared-footprint-check-recipe)
and select `.library/intrinsic/`, `.library/custom/`, and explicitly configured
roots; inspection writes nothing. Cleanup means reviewed validation, renaming,
consolidation, archive, or a PR—not ad-hoc removal. First show a dry-run, explain
what changes, obtain explicit user consent, and record approved work in
`logs/cleanup.jsonl`; let the next natural reload update the catalog, or use
the rare immediate-activation exception above. The recipe's audit append is a
separate explicit write.