From sdd
Analyze session transcript logs to identify genuine reusable skill candidates across multiple tickets and sessions
npx claudepluginhub manifoldlogic/claude-code-plugins --plugin sddThis skill uses the workspace's default tool permissions.
Session transcripts contain a wealth of procedural patterns that agents follow repeatedly across tickets and projects. Phase 1 hooks (registered via `log-session-transcript.py`) capture transcript references to `${SDD_ROOT_DIR}/logs/session-transcripts/` whenever sessions compact or end. These logs form a raw dataset of agent behavior, but the vast majority of patterns within them are noise -- ...
Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
Session transcripts contain a wealth of procedural patterns that agents follow repeatedly across tickets and projects. Phase 1 hooks (registered via log-session-transcript.py) capture transcript references to ${SDD_ROOT_DIR}/logs/session-transcripts/ whenever sessions compact or end. These logs form a raw dataset of agent behavior, but the vast majority of patterns within them are noise -- trivial commands, general knowledge application, and standard tool usage that would not benefit from formal documentation as a skill.
This skill guides agents through a structured methodology for mining those session transcript logs to identify genuine reusable skill candidates. The emphasis is on quality over quantity: a successful analysis session might yield zero new skill candidates, and that is a valid outcome. The goal is to surface only those patterns that meet strict quality gates -- patterns that are multi-step, cross-project, non-trivial, and not already covered by existing skills or standard documentation.
This is a Reference Skill (methodology/procedure). Agents read this skill and follow the procedure using their own tool access (Read, Grep, Glob) to analyze transcripts. There is no automation or executable script associated with this skill.
Apply this methodology when:
/sdd:curate-skills output: If single-ticket curation identifies a pattern that appears to have broader applicability, use this skill to validate it against cross-session evidence/sdd:curate-skills workflow instead. That workflow handles within-ticket skill extraction and does not require cross-session analysis.skill-creation-workflow.md.Locate and inventory session transcript log files.
Log directory: ${SDD_ROOT_DIR}/logs/session-transcripts/
File naming convention: {session_id}_{event}_{timestamp}.json
Where:
session_id is the Claude Code session identifier (e.g., abc123)event is the hook event that triggered the log (e.g., PreCompact, Stop)timestamp is an ISO 8601 timestamp with microseconds (e.g., 2026-02-13T15:30:00.123456)Procedure:
Use Glob to list *.json files in the log directory:
${SDD_ROOT_DIR}/logs/session-transcripts/*.json
Sort by timestamp (embedded in filename) to prioritize recent sessions.
Filter by date range if analyzing a specific time period.
Count total files to gauge analysis scope.
Session transcript logs accumulate over time. Recommended retention policies:
Active Retention (90 days): Logs from the past 90 days are useful for skill discovery - recent patterns are more likely to become reusable skills. This window balances disk usage with analysis value.
Historical Retention (1 year): Older logs may have long-term analytical value but are unlikely to reveal new skills. Archive them for future reference without cluttering active storage.
Deletion (after 90 days):
To permanently delete logs older than 90 days:
find ${SDD_ROOT_DIR}/logs/session-transcripts/ -type f -name "*.json" -mtime +90 -delete
Warning: This is irreversible. Verify with dry-run first:
find ${SDD_ROOT_DIR}/logs/session-transcripts/ -type f -name "*.json" -mtime +90 -print
Archival (after 90 days):
To compress and archive logs older than 90 days:
# Create archive directory
mkdir -p ${SDD_ROOT_DIR}/logs/archives
# Find and archive old logs
archive_date=$(date +%Y%m%d)
find ${SDD_ROOT_DIR}/logs/session-transcripts/ -type f -name "*.json" -mtime +90 -print0 | \
tar -czf ${SDD_ROOT_DIR}/logs/archives/session-transcripts-${archive_date}.tar.gz --null -T -
# After verifying archive, delete originals
find ${SDD_ROOT_DIR}/logs/session-transcripts/ -type f -name "*.json" -mtime +90 -delete
Archived logs can be extracted later for historical analysis:
tar -xzf ${SDD_ROOT_DIR}/logs/archives/session-transcripts-YYYYMMDD.tar.gz -C /tmp/
Custom Retention:
Adjust retention based on your needs:
For each log file, extract the transcript reference and assess availability.
Log entry format (JSON):
{
"session_id": "abc123",
"schema_version": "1.0",
"transcript_path": "/home/user/.claude/projects/.../session.jsonl",
"cwd": "/workspace/repos/project",
"hook_event_name": "PreCompact",
"timestamp": "2026-02-13T15:30:00.123456",
"trigger": "auto",
"custom_instructions": "",
"status": "ok"
}
Procedure:
transcript_path fieldJSONL transcript format:
Each line of a .jsonl transcript file is a self-contained JSON object representing one message or tool invocation in the session:
{"role": "user", "content": "Please implement feature X", "timestamp": "..."}
{"role": "assistant", "content": "I'll help with that...", "timestamp": "..."}
{"role": "tool_use", "tool": "Read", "parameters": {"file_path": "/path/to/file"}, "timestamp": "..."}
{"role": "tool_result", "content": "...", "timestamp": "..."}
Key fields:
role: One of user, assistant, tool_use, tool_resultcontent: The message text or tool outputtool: (tool_use only) The tool name invokedparameters: (tool_use only) The parameters passed to the tooltimestamp: When the message occurredThe exact schema may vary between Claude Code versions. Parse defensively and skip lines that do not match expected structure.
Focus areas during triage:
cwd field in log entries)Identify patterns with potential reuse value from the triaged transcripts.
What to look for:
cwd directories or different plugin contexts, indicating the pattern is not project-specificWhat to ignore:
Evaluate each candidate pattern against the quality gates table. A candidate must pass ALL gates to proceed.
| Gate | Criteria | Pass Condition |
|---|---|---|
| Reuse Potential | Pattern observed across sessions or projects | 3+ sessions AND cross-project applicability (session-derived skills must meet BOTH criteria) |
| Complexity | Pattern is non-trivial | Pattern involves multiple steps or non-obvious integration (single commands or general knowledge are insufficient) |
| Distinctiveness | Not already covered by existing skills | Check .claude/skills/ and plugins/*/skills/ for overlap |
| Documentability | Can be expressed as a SKILL.md | Fits either executable or reference pattern from skill-md-structure |
| Teachability | Agent would benefit from having this documented | Not common knowledge; requires domain insight or repo-specific context |
| Non-Triviality | Pattern is not general developer knowledge | Not covered by standard tool docs (man pages, MDN, official guides) or common StackOverflow patterns |
Gate evaluation order: Apply Reuse Potential and Non-Triviality first, as these are the most common rejection reasons. If a candidate fails either of these, skip remaining gates.
The following examples illustrate patterns that should be rejected during quality gate evaluation. These represent the triviality boundary -- patterns that are either single commands, general knowledge, or standard tool usage.
Running git status: Trivial single command. Standard workflow documented in git --help. No multi-step procedure or domain insight.
Using ls -la to list files: Basic shell command. Documented in man pages. Every developer knows this without a skill document.
Reading MDN documentation for Array.prototype.map: General JavaScript knowledge. Covered comprehensively by official documentation. Not repo-specific or procedural.
Installing npm packages with npm install: Standard tool usage. The npm install command and its flags are fully documented in npm's official documentation.
Searching StackOverflow for common error messages: General debugging practice. Not a reusable pattern -- each error message and solution is unique.
Using grep -r "pattern" . for code search: Standard tool usage with no multi-step procedure. Grep usage is documented in man pages and tutorials.
Committing changes with git commit -m "message": Basic git workflow. No non-obvious integration or domain-specific procedure.
Contrast with valid candidates: A valid candidate might be "verifying identical content blocks across multiple markdown files using grep, extraction, hash comparison, and diff" -- this is multi-step, requires a specific procedure, and is not covered by any single tool's documentation.
Cross-reference candidates that pass all quality gates against the existing skill-curation infrastructure.
Procedure:
skill-quality-criteria.md from the skill-curation infrastructure to confirm the candidate meets the project's established quality bar.claude/skills/ for existing repo-local skills that might already cover the pattern (compare by purpose, not just name)plugins/*/skills/ for existing plugin-scoped skills with overlapping coverage.claude/skills/skill-md-structure/SKILL.md (determine whether it would be an executable or reference skill)For candidates that survive all gates and validation, prepare skill proposals.
Procedure:
skill-creation-workflow.md from the skill-curation infrastructure for the formal creation process.claude/skills/{name}/SKILL.md (same location as ticket-curated skills)plugins/{plugin}/skills/{name}/SKILL.mdObserved in: SKILLLOG, TOOLS, RECIPES tickets (across 5+ sessions)
Pattern: Verifying identical content blocks across multiple markdown files. The procedure involves grepping for block markers, extracting content sections, comparing hashes or using diff, and reporting inconsistencies with specific line numbers.
Procedure observed in transcripts:
grep -n to locate content block markers across all target filesdiffWhy it passes quality gates:
Deliverable: .claude/skills/multi-file-documentation-sync/SKILL.md
Observed in: iterm plugin, sdd plugin, github-actions plugin development (across 4+ sessions)
Pattern: Rejecting dangerous input patterns in shell scripts that accept user-provided strings. The procedure involves regex-based validation for newlines, backticks, command substitution ($(...)), and variable expansion (${...}), with consistent error messaging and exit codes.
Procedure observed in transcripts:
Why it passes quality gates:
Deliverable: .claude/skills/shell-script-input-validation/SKILL.md
Scenario: A session log entry at ${SDD_ROOT_DIR}/logs/session-transcripts/abc123_PreCompact_2026-02-10T14:22:00.000000.json contains a transcript_path pointing to /tmp/session-abc123.jsonl.
Problem: The transcript file no longer exists. Claude Code periodically cleans up session files, and /tmp is volatile across container restarts.
Procedure for graceful handling:
transcript_pathsession_id, cwd, timestamp, hook_event_nameWhy this matters: Graceful degradation prevents analysis failures when transcript files have been cleaned up. The metadata alone (which project, when, what hook event) can still contribute to cross-referencing patterns identified in other sessions.
Observed in: worktree plugin, vscode plugin development (across 6+ sessions)
Pattern: Implementing plugin commands that delegate to an external CLI tool with graceful fallback when the tool is unavailable. The procedure involves checking tool availability with command -v, constructing the delegation command with proper argument forwarding, capturing exit codes, and providing meaningful error messages when the tool is missing.
Procedure observed in transcripts:
command -vWhy it passes quality gates:
Deliverable: .claude/skills/wrapper-with-fallback-pattern/SKILL.md
Observed in: ISKIM, SKILLLOG, PANE tickets (across 8+ sessions)
Pattern: Choosing between executable and reference skill patterns when creating SKILL.md documentation. The procedure involves evaluating whether the skill includes scripts, determining the appropriate section count (5 vs 12+), and validating frontmatter fields against the pattern requirements.
Why it was NOT proposed as a standalone skill: This pattern was already captured as .claude/skills/skill-md-structure/SKILL.md during the ISKIM ticket. This example demonstrates that Step 5 (Validate Against Existing Criteria) correctly filters out duplicates, even when the pattern is observed frequently in transcripts.
If log files are not being created in ${SDD_ROOT_DIR}/logs/session-transcripts/, follow these verification steps:
Check that the environment variable is configured:
echo "SDD_ROOT_DIR=${SDD_ROOT_DIR}"
Expected output: /path/to/sdd/root (not empty)
If empty, the setup-sdd-env.js SessionStart hook may not have run. Check that the SDD plugin is installed.
Check directory permissions:
ls -ld ${SDD_ROOT_DIR}/logs/session-transcripts/
Expected: Directory exists and is writable by current user.
If directory is missing, create it manually:
mkdir -p ${SDD_ROOT_DIR}/logs/session-transcripts
chmod 700 ${SDD_ROOT_DIR}/logs/session-transcripts
Check that the hook is registered in plugin.json:
jq '.hooks.PreCompact, .hooks.SessionEnd' plugins/sdd/.claude-plugin/plugin.json
Expected: Both hooks list log-session-transcript.py with timeout 10.
If missing, hook registration (SKILLLOG.1003) was not completed successfully.
Execute the hook with test input to check for Python errors:
export SDD_ROOT_DIR=/path/to/your/sdd/root
echo '{"session_id": "test123", "transcript_path": "/tmp/test.jsonl", "cwd": "/workspace", "hook_event_name": "SessionEnd", "reason": "test"}' | python3 plugins/sdd/hooks/log-session-transcript.py
echo "Exit code: $?"
Expected: Exit code 0, no output. Check for new file in ${SDD_ROOT_DIR}/logs/session-transcripts/.
If Python errors appear, the hook script has a bug.
transcript_path is sometimes empty. Log entry is created with status: "empty_path".python3 --versionumaskdf -h ${SDD_ROOT_DIR}If none of these steps reveal the issue, check Claude Code's internal logs for hook execution errors.
Skill curation infrastructure:
skill-quality-criteria.md -- Established quality criteria for skill candidates (located in skill-curation infrastructure, may be in other worktrees)skill-creation-workflow.md -- Step-by-step workflow for creating new skills from validated candidates (located in skill-curation infrastructure, may be in other worktrees)Skill structure documentation:
.claude/skills/skill-md-structure/SKILL.md -- Reference Skill pattern documentation defining the 5-section and 12-section structuresSession transcript log directory:
${SDD_ROOT_DIR}/logs/session-transcripts/ -- Location where Phase 1 hooks write session transcript log entries{session_id}_{event}_{timestamp}.jsonsession_id, schema_version, transcript_path, cwd, hook_event_name, timestamp, trigger, statusTranscript format:
role, content, timestamp (plus tool and parameters for tool_use entries)Existing repo-local skills (examples of discovered patterns):
.claude/skills/multi-file-documentation-sync/SKILL.md -- Pattern for verifying content consistency across files.claude/skills/shell-script-input-validation/SKILL.md -- Pattern for rejecting dangerous input in shell scripts.claude/skills/skill-md-structure/SKILL.md -- Two SKILL.md documentation patterns.claude/skills/wrapper-with-fallback-pattern/SKILL.md -- Plugin delegation with graceful fallbackOrigin ticket: SKILLLOG (Session Skill Discovery epic)