session-create

Original：🇺🇸 English
Translated

Open a new context session at the start of a leader agent workflow. Records agentName, storyId, and phase in wint.contextSessions, emitting a structured SESSION CREATED block for downstream workers to inherit.

2installs
Sourcemichael-menard/monorepo
Added on

NPX Install

npx skill4agent add michael-menard/monorepo session-create

Tags

Translated version includes tags in frontmatter
agent-workflowsession-managementmulti-agent-systemtelemetry-trackingskill-documentation

SKILL.md Content

View Translation Comparison →

/session-create - Open a Context Session

Description

Opens a new context session at the beginning of a leader agent's workflow. The session record tracks token usage, agent identity, and story context across multi-agent workflows. Workers inherit this session via the companion 
session-inherit
skill.
Session tracking is telemetry — it must never gate or block a workflow. If the session cannot be created (DB unavailable, null return), the leader emits a warning and continues normally.

Usage

/session-create                                      # called at start of leader workflow
/session-create storyId=WINT-1234 phase=execute      # with story and phase context

Parameters

ParameterRequiredDefaultDescription
agentName
Yes(current agent name)The name of the leader agent opening the session
storyId
NonullStory ID for this workflow (e.g. 
WINT-1234
)
phase
NonullCurrent workflow phase (e.g. 
execute
, 
plan
, 
qa
)
sessionId
No(auto-generated UUID)Override the session UUID (rarely needed)

What It Does

This skill:
  1. Calls 
    mcp__postgres-knowledgebase__sessionCreate
    with 
    agentName
    , 
    storyId
    , and 
    phase
  2. Records the returned 
    session_id
    and emits the structured 
    SESSION CREATED
    output block
  3. Handles null returns (DB error) gracefully — emits 
    SESSION UNAVAILABLE
    and continues

Execution Steps

Step 1: Invoke sessionCreate

Call the MCP tool with required and optional fields:
javascript
const result = await mcp__postgres_knowledgebase__sessionCreate({
  agentName: 'dev-execute-leader',   // required — name of THIS agent
  storyId: 'WINT-2090',              // optional
  phase: 'execute',                  // optional
  // sessionId: crypto.randomUUID()  // omit to auto-generate
})
SessionCreateInput fields:
FieldTypeRequiredNotes
agentName
string (min 1)YesName of the leader agent
sessionId
UUID stringNoAuto-generated if omitted
storyId
string | nullNoStory identifier
phase
string | nullNoWorkflow phase label
inputTokens
int >= 0NoDefault: 0
outputTokens
int >= 0NoDefault: 0
cachedTokens
int >= 0NoDefault: 0
startedAt
DateNoDefaults to now()

Step 2: Handle the result

Success path — 
result
is not null:
javascript
if (result && result.sessionId) {
  // Emit the structured output block (see Output section below)
}
Null-return path — DB error or connection failure:
javascript
if (result === null) {
  // Emit SESSION UNAVAILABLE warning and continue
}

Step 3: Emit structured output

On success, always emit the following block so workers can parse the session ID:
SESSION CREATED
  session_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
  agent:      dev-execute-leader
  story_id:   WINT-2090
  phase:      execute
The 
session_id
line must match the regex: 
/SESSION CREATED\n\s+session_id:\s+([0-9a-f-]{36})/

Output

Success

After a successful 
sessionCreate
call, emit:
SESSION CREATED
  session_id: {uuid returned by sessionCreate}
  agent:      {agentName}
  story_id:   {storyId or "—"}
  phase:      {phase or "—"}

Null Return (Graceful Degradation)

If 
sessionCreate
returns 
null
(DB unavailable or insertion error):
SESSION UNAVAILABLE — continuing without session tracking
Then continue the workflow normally. Do not block, retry, or raise an error. Session tracking is telemetry, not a gate.

Session Lifecycle

The full session lifecycle across a multi-agent workflow:
  1. Leader opens — calls 
    session-create
    → 
    sessionCreate
    → emits 
    SESSION CREATED
  2. Workers inherit — each worker calls 
    session-inherit
    → 
    sessionQuery(activeOnly: true)
    → emits 
    SESSION INHERITED
  3. Workers update tokens — call 
    sessionUpdate({ sessionId, mode: 'incremental', inputTokens, outputTokens })
  4. Leader closes — the leader (and ONLY the leader that opened the session) calls 
    sessionComplete
  5. Periodic cleanup — 
    sessionCleanup({ retentionDays: 90 })
    archives old sessions (future: WINT-2100)
Workers MUST NOT call 
sessionComplete
. See the 
session-inherit
skill for the full restriction.

Graceful Degradation

Session tracking is purely telemetry. The following conditions must NOT block the workflow:
ConditionBehavior
DB connection unavailableEmit 
SESSION UNAVAILABLE — continuing without session tracking
and proceed
sessionCreate
returns null		Same as above
MCP tool unavailableLog warning, proceed without session
Network timeoutLog warning, proceed without session
The leader's downstream work (plan execution, file writes, code generation) must continue regardless of session state.

Examples

Minimal invocation

javascript
const session = await mcp__postgres_knowledgebase__sessionCreate({
  agentName: 'dev-execute-leader',
})
// Emits:
// SESSION CREATED
//   session_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
//   agent:      dev-execute-leader
//   story_id:   —
//   phase:      —

Full invocation with context

javascript
const session = await mcp__postgres_knowledgebase__sessionCreate({
  agentName: 'dev-execute-leader',
  storyId: 'WINT-2090',
  phase: 'execute',
})
// Emits:
// SESSION CREATED
//   session_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
//   agent:      dev-execute-leader
//   story_id:   WINT-2090
//   phase:      execute

Null-return path

javascript
const session = await mcp__postgres_knowledgebase__sessionCreate({
  agentName: 'dev-execute-leader',
  storyId: 'WINT-2090',
  phase: 'execute',
})

if (!session) {
  // Emit:
  // SESSION UNAVAILABLE — continuing without session tracking
  // then continue with the rest of the workflow normally
}

Integration Notes

  • The 
    session_id
    from 
    SESSION CREATED
    should be passed to spawned workers via their prompt context so they can call 
    session-inherit
  • Workers use 
    sessionQuery({ activeOnly: true, limit: 50 })
    and filter client-side — they do NOT receive a 
    sessionId
    filter directly
  • The leader is solely responsible for calling 
    sessionComplete
    at the end of its workflow