starred/planning-with-files

Fork 0

mirror of https://github.com/OthmanAdi/planning-with-files.git synced 2026-04-26 08:26:01 +03:00

[GH-ISSUE #24] SessionStart hook does not work with Skill #17

New issue

Closed

opened 2026-03-03 18:50:00 +03:00 by kerem · 2 comments

kerem commented

2026-03-03 18:50:00 +03:00

Owner

Originally created by @tianyili-roller on GitHub (Jan 13, 2026).
Original GitHub issue: https://github.com/OthmanAdi/planning-with-files/issues/24

Context

According to official doc,
the supported events are PreToolUse, PostToolUse, and Stop.

The issue

Although the hooks section contains SessionStart, it won't work with skills.

name: planning-with-files
version: "2.1.2"
description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls.
user-invocable: true
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - WebFetch
  - WebSearch
hooks:
  SessionStart:
    - hooks:
        - type: command
          command: "echo '[planning-with-files] Ready. Auto-activates for complex tasks, or invoke manually with /planning-with-files'"
  PreToolUse:
    - matcher: "Write|Edit|Bash"
      hooks:
        - type: command
          command: "cat task_plan.md 2>/dev/null | head -30 || true"
  PostToolUse:
    - matcher: "Write|Edit"
      hooks:
        - type: command
          command: "echo '[planning-with-files] File updated. If this completes a phase, update task_plan.md status.'"
  Stop:
    - hooks:
        - type: command
          command: "${CLAUDE_PLUGIN_ROOT}/scripts/check-complete.sh"

Originally created by @tianyili-roller on GitHub (Jan 13, 2026). Original GitHub issue: https://github.com/OthmanAdi/planning-with-files/issues/24 ## Context According to [official doc](https://code.claude.com/docs/en/hooks#hooks-in-skills,-agents,-and-slash-commands), the supported events are PreToolUse, PostToolUse, and Stop. ## The issue Although the hooks section contains `SessionStart`, it won't work with skills. ```yaml name: planning-with-files version: "2.1.2" description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls. user-invocable: true allowed-tools: - Read - Write - Edit - Bash - Glob - Grep - WebFetch - WebSearch hooks: SessionStart: - hooks: - type: command command: "echo '[planning-with-files] Ready. Auto-activates for complex tasks, or invoke manually with /planning-with-files'" PreToolUse: - matcher: "Write|Edit|Bash" hooks: - type: command command: "cat task_plan.md 2>/dev/null | head -30 || true" PostToolUse: - matcher: "Write|Edit" hooks: - type: command command: "echo '[planning-with-files] File updated. If this completes a phase, update task_plan.md status.'" Stop: - hooks: - type: command command: "${CLAUDE_PLUGIN_ROOT}/scripts/check-complete.sh" ```

kerem closed this issue

2026-03-03 18:50:00 +03:00

kerem commented

2026-03-03 18:50:01 +03:00

Author

Owner

@OthmanAdi commented on GitHub (Jan 17, 2026):

Hi there,

Thanks for reporting this, and apologies for my delayed response!

Why SessionStart Doesn't Work in Skills

You've discovered an important limitation of Claude Code's skill system. Let me explain what's happening:

The Technical Issue

Skills use component-scoped hooks, which means hooks in SKILL.md only fire when that specific skill is actively loaded and executing.

SessionStart fires when Claude Code starts, but at that moment, skills aren't loaded yet! Claude Code uses "progressive disclosure" - skills only load on-demand when needed.

Result: SessionStart hooks in SKILL.md never fire because there's a timing mismatch.

This is By Design

From the official Claude Code hooks documentation:

Hooks in SKILL.md are component-scoped
They only run during skill execution
Global events like SessionStart happen before skills load

✅ Solutions That Actually Work

Option 1: Plugin-Level Hook (Best Solution)

Move the SessionStart hook from SKILL.md to plugin-level configuration.

Create .claude-plugin/hooks.json:

{
  "hooks": {
    "SessionStart": [
      {
        "type": "command",
        "command": "echo '[planning-with-files] Ready! Use /planning-with-files for complex tasks or include \"task plan\" in requests.'"
      }
    ]
  }
}

Update .claude-plugin/plugin.json to reference it:

{
  "name": "planning-with-files",
  "version": "2.2.0",
  "hooks": "hooks.json",
  ...
}

Option 2: User-Level Hook

Users can add this to their personal ~/.claude/hooks.json:

{
  "hooks": {
    "SessionStart": [
      {
        "type": "command",
        "command": "echo '💡 Tip: Use /planning-with-files for complex multi-step tasks'"
      }
    ]
  }
}

Option 3: Remove It (Current Approach)

Simply remove SessionStart from SKILL.md since it doesn't work. Focus on:

✅ PreToolUse hooks (these work!)
✅ PostToolUse hooks (these work!)
✅ Stop hooks (these work!)
✅ Manual invocation with /planning-with-files

What I'm Considering for v2.3.0

I may add plugin-level SessionStart hook in the next release. This would:

Fire when Claude Code starts
Remind users the plugin is available
Work regardless of skill activation

Documentation Update

I'll update the README to clarify:

SessionStart doesn't work in skill-scoped hooks
Users can add their own SessionStart reminders
Manual invocation (/planning-with-files) is the reliable approach

Bottom line: This isn't a bug - it's a limitation of how Claude Code's progressive loading works with component-scoped hooks. SessionStart needs to be at plugin-level or user-level, not skill-level.

Thanks for helping identify this! It'll improve the documentation for everyone.

Best regards,
Ahmad

@OthmanAdi commented on GitHub (Jan 17, 2026): Hi there, Thanks for reporting this, and apologies for my delayed response! ## Why SessionStart Doesn't Work in Skills You've discovered an important limitation of Claude Code's skill system. Let me explain what's happening: ### The Technical Issue **Skills use component-scoped hooks**, which means hooks in SKILL.md only fire when that specific skill is **actively loaded and executing**. **SessionStart fires when Claude Code starts**, but at that moment, skills aren't loaded yet! Claude Code uses "progressive disclosure" - skills only load on-demand when needed. **Result:** SessionStart hooks in SKILL.md never fire because there's a timing mismatch. ### This is By Design From the [official Claude Code hooks documentation](https://code.claude.com/docs/en/hooks): - Hooks in SKILL.md are **component-scoped** - They only run during skill execution - Global events like SessionStart happen before skills load ### ✅ Solutions That Actually Work #### Option 1: Plugin-Level Hook (Best Solution) Move the SessionStart hook from SKILL.md to plugin-level configuration. Create `.claude-plugin/hooks.json`: ```json { "hooks": { "SessionStart": [ { "type": "command", "command": "echo '[planning-with-files] Ready! Use /planning-with-files for complex tasks or include \"task plan\" in requests.'" } ] } } ``` Update `.claude-plugin/plugin.json` to reference it: ```json { "name": "planning-with-files", "version": "2.2.0", "hooks": "hooks.json", ... } ``` #### Option 2: User-Level Hook Users can add this to their personal `~/.claude/hooks.json`: ```json { "hooks": { "SessionStart": [ { "type": "command", "command": "echo '💡 Tip: Use /planning-with-files for complex multi-step tasks'" } ] } } ``` #### Option 3: Remove It (Current Approach) Simply remove SessionStart from SKILL.md since it doesn't work. Focus on: - ✅ PreToolUse hooks (these work!) - ✅ PostToolUse hooks (these work!) - ✅ Stop hooks (these work!) - ✅ Manual invocation with `/planning-with-files` ### What I'm Considering for v2.3.0 I may add plugin-level SessionStart hook in the next release. This would: - Fire when Claude Code starts - Remind users the plugin is available - Work regardless of skill activation ### Documentation Update I'll update the README to clarify: - SessionStart doesn't work in skill-scoped hooks - Users can add their own SessionStart reminders - Manual invocation (`/planning-with-files`) is the reliable approach --- **Bottom line:** This isn't a bug - it's a limitation of how Claude Code's progressive loading works with component-scoped hooks. SessionStart needs to be at plugin-level or user-level, not skill-level. Thanks for helping identify this! It'll improve the documentation for everyone. Best regards, Ahmad

kerem commented

2026-03-03 18:50:01 +03:00

Author

Owner

@OthmanAdi commented on GitHub (Jan 20, 2026):

any updates? @tianyili-roller

@OthmanAdi commented on GitHub (Jan 20, 2026): any updates? @tianyili-roller

No labels

bug

pull-request

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

starred/planning-with-files#17

No description provided.

Rows
Columns