Create protocol-compliant JSON session logs with verification-based enforcement. Autonomous operation with auto-incremented session numbers and objective derivation from git state. Use when starting any new session.
Creates validated JSON session logs from git state and canonical templates with immediate protocol verification.
/plugin marketplace add rjmurillo/ai-agents/plugin install project-toolkit@ai-agentsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Create protocol-compliant session logs with verification-based enforcement.
python3 .claude/skills/session-init/scripts/new_session_log.py
The script will:
/session-init
Follow the manual workflow below if the automated script doesn't meet your needs.
| Phrase | Action |
|---|---|
/session-init | Create new session log |
create session log | Natural language activation |
start new session | Alternative trigger |
initialize session | Alternative trigger |
| Input | Output | Quality Gate |
|---|---|---|
| Session number, objective | Validated session log file | Exit code 0 from validation |
Use this skill when:
Use session-log-fixer instead when:
Use session-migration instead when:
Problem: Every PR starts with malformed session logs that fail CI validation.
Root Cause: Agents generate session logs from LLM memory instead of copying the canonical template from SESSION-PROTOCOL.md. This causes variations like:
(COMPLETE ALL before closing) text in Session End header## vs ###)Solution: Verification-based enforcement following the proven Serena initialization pattern.
Format: YYYY-MM-DD-session-NN.json
The script automatically generates human-readable filenames by extracting up to 5 keywords from the session objective using NLP heuristics:
| Session Objective | Generated Filename |
|---|---|
| "Debug recurring session validation failures" | 2026-01-06-session-374-debug-recurring-session-validation-failures.md |
| "Implement OAuth 2.0 authentication flow" | 2026-01-06-session-375-implement-oauth-authentication-flow.md |
| "Fix test coverage gaps in UserService" | 2026-01-06-session-376-fix-test-coverage-gaps-userservice.md |
| "Refactor PaymentProcessor for better error handling" | 2026-01-06-session-377-refactor-paymentprocessor-better-error-handling.md |
ls .agents/sessions/ and instantly understand contentgrep -l "oauth" .agents/sessions/*.jsonUser Request: /session-init
|
v
+---------------------------------------------+
| Phase 1: GATHER INPUTS |
| - Prompt for session number |
| - Prompt for objective |
| - Auto-detect: date (YYYY-MM-DD) |
| - Auto-detect: branch (git branch) |
| - Auto-detect: commit (git log) |
| - Auto-detect: git status |
+---------------------------------------------+
|
v
+---------------------------------------------+
| Phase 2: READ CANONICAL TEMPLATE |
| - Read .agents/SESSION-PROTOCOL.md |
| - Extract template (lines 494-612) |
| - Preserve EXACT formatting |
| - Critical: Keep "(COMPLETE ALL before |
| closing)" text in Session End header |
+---------------------------------------------+
|
v
+---------------------------------------------+
| Phase 3: POPULATE TEMPLATE |
| - Replace NN with session number |
| - Replace YYYY-MM-DD with date |
| - Replace [branch name] with actual branch |
| - Replace [SHA] with commit hash |
| - Replace [objective] with user input |
| - Replace [clean/dirty] with git status |
+---------------------------------------------+
|
v
+---------------------------------------------+
| Phase 4: WRITE SESSION LOG |
| - Generate descriptive filename with |
| keywords from objective |
| - Write to .agents/sessions/YYYY-MM-DD- |
| session-NN-keyword1-keyword2-...md |
| - Preserve all template sections |
+---------------------------------------------+
|
v
+---------------------------------------------+
| Phase 5: IMMEDIATE VALIDATION |
| - Run validate_session_json.py |
| - Report validation result |
| - If FAIL: show errors, allow retry |
| - If PASS: confirm success |
+---------------------------------------------+
|
v
Protocol-Compliant Session Log
Prompt user for required inputs:
What is the session number? (e.g., 375)
What is the session objective? (e.g., "Implement session-init skill")
Auto-detect from environment:
# Current date
date +%Y-%m-%d
# or PowerShell: Get-Date -Format "yyyy-MM-dd"
# Current branch
git branch --show-current
# Starting commit
git log --oneline -1
# Git status
git status --short
CRITICAL: Use the new_session_log.py script to read the template from SESSION-PROTOCOL.md.
python3 .claude/skills/session-init/scripts/new_session_log.py
DO NOT generate the template from memory or read specific line numbers. The script extracts the canonical template dynamically:
## vs ###)[ ]<!-- -->### Session End (COMPLETE ALL before closing) header textReplace placeholders with actual values:
| Placeholder | Replace With |
|---|---|
NN | Session number (e.g., 375) |
YYYY-MM-DD | Current date |
[branch name] | Git branch name |
[SHA] | Starting commit hash |
[What this session aims to accomplish] | User-provided objective |
[clean/dirty] | Git status result |
Leave these unchanged:
[ ] (unchecked)Write the populated session log to a file with descriptive naming:
Filename Format: YYYY-MM-DD-session-NN.json
The script automatically:
Example:
For objective "Debug recurring session validation failures", the filename becomes:
2026-01-06-session-374-debug-recurring-session-validation-failures.md
Construct filename: .agents/sessions/YYYY-MM-DD-session-NN.json
Example: .agents/sessions/.agents/sessions/2026-01-05-session-375.json
Write the populated template to this file.
Run validation script:
python3 scripts/validate_session_json.py ".agents/sessions/YYYY-MM-DD-session-NN.json"
Check exit code:
| Exit Code | Meaning | Action |
|---|---|---|
| 0 | PASS | Confirm success, agent proceeds |
| 1 | FAIL | Show errors, offer to retry |
Before reporting success:
(COMPLETE ALL before closing).agents/sessions/YYYY-MM-DD-session-NN.json| Avoid | Why | Instead |
|---|---|---|
| Generating template from memory | Will miss exact formatting | Read from SESSION-PROTOCOL.md |
| Skipping validation | Won't catch errors until CI | Validate immediately |
| Hardcoding template in skill | Template may change | Always read from canonical source |
| Pre-checking boxes | Defeats verification purpose | Leave all unchecked |
Using ## Session End | Missing required text | Use ### Session End (COMPLETE ALL before closing) |
Success:
Session log created and validated
File: .agents/sessions/.agents/sessions/2026-01-05-session-375.json
Validation: PASS
Branch: feat/session-init
Commit: abc1234
Next: Complete Session Start checklist in the session log
Failure:
Session log created but validation FAILED
File: .agents/sessions/.agents/sessions/2026-01-05-session-375.json
Validation: FAIL
Errors:
- Missing Session End checklist header
Run: python3 scripts/validate_session_json.py ".agents/sessions/.agents/sessions/2026-01-05-session-375.json"
Fix the issues and re-validate.
| Skill | Relationship |
|---|---|
| log-fixer | Reactive fix after failure (this skill prevents need) |
| qa-eligibility | QA eligibility checking (different purpose) |
| Script | Purpose | Exit Codes |
|---|---|---|
| new_session_log.py | Automated session log creation with validation | 0=success, 1=error |
| new_session_log_json.py | Simplified JSON session log creation | 0=success, 1=error |
Automated (Recommended):
# Create session log with parameters
python3 .claude/skills/session-init/scripts/new_session_log.py --session-number 375 --objective "Implement feature X"
# Skip validation
python3 .claude/skills/session-init/scripts/new_session_log.py --session-number 375 --objective "Implement feature X" --skip-validation
# Simplified JSON-only version
python3 .claude/skills/session-init/scripts/new_session_log_json.py --session-number 375 --objective "Implement feature X"
This skill follows the same pattern as Serena initialization:
| Aspect | Serena Init | Session Init |
|---|---|---|
| Verification | Tool output in transcript | Validation script exit code |
| Feedback | Immediate (tool response) | Immediate (validation output) |
| Enforcement | Cannot proceed without output | Cannot claim success without pass |
| Compliance Rate | 100% (never violated) | Target: 100% |
Why it works:
Activates when the user asks about AI prompts, needs prompt templates, wants to search for prompts, or mentions prompts.chat. Use for discovering, retrieving, and improving prompts.
Search, retrieve, and install Agent Skills from the prompts.chat registry using MCP tools. Use when the user asks to find skills, browse skill catalogs, install a skill for Claude, or extend Claude's capabilities with reusable AI agent components.
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.