Agent Skill¶
The Point CLI owns storage, lineage, Git relations, and transport. The Point Skill makes that protocol disappear into normal Agent collaboration.
Install¶
Install globally with -g when needed across projects.
What the Skill does¶
The Skill:
- recognizes “save,” “continue,” “start another direction,” “commit,” and “publish” intent;
- exports newly produced participant-visible Session events as JSONL;
- preserves every allowed, participant-visible Session event in its original order;
- lets the CLI derive Session identity, active parents, Point Branch, and Git state;
- treats Resume output as restored context;
- starts a new event boundary after Resume or a successful save;
- prepares real Session events before an Agent-triggered Git Commit;
- never copies restored parent payload into a child Point.
Why an Agent integration is required¶
The CLI can inspect Git but cannot reach into every Agent runtime. Only the Agent integration knows which Session events are participant-visible, allowed to be saved, and new since the last Point boundary.
The boundary is deliberate:
Agent adapter / Skill Point CLI
──────────────────── ─────────
read visible Session events → validate JSONL
track the event boundary → create Git objects
inject Resume output ← traverse Point DAG
prepare commit context → link it to Git Commit
Point does not require different Agents to share internal memory or a private runtime. They only need the common JSONL and Git protocol.
Session JSONL¶
Each non-empty line is a JSON event with a type:
{"id":"e1","type":"message","role":"user","content":"Keep retries bounded."}
{"id":"e2","type":"message","role":"assistant","content":"I will inspect the failure path."}
{"id":"e3","type":"tool_call","call_id":"t1","name":"test","arguments":{"target":"retry"}}
{"id":"e4","type":"tool_result","call_id":"t1","name":"test","content":"passed"}
Adapters may preserve additional fields. Point requires only a non-empty type so the source can evolve without a central Agent schema.
Event boundaries¶
A new Point stores events produced after the latest of:
- the Agent Session start;
point resume;- a successful Stash Point or Commit Point.
Resume may inject several historical Sessions into the Agent. The adapter must not export those bytes again. Parent IDs already preserve them. This gives Point a logically complete Session history without physical transcript duplication.
Commit handshake¶
Before git commit, the Skill passes the new Session segment to the internal preparation command. The Hook creates a Commit Point only when that capture matches both the Git base and staged tree. On a failed commit, the Skill cancels the pending capture.
This handshake prevents two bad outcomes:
- attaching stale context to a later, unrelated commit;
- creating placeholder context when the Agent Session is unavailable.
User experience¶
Users should not need Session tokens, temporary Agent names, event cursors, or parent flags. They can say:
Save this Session as a Point.
Resume the project context.
Continue from these two Points on master.
Commit this change with its Session.
Publish the Git Branch and context to the team.
The Skill returns meaningful outcomes: Point ID, branch advanced, Git Commit link, and whether the Point is still local or has been published.