From 10e1d3fe77919af0dfb44081e0f4f811a083e532 Mon Sep 17 00:00:00 2001 From: Dickson Tsai Date: Tue, 28 Oct 2025 02:39:56 -0700 Subject: [PATCH 1/2] Implement a plugin as alternative for deprecated Explanatory output style --- .../.claude-plugin/plugin.json | 9 +++ plugins/explanatory-output-style/README.md | 56 +++++++++++++++++++ .../hooks-handlers/session-start.sh | 15 +++++ .../explanatory-output-style/hooks/hooks.json | 15 +++++ 4 files changed, 95 insertions(+) create mode 100644 plugins/explanatory-output-style/.claude-plugin/plugin.json create mode 100644 plugins/explanatory-output-style/README.md create mode 100755 plugins/explanatory-output-style/hooks-handlers/session-start.sh create mode 100644 plugins/explanatory-output-style/hooks/hooks.json diff --git a/plugins/explanatory-output-style/.claude-plugin/plugin.json b/plugins/explanatory-output-style/.claude-plugin/plugin.json new file mode 100644 index 00000000..1a98d12c --- /dev/null +++ b/plugins/explanatory-output-style/.claude-plugin/plugin.json @@ -0,0 +1,9 @@ +{ + "name": "explanatory-output-style", + "version": "1.0.0", + "description": "Adds educational insights about implementation choices and codebase patterns (mimics the deprecated Explanatory output style)", + "author": { + "name": "Anthropic", + "email": "support@anthropic.com" + } +} diff --git a/plugins/explanatory-output-style/README.md b/plugins/explanatory-output-style/README.md new file mode 100644 index 00000000..bd96601d --- /dev/null +++ b/plugins/explanatory-output-style/README.md @@ -0,0 +1,56 @@ +# Explanatory Output Style Plugin + +This plugin recreates the deprecated Explanatory output style as a SessionStart hook. + +## What it does + +When enabled, this plugin automatically adds instructions at the start of each session that encourage Claude to: + +1. Provide educational insights about implementation choices +2. Explain codebase patterns and decisions +3. Balance task completion with learning opportunities + +## How it works + +The plugin uses a SessionStart hook to inject additional context into every session. This context instructs Claude to provide brief educational explanations before and after writing code, formatted as: + +``` +`★ Insight ─────────────────────────────────────` +[2-3 key educational points] +`─────────────────────────────────────────────────` +``` + +## Installation + +Install this plugin from the Claude Code marketplace, or manually by placing it in your `.claude/plugins` directory. + +## Usage + +Once installed, the plugin activates automatically at the start of every session. No additional configuration is needed. + +The insights focus on: +- Specific implementation choices for your codebase +- Patterns and conventions in your code +- Trade-offs and design decisions +- Codebase-specific details rather than general programming concepts + +## Migration from Output Styles + +This plugin replaces the deprecated "Explanatory" output style setting. If you previously used: + +```json +{ + "outputStyle": "Explanatory" +} +``` + +You can now achieve the same behavior by installing this plugin instead. + +## Managing changes + +* Disable the plugin - keep the code installed on your device +* Uninstall the plugin - remove the code from your device +* Update the plugin - create a local copy of this plugin to personalize this plugin + - Hint: Ask Claude to read https://docs.claude.com/en/docs/claude-code/plugins.md and set it up for you! + + diff --git a/plugins/explanatory-output-style/hooks-handlers/session-start.sh b/plugins/explanatory-output-style/hooks-handlers/session-start.sh new file mode 100755 index 00000000..cd2cad82 --- /dev/null +++ b/plugins/explanatory-output-style/hooks-handlers/session-start.sh @@ -0,0 +1,15 @@ +#!/bin/bash + +# Output the explanatory mode instructions as additionalContext +# This mimics the deprecated Explanatory output style + +cat << 'EOF' +{ + "hookSpecificOutput": { + "hookEventName": "SessionStart", + "additionalContext": "You are in 'explanatory' output style mode, where you should provide educational insights about the codebase as you help with the user's task.\n\nYou should be clear and educational, providing helpful explanations while remaining focused on the task. Balance educational content with task completion. When providing insights, you may exceed typical length constraints, but remain focused and relevant.\n\n## Insights\nIn order to encourage learning, before and after writing code, always provide brief educational explanations about implementation choices using (with backticks):\n\"`★ Insight ─────────────────────────────────────`\n[2-3 key educational points]\n`─────────────────────────────────────────────────`\"\n\nThese insights should be included in the conversation, not in the codebase. You should generally focus on interesting insights that are specific to the codebase or the code you just wrote, rather than general programming concepts. Do not wait until the end to provide insights. Provide them as you write code." + } +} +EOF + +exit 0 diff --git a/plugins/explanatory-output-style/hooks/hooks.json b/plugins/explanatory-output-style/hooks/hooks.json new file mode 100644 index 00000000..d1fb8a57 --- /dev/null +++ b/plugins/explanatory-output-style/hooks/hooks.json @@ -0,0 +1,15 @@ +{ + "description": "Explanatory mode hook that adds educational insights instructions", + "hooks": { + "SessionStart": [ + { + "hooks": [ + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/hooks-handlers/session-start.sh" + } + ] + } + ] + } +} From 8b47e224a0b2248dc4bfea1254258248a4144b64 Mon Sep 17 00:00:00 2001 From: Dickson Tsai Date: Wed, 29 Oct 2025 08:37:48 -0700 Subject: [PATCH 2/2] Editorial changes --- .../.claude-plugin/plugin.json | 4 +- plugins/explanatory-output-style/README.md | 46 +++++++++++++------ 2 files changed, 33 insertions(+), 17 deletions(-) diff --git a/plugins/explanatory-output-style/.claude-plugin/plugin.json b/plugins/explanatory-output-style/.claude-plugin/plugin.json index 1a98d12c..a70cbf97 100644 --- a/plugins/explanatory-output-style/.claude-plugin/plugin.json +++ b/plugins/explanatory-output-style/.claude-plugin/plugin.json @@ -3,7 +3,7 @@ "version": "1.0.0", "description": "Adds educational insights about implementation choices and codebase patterns (mimics the deprecated Explanatory output style)", "author": { - "name": "Anthropic", - "email": "support@anthropic.com" + "name": "Dickson Tsai", + "email": "dickson@anthropic.com" } } diff --git a/plugins/explanatory-output-style/README.md b/plugins/explanatory-output-style/README.md index bd96601d..f7de6326 100644 --- a/plugins/explanatory-output-style/README.md +++ b/plugins/explanatory-output-style/README.md @@ -1,10 +1,15 @@ # Explanatory Output Style Plugin -This plugin recreates the deprecated Explanatory output style as a SessionStart hook. +This plugin recreates the deprecated Explanatory output style as a SessionStart +hook. + +WARNING: Do not install this plugin unless you are fine with incurring the token +cost of this plugin's additional instructions and output. ## What it does -When enabled, this plugin automatically adds instructions at the start of each session that encourage Claude to: +When enabled, this plugin automatically adds instructions at the start of each +session that encourage Claude to: 1. Provide educational insights about implementation choices 2. Explain codebase patterns and decisions @@ -12,7 +17,9 @@ When enabled, this plugin automatically adds instructions at the start of each s ## How it works -The plugin uses a SessionStart hook to inject additional context into every session. This context instructs Claude to provide brief educational explanations before and after writing code, formatted as: +The plugin uses a SessionStart hook to inject additional context into every +session. This context instructs Claude to provide brief educational explanations +before and after writing code, formatted as: ``` `★ Insight ─────────────────────────────────────` @@ -20,15 +27,13 @@ The plugin uses a SessionStart hook to inject additional context into every sess `─────────────────────────────────────────────────` ``` -## Installation - -Install this plugin from the Claude Code marketplace, or manually by placing it in your `.claude/plugins` directory. - ## Usage -Once installed, the plugin activates automatically at the start of every session. No additional configuration is needed. +Once installed, the plugin activates automatically at the start of every +session. No additional configuration is needed. The insights focus on: + - Specific implementation choices for your codebase - Patterns and conventions in your code - Trade-offs and design decisions @@ -36,7 +41,8 @@ The insights focus on: ## Migration from Output Styles -This plugin replaces the deprecated "Explanatory" output style setting. If you previously used: +This plugin replaces the deprecated "Explanatory" output style setting. If you +previously used: ```json { @@ -46,11 +52,21 @@ This plugin replaces the deprecated "Explanatory" output style setting. If you p You can now achieve the same behavior by installing this plugin instead. +More generally, this SessionStart hook pattern is roughly equivalent to +CLAUDE.md, but it is more flexible and allows for distribution through plugins. + +Note: Output styles that involve tasks besides software development, are better +expressed as +[subagents](https://docs.claude.com/en/docs/claude-code/sub-agents), not as +SessionStart hooks. Subagents change the system prompt while SessionStart hooks +add to the default system prompt. + ## Managing changes -* Disable the plugin - keep the code installed on your device -* Uninstall the plugin - remove the code from your device -* Update the plugin - create a local copy of this plugin to personalize this plugin - - Hint: Ask Claude to read https://docs.claude.com/en/docs/claude-code/plugins.md and set it up for you! - - +- Disable the plugin - keep the code installed on your device +- Uninstall the plugin - remove the code from your device +- Update the plugin - create a local copy of this plugin to personalize this + plugin + - Hint: Ask Claude to read + https://docs.claude.com/en/docs/claude-code/plugins.md and set it up for + you!