Skip to content

refactor(session-history): move extraction scripts behind skills#619

Merged
tmchow merged 2 commits intomainfrom
tmchow/session-historian-skills
Apr 21, 2026
Merged

refactor(session-history): move extraction scripts behind skills#619
tmchow merged 2 commits intomainfrom
tmchow/session-historian-skills

Conversation

@tmchow
Copy link
Copy Markdown
Collaborator

@tmchow tmchow commented Apr 21, 2026

Summary

ce-session-historian used to reach into a sibling session-history-scripts/ directory for its four extraction scripts. That broke the repo convention that scripts live inside skills, not beside agents. This PR moves those scripts into two new agent-internal skills — ce-session-inventory and ce-session-extract — and has the agent invoke them via the Skill tool in fork context.

No behavior change for callers. /ce-sessions and /ce-compound's session-history phase work identically.

Why two skills, not four

The agent uses the scripts in two workflow phases:

Phase Scripts New skill
Inventory (always used together, piped) discover-sessions.sh + extract-metadata.py ce-session-inventory
Per-session deep-dive (selective, mode-parameterized) extract-skeleton.py + extract-errors.py ce-session-extract

One-skill-per-script would have fragmented the primitives below the level the agent operates at. Bundling all four into one skill would have blurred the inventory vs deep-dive distinction the agent makes.

Why user-invocable: false + context: fork

Both new skills set user-invocable: false so they don't auto-fire on user queries. They're agent-internal primitives, not end-user commands.

Both set context: fork so the bash-pipeline plumbing stays in the fork and only the JSONL output bubbles back. The agent's tool-call history stays clean across multiple ce-session-extract invocations during a single research task. The skills pass the "explicit instructions" test fork is designed for: positional args in, stdout verbatim out.

Scope

  • Agent rewrite: references to the old script directory removed; extraction delegated via the Skill tool.
  • Two new skills under plugins/compound-engineering/skills/, each with a small SKILL.md and a scripts/ directory holding the relevant scripts.
  • session-history-scripts/ removed from agents/research/.
  • tests/session-history-scripts.test.ts rewired to the new script locations; 30 tests pass.

Smoke-tested end-to-end

Both the /ce-sessions → agent → skills path and direct agent dispatch return clean results on Claude Code:

  • ce-session-inventory returned metadata cleanly with parse_errors: 0 on both tests.
  • Fork context correctly passed positional args and returned stdout.
  • ce-session-extract design verified against the skeleton and errors scripts; not exercised live in the smoke tests (the agent correctly judged metadata alone was sufficient for the two smoke questions).

Conversion notes

user-invocable and context aren't parsed by this plugin's TypeScript skill parser, so they pass through verbatim via copySkillDir when converting to other targets. Claude Code honors both natively. Kiro drops context: fork per its spec. Copilot's writer hardcodes user-invocable: true. End-to-end behavior on non-Claude-Code targets isn't verified yet.


Compound Engineering
Claude Code

tmchow added 2 commits April 20, 2026 22:27
Hoists the four session-history extraction scripts out of the
ce-session-historian agent's sibling directory and into two new skills:

- ce-session-inventory wraps discover-sessions.sh + extract-metadata.py
  for the discover-then-enrich inventory phase.
- ce-session-extract wraps extract-skeleton.py + extract-errors.py for
  per-session deep-dives.

ce-session-historian now invokes these skills via the Skill tool in
fork context instead of reaching into a sibling script directory.
Scripts live with skills (matching repo convention), the agent keeps
its format knowledge, methodology, and synthesis role, and callers of
the agent need no changes.

Both new skills set user-invocable: false and context: fork so they
act as agent-internal primitives: hidden from user query triggering,
with clean tool-call boundaries in the caller's context.

Tests updated to route to the new script locations.
@tmchow tmchow merged commit cd4af86 into main Apr 21, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant