Shape the _agent/
Canonical protocols: read form primitive for procedures, checklists, routines, and agents; read form perspective for reusable thinking patterns.
Which one
- Primitive — how to work in a situation: a procedure, checklist, review pattern, memory routine. Any part of
_agent/withname+descriptionfrontmatter (the description is the trigger). Use form primitive. - Perspective — how to think about something repeatably: an evaluation or analysis with Object Definition, Thinking Structure, Expected Outcome. Use form perspective.
If the user wants consistent evaluation/analysis, it's a perspective. If they want a repeatable procedure/behavior, it's a primitive.
How
Elicit progressively — don't demand the full structure up front. Start from a real instance ("walk me through the last time you did this"), find the invariant, draft, and show it before saving.
Primitives and perspectives live in _agent/ at the level where they apply; everything in _agent/ composes along the path root → current position.
Use native write / edit for _agent/skills/*, _agent/perspectives/*, and other agent-context primitives because they use name + description frontmatter, not Note name + summary frontmatter. For a skill, its entry id and frontmatter name must be the same portable id — follow the exact rule and worked example in form primitive. Pi warns at startup when a loaded skill violates it. Use is_write only when shaping ordinary Notes such as _agent/purpose.md or _agent/now.md that should carry Note-style summary frontmatter.
Preview, confirm, then write — the write gate in guide applies to shaping like any capture.
Shaping changes the agent agreement, so finish with the capture boundary:
- For ordinary Note-style files written with
is_write, commit staged knowledge withis_commitafter confirmation. - For native
_agent/edits, commit the explicit changed paths withis_commitafter confirmation. - If the user only wanted a draft, say that it remains local/uncommitted.