К основному содержанию
скилл CX Codex

session-chronicle — скилл Claude Code: аудит сессий

Скилл session-chronicle для Claude Code связывает находки, решения и изменения в коде с сессиями и их UUID. Ищет происхождение решений и готовит записи о сессиях.

MIT 135 установок ★ 3 обновлён 2026-10-25

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add terrylica/cc-skills --skill session-chronicle -a claude-code
Открыть на GitHub

Что делает session-chronicle

session-chronicle ищет происхождение исследовательских находок, архитектурных решений и фрагментов кода в логах сессий. Он связывает UUID основной сессии и субагентов, чтобы запись в реестре сохраняла контекст для будущей работы. Скилл использует Read, Grep, Glob, Bash и AskUserQuestion.

Перед работой он проверяет хранилище сессий в ~/.claude/projects/, файлы проекта и инструменты jq, brotli, aws, op. Для публикации артефактов в S3 предусмотрена санитизация: сырые JSONL-логи могут содержать токены, ключи, адреса и другие секреты, поэтому их нельзя загружать напрямую. Это скилл с несколькими сценариями выбора цели, атрибуции и состава сессий.

Какие задачи решает

  • найти, кто создал фрагмент кода
  • связать решение в ADR с логами сессий
  • сохранить UUID основной сессии и субагентов
  • зафиксировать происхождение исследовательской находки
  • подготовить логи к публикации в S3

Примеры запросов агенту

  • Найди, кто создал эту функцию, и свяжи результат с логами сессий.
  • Зафиксируй это исследование в реестре вместе со всеми UUID основной сессии и субагентов.
  • Подготовь архив сессий для S3, сначала удали секреты и создай отчёт о санитизации.

Как установить session-chronicle

1Через Skills CLI (Vercel)

npx skills add terrylica/cc-skills --skill session-chronicle -a claude-code

2Вручную: положить файлы

~/.claude/skills/session-chronicle/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/session-chronicle/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о session-chronicle

Как установить session-chronicle в Claude Code?

Выполните npx skills add terrylica/cc-skills --skill session-chronicle -a claude-code, затем проверьте файл ~/.claude/skills/session-chronicle/SKILL.md.

Что делает session-chronicle?

Скилл исследует логи Claude Code-сессий и связывает их UUID с находками, решениями и изменениями в коде. Он помогает сохранять происхождение работы в реестре.

Что нужно проверить перед публикацией сессий в S3?

Сначала нужно прогнать логи через санитизатор и просмотреть отчёт о редактировании. Сырые JSONL-файлы могут содержать ключи, токены, адреса и другие секреты, поэтому их нельзя загружать напрямую.

Исходный текст

SKILL.md · MIT
---
name: session-chronicle
description: Session log provenance tracking. TRIGGERS - who created, trace origin, session archaeology, ADR reference.
allowed-tools: Read, Grep, Glob, Bash, AskUserQuestion
---

# Session Chronicle

Excavate Claude Code session logs to capture **complete provenance** for research findings, ADR decisions, and code contributions. Traces UUID chains across multiple auto-compacted sessions.

**CRITICAL PRINCIPLE**: Registry entries must be **self-contained**. Record ALL session UUIDs (main + subagent) at commit time. Future maintainers should not need to run archaeology to understand provenance.

**S3 Artifact Sharing**: Artifacts can be uploaded to S3 for team access. See [S3 Sharing ADR](/docs/adr/2026-01-02-session-chronicle-s3-sharing.md).

> **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

## When to Use This Skill

- User asks "who created this?" or "where did this come from?"
- User says "document this finding" with full session context
- ADR or research finding needs provenance tracking
- Git commit needs session UUID references
- Tracing edits across auto-compacted sessions
- **Creating a registry entry for a research session**

---

## File Ownership Model

| Directory                                 | Committed? | Purpose                                  |
| ----------------------------------------- | ---------- | ---------------------------------------- |
| `findings/registry.jsonl`                 | YES        | Master index (small, append-only NDJSON) |
| `findings/sessions/<id>/iterations.jsonl` | YES        | Iteration records (small, append-only)   |
| `outputs/research_sessions/<id>/`         | NO         | Research artifacts (large, gitignored)   |
| `tmp/`                                    | NO         | Temporary archives before S3 upload      |
| S3 `example-findings-bucket/sessions/<id>/`      | N/A        | Permanent team-shared archive            |

**Key Principle**: Only `findings/` is committed. Research artifacts go to gitignored `outputs/` and S3.

---

## Part 0: Preflight Check

Verify session storage, find project sessions, and check required tools (jq, brotli, aws, op).

**Full scripts**: [Preflight Scripts](./references/preflight-scripts.md)

Summary of steps:

1. **Verify Session Storage** - Confirm `~/.claude/projects/` exists
2. **Find Current Project Sessions** - Encode CWD path, enumerate main + subagent `.jsonl` files
3. **Verify Required Tools** - Check `jq`, `brotli`, `aws`, `op` are installed

### Step 4 (MANDATORY before any S3 share): Sanitize

**Raw Claude Code session JSONL files are dangerous to share.** They commonly contain real credentials (AWS keys, GitHub PATs, Telegram bot tokens, Tailscale API keys, 1Password service tokens), internal hostnames, Tailscale CGNAT IPs, emails, and other infrastructure secrets that leak into prompts via screenshots, env dumps, and shell commands.

**Before** zipping + uploading to S3, run the sanitizer:

```bash
SKILL_DIR="$(find $HOME/.claude/plugins/marketplaces/cc-skills -type d -name session-chronicle | head -1)"
"$SKILL_DIR/scripts/sanitize_sessions.py" \
  --input  /path/to/raw/claude-sessions-export-raw \
  --output /path/to/sanitized/claude-sessions-export \
  --report /path/to/redaction_report.txt
```

The sanitizer is **field-aware** (does not destroy UUIDs, tool-use IDs, or forex decimals — v1 had a 92% phone-regex false-positive rate that murdered structural identifiers) and covers:

- AWS / GitHub / OpenAI / Anthropic / Slack / Stripe / Google / JWT / Bearer / Authorization
- Tailscale API keys (`tskey-*`), CGNAT IPs (100.64–127.x.x), tailnet DNS (`*.ts.net`), tailnet names
- 1Password service tokens (`ops_*`), `op://` URLs, 32-char item IDs after `op` CLI context
- Cloudflare API tokens + Global API Key + `CF_AppSession`
- Doppler (`dp.*`), Docker PAT (`dckr_pat_*`), npm (`npm_*`), Supabase (`sbp_*`), SendGrid (`SG.*`)
- Telegram bot tokens (`<bot_id>:<secret>` format) — catches tokens pasted into env dumps
- ClickHouse URLs with embedded credentials
- `.internal` hostnames, 172.25.x.x private range
- PEM private key blocks (OPENSSH / RSA / EC / DSA / PGP / ED25519)
- Generic `password=`, `api_key=`, `secret=` declarations in JSON/YAML/env format
- Email addresses
- Phone numbers — **only when separators present** (prevents UUID/decimal destruction)

**Output**: a redaction report listing per-pattern counts. Review before packaging to confirm nothing important was destroyed (sanity check: UUID integrity should be preserved).

**S3 upload sequence**: always raw → sanitize → zip → S3 → presigned URL. **Never upload `-raw/` directly.**

---

## Part 1: AskUserQuestion Flows

### Flow A: Identify Target for Provenance

When the skill is triggered, first identify what the user wants to trace:

```
AskUserQuestion:
  question: "What do you want to trace provenance for?"
  header: "Target"
  multiSelect: false
  options:
    - label: "Research finding/session"
      description: "Document a research session with full session context for reproducibility"
    - label: "Specific code/feature"
      description: "Trace who created a specific function, feature, or code block"
    - label: "Configuration/decision"
      description: "Trace when and why a configuration or architectural decision was made"
    - label: "Custom search"
      description: "Search session logs for specific keywords or patterns"
```

### Flow B: Confirm GitHub Attribution

**CRITICAL**: Every registry entry MUST have GitHub username attribution.

```
AskUserQuestion:
  question: "Who should be attributed as the creator?"
  header: "Attribution"
  multiSelect: false
  options:
    - label: "Use git config user (Recommended)"
      description: "Attribute to $(git config user.name) / $(git config user.email)"
    - label: "Specify GitHub username"
      description: "I'll provide the GitHub username manually"
    - label: "Team attribution"
      description: "Multiple contributors - list all GitHub usernames"
```

### Flow C: Confirm Session Scope

**CRITICAL**: Default to ALL sessions. Registry must be self-contained.

```
AskUserQuestion:
  question: "Which sessions should be recorded in the registry?"
  header: "Sessions"
  multiSelect: false
  options:
    - label: "ALL sessions (main + subagent) (Recommended)"
      description: "Record every session file - complete provenance for future maintainers"
    - label: "Main sessions only"
      description: "Exclude agent-* subagent sessions (loses context)"
    - label: "Manual selection"
      description: "I'll specify which sessions to include"
```

**IMPORTANT**: Always default to recording ALL sessions. Subagent sessions (`agent-*`) contain critical context from Explore, Plan, and specialized agents. Omitting them forces future maintainers to re-run archaeology.

### Flow D: Preview Session Contexts Array

Before writing, show the user the full `session_contexts` array, then confirm:

```
AskUserQuestion:
  question: "Review the session_contexts array that will be recorded:"
  header: "Review"
  multiSelect: false
  options:
    - label: "Looks correct - proceed"
      description: "Write this to the registry"
    - label: "Add descriptions"
      description: "Let me add descriptions to some sessions"
    - label: "Filter some sessions"
      description: "Remove sessions that aren't relevant"
    - label: "Cancel"
      description: "Don't write to registry yet"
```

### Flow E: Choose Output Format

```
AskUserQuestion:
  question: "What outputs should be generated?"
  header: "Outputs"
  multiSelect: true
  options:
    - label: "registry.jsonl entry (Recommended)"
      description: "Master index entry with ALL session UUIDs and GitHub attribution"
    - label: "iterations.jsonl entries"
      description: "Detailed iteration records in sessions/<id>/"
    - label: "Full session chain archive (.jsonl.br)"
      description: "Compress sessions with Brotli for archival"
    - label: "Markdown finding document"
      description: "findings/<name>.md with embedded provenance table"
    - label: "Git commit with provenance"
      description: "Structured commit message with session references"
    - label: "Upload to S3 for team sharing"
      description: "Upload artifacts to S3 with retrieval command in commit"
```

### Flow F: Link to Existing ADR

```
AskUserQuestion:
  question: "Link this to an existing ADR or design spec?"
  header: "ADR Link"
  multiSelect: false
  options:
    - label: "No ADR link"
      description: "This is standalone or ADR doesn't exist yet"
    - label: "Specify ADR slug"
      description: "Link to an existing ADR (e.g., 2025-12-15-feature-name)"
    - label: "Create new ADR"
      description: "This finding warrants a new ADR"
```

---

## Part 2: Session Archaeology Process

Scan ALL session files, build the `session_contexts` array, and optionally trace UUID chains.

**Full scripts**: [Archaeology Scripts](./references/archaeology-scripts.md)

Summary of steps:

1. **Full Project Scan** - Enumerate all main + subagent sessions with line counts and timestamps
2. **Build session_contexts Array** - Create the array with ALL sessions (session_uuid, type, entries, description)
3. **Trace UUID Chain** (optional) - Follow parent UUID references across sessions for detailed provenance

---

## Part 3: Registry Schema

Two NDJSON files track provenance:

- **`findings/registry.jsonl`** - Master index, one self-contained JSON object per line
- **`findings/sessions/<id>/iterations.jsonl`** - Iteration-level tracking per session

**Full schema, examples, and field reference**: [Registry Schema Reference](./references/registry-schema.md)

### Required Fields (registry.jsonl)

| Field                        | Format                                      |
| ---------------------------- | ------------------------------------------- |
| `id`                         | `YYYY-MM-DD-slug`                           |
| `type`                       | `research_session` / `finding` / `decision` |
| `created_at`                 | ISO8601 timestamp                           |
| `created_by.github_username` | **MANDATORY** GitHub username               |
| `session_contexts`           | **MANDATORY** Array of ALL session UUIDs    |

---

## Part 4: Output Generation

Brotli compression for session archival and structured git commit messages with provenance.

**Full scripts and templates**: [Output Generation](./references/output-generation.md)

Summary:

- **Compression** - Brotli-9 compress each session to `outputs/research_sessions/<id>/*.jsonl.br` (gitignored)
- **Manifest** - Auto-generated `manifest.json` with target_id, count, timestamp
- **Commit message** - Template includes registry_id, attribution, session counts, S3 retrieval commands

---

## Part 5: Confirmation Workflow

### Final Confirmation Before Write

**ALWAYS** show the user what will be written before appending:

```
AskUserQuestion:
  question: "Ready to write to registry. Confirm the entry:"
  header: "Confirm"
  multiSelect: false
  options:
    - label: "Write to registry"
      description: "Append this entry to findings/registry.jsonl"
    - label: "Edit first"
      description: "Let me modify some fields before writing"
    - label: "Cancel"
      description: "Don't write anything"
```

Before this question, display:

1. Full JSON entry (pretty-printed)
2. Count of session_contexts entries
3. GitHub username attribution
4. Target file path

### Post-Write Verification

After writing, verify:

```bash
# Validate NDJSON format
tail -1 findings/registry.jsonl | jq . > /dev/null && echo "Valid JSON"

# Show what was written
echo "Entry added:"
tail -1 findings/registry.jsonl | jq '.id, .created_by.github_username, (.session_contexts | length)'
```

---

## Part 6: Workflow Summary

```
1. PREFLIGHT
   ├── Verify session storage location
   ├── Find ALL sessions (main + subagent)
   └── Check required tools (jq, brotli)

2. ASK: TARGET TYPE
   └── AskUserQuestion: What to trace?

3. ASK: GITHUB ATTRIBUTION
   └── AskUserQuestion: Who created this?

4. ASK: SESSION SCOPE
   └── AskUserQuestion: Which sessions? (Default: ALL)

5. BUILD session_contexts ARRAY
   ├── Enumerate ALL main sessions
   ├── Enumerate ALL subagent sessions
   └── Collect metadata (entries, timestamps)

6. ASK: PREVIEW session_contexts
   └── AskUserQuestion: Review before writing

7. ASK: OUTPUT FORMAT
   └── AskUserQuestion: What to generate?

8. ASK: ADR LINK
   └── AskUserQuestion: Link to ADR?

9. GENERATE OUTPUTS
   ├── Build registry.jsonl entry (with iterations_path, iterations_count)
   ├── Build iterations.jsonl entries (if applicable)
   └── Prepare commit message

10. ASK: FINAL CONFIRMATION
    └── AskUserQuestion: Ready to write?

11. WRITE & VERIFY
    ├── Append to registry.jsonl
    ├── Append to sessions/<id>/iterations.jsonl
    └── Validate NDJSON format

12. SANITIZE (MANDATORY before any S3 share)
    ├── Run scripts/sanitize_sessions.py on the staging directory
    ├── Review redaction_report.txt (verify no structural destruction)
    └── Produce sanitized/ directory for downstream packaging

13. (OPTIONAL) S3 UPLOAD
    ├── Package sanitized/ directory (zip or brotli per-file)
    └── Upload compressed archives, generate presigned URL if sharing externally
```

---

## Success Criteria

1. **Complete session enumeration** - ALL main + subagent sessions recorded
2. **GitHub attribution** - `created_by.github_username` always present
3. **Self-contained registry** - Future maintainers don't need archaeology
4. **User confirmation** - Every step has AskUserQuestion confirmation
5. **Valid NDJSON** - All entries pass `jq` validation
6. **Reproducible** - Session UUIDs enable full context retrieval

---

## References

- [S3 Sharing ADR](/docs/adr/2026-01-02-session-chronicle-s3-sharing.md)
- [S3 Retrieval Guide](./references/s3-retrieval-guide.md)
- [Registry Schema Reference](./references/registry-schema.md)
- [Preflight Scripts](./references/preflight-scripts.md)
- [Archaeology Scripts](./references/archaeology-scripts.md)
- [Output Generation](./references/output-generation.md)
- [NDJSON Specification](https://github.com/ndjson/ndjson-spec)
- [jq Manual](https://jqlang.github.io/jq/manual/)
- [Brotli Compression](https://github.com/google/brotli)

---

## Troubleshooting

| Issue                     | Cause                       | Solution                                            |
| ------------------------- | --------------------------- | --------------------------------------------------- |
| Session storage not found | Claude Code not initialized | Start a Claude Code session first                   |
| No sessions in project    | Wrong path encoding         | Check encoded path matches ~/.claude/projects/      |
| jq parse error            | Malformed JSONL             | Validate each line with `jq -c .` individually      |
| brotli not found          | Missing dependency          | Install with `brew install brotli`                  |
| S3 upload fails           | Missing AWS credentials     | Configure AWS CLI or use 1Password injection        |
| UUID chain broken         | Session compacted           | Check related sessions for continuation             |
| GitHub username missing   | Attribution not set         | Always require github_username in registry entry    |
| Registry entry invalid    | Missing required fields     | Verify id, type, created_at, session_contexts exist |

## Post-Execution Reflection

After this skill completes, check before closing:

1. **Did the command succeed?** — If not, fix the instruction or error table that caused the failure.
2. **Did parameters or output change?** — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
3. **Was a workaround needed?** — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.

© terrylica · MIT · terrylica/cc-skills

Похожие скиллы

Все скиллы по теме «Настройка агента: память, контекст, субагенты» →
steel-session-debugging steel-dev Скилл steel-session-debugging находит причину сбоев в браузерных сессиях Steel по логам, трейсам и скриншотам. Помогает разобраться с таймаутами, блокировками страниц и ошибками автоматизации. CX Codex +1 487установок whatidid Microsoft Плагин whatidid собирает HTML-отчёт по локальным логам Copilot-сессий: что вы сделали, часы-эквиваленты и расход кредитов. ★ 54звёзд репо skill-idea-miner tradermonty Скилл skill-idea-miner для Claude Code ищет идеи новых скиллов в логах сессий. Еженедельный пайплайн оценивает кандидатов и добавляет их в бэклог. CX Codex +1 3 500установок read-memories duckdb Скилл read-memories ищет прошлые решения и договорённости в логах сессий Claude Code через DuckDB. Помогает восстановить контекст диалога без ручного поиска по файлам. CX Codex +1 911установок save-session-learnings CloudAI-X Команда save-session-learnings переносит важные выводы из сессии в CLAUDE.md и AGENTS.md. Запускайте её после отладки или крупной задачи, чтобы сохранить контекст для следующих сессий. CX Codex +1 ★ 1 424звёзд репо pr-provenance-stamp Karan Bansal Плагин pr-provenance-stamp дописывает в тело пулл-реквеста квитанцию: число промптов, оценку расхода, коды возврата тестов и долю строк, написанных агентом. ★ 586звёзд репо

Из того же набора79

Весь набор →
backtesting-py-oracle Скилл backtesting-py-oracle настраивает backtesting.py для сверки торговых сигналов с расчётами в ClickHouse SQL. Помогает устранить расхождения в сделках при тестировании паттернов на рендж-барах. CX Codex +1 135установок doppler-secret-validation Скилл doppler-secret-validation помогает добавить секреты в Doppler, проверить их хранение и протестировать API-аутентификацию. Пригодится перед тем, как использовать токен в проекте. CX Codex +1 135установок link-validation Скилл link-validation проверяет ссылки в markdown-файлах проекта офлайн через lychee: относительные пути, корневые пути и якоря. Пригодится перед коммитом документации. CX Codex +1 135установок session-recovery Скилл session-recovery диагностирует и восстанавливает потерянные сессии Claude Code, если команда claude -r не находит историю диалогов или файлы пишутся не туда. CX Codex +1 135установок notion-sdk Скилл notion-sdk для Claude Code и Codex, работает с Notion через официальный Python SDK. Создаёт страницы и базы данных, запрашивает информацию, добавляет блоки контента — всё программно, без ручного ввода. CX Codex +1 133установок hooks-development Скилл hooks-development помогает создавать и отлаживать хуки Claude Code, особенно когда агент не видит их вывод. В нём разобраны форматы ответа и обработка событий. CX Codex +1 133установок asciinema-cast-format Скилл asciinema-cast-format для Claude Code помогает разбирать заголовки NDJSON и события терминала в записях .cast asciinema v3. CX Codex +1 132установок python-workspace Скилл python-workspace экспортирует котировки из MetaTrader 5 и переносит индикаторы MQL5 на Python с проверкой корреляции от 0.999. CX Codex +1 131установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой