chore: Archive update-skills-lesson change

openspec/changes/fix-context-usage-hook/proposal.md

@@ -0,0 +1,44 @@
+# Change: Fix Context Usage Hook Token Calculation
+
+## Why
+
+The context-usage hook (Stop event) always reports 0 tokens because of a bug in line 68 of `context-usage.py`:
+
+```python
+estimated_tokens = estimate_tokens(str(total_chars))
+```
+
+This converts the integer `total_chars` (e.g., `156789`) to a string `"156789"` and then calculates tokens from that 6-character string, resulting in `6 // 4 = 1` token instead of `156789 // 4 = ~39,197` tokens.
+
+**Current behavior:**
+```
+Stop says: Context: ~0/200,000 tokens (100.0% remaining)
+```
+
+**Expected behavior:**
+```
+Stop says: Context: ~39,197/200,000 tokens (80.4% remaining)
+```
+
+## What
+
+Fix the token calculation bug in the context-usage.py example hook:
+1. Remove the erroneous `str()` conversion
+2. Calculate estimated tokens directly from character count
+
+## Scope
+
+- **Files affected:**
+  - `06-hooks/README.md` - Update the example code
+  - User's `~/.claude/hooks/context-usage.py` - Not managed by this repo, but fix will be documented
+
+## Out of Scope
+
+- Improving transcript parsing logic
+- Adding more sophisticated token estimation
+- Adding new hook features
+
+## Risks
+
+- **Low:** Simple bug fix with clear expected behavior
+- Users who copied the broken example will need to update their hook manually

openspec/changes/fix-context-usage-hook/specs/hooks-documentation/spec.md

@@ -0,0 +1,24 @@
+# hooks-documentation Specification Delta
+
+## MODIFIED Requirements
+
+### Requirement: Context Usage Reporting Hook Example
+The hooks lesson SHALL include a correct, working example showing how to create a hook that reports context/token usage after each Claude response.
+
+#### Scenario: Token calculation is correct
+- **WHEN** a user copies the context-usage.py example
+- **AND** runs it as a Stop hook
+- **THEN** the hook correctly calculates estimated tokens from total character count
+- **AND** displays a non-zero token count proportional to conversation length
+
+#### Scenario: User learns to create context monitoring hook
+- **WHEN** a user reads the context usage reporter example
+- **THEN** they find a complete Python script that reads the transcript file
+- **AND** they understand how to estimate token usage from conversation history
+- **AND** they see the configuration for Stop hooks
+- **AND** they understand the limitations of token estimation
+
+#### Scenario: Hook output format is documented
+- **WHEN** a user implements the context usage hook
+- **THEN** they can generate a one-line report showing used tokens and remaining capacity
+- **AND** the output shows realistic token counts based on conversation size

openspec/changes/fix-context-usage-hook/tasks.md

@@ -0,0 +1,20 @@
+# Tasks: Fix Context Usage Hook Token Calculation
+
+## Implementation Tasks
+
+### 1. Fix the bug in 06-hooks/README.md example
+- [ ] Update line 564 in the context-usage.py example: change `estimate_tokens(str(total_chars))` to `total_chars // 4`
+- [ ] Remove the now-unused `estimate_tokens()` function from the example
+
+### 2. Update user's local hook file
+- [ ] Fix `~/.claude/hooks/context-usage.py` with the same correction
+
+### 3. Verification
+- [ ] Test the hook by running Claude Code and confirming non-zero token count is displayed
+- [ ] Verify the percentage calculation is reasonable (should show usage increasing during conversation)
+
+## Acceptance Criteria
+
+- [ ] After Claude responds, the Stop hook displays a non-zero token estimate
+- [ ] The displayed percentage decreases as conversation grows
+- [ ] Example in README.md matches the corrected implementation

openspec/changes/update-memory-lesson/proposal.md

@@ -0,0 +1,32 @@
+# Change: Update Memory Lesson with Latest Documentation
+
+## Why
+
+The current memory lesson (`blog-posts/02-memory.md`) is based on older Claude Code documentation. The official documentation at `https://code.claude.com/docs/en/memory` includes several new features and updates that the lesson doesn't cover, making it incomplete for readers who want to learn about Claude Code's full memory capabilities.
+
+## What Changes
+
+### New Features to Add
+- **Project Rules** (`.claude/rules/*.md`) - Modular, topic-specific markdown files for organizing instructions
+- **Path-Specific Rules** - YAML frontmatter with `paths:` to scope rules to specific file patterns
+- **Glob Pattern Support** - Examples of glob patterns for path-specific rules
+- **Project Local Memory** (`CLAUDE.local.md`) - Personal project preferences that are auto-gitignored
+- **Symlink Support** - Sharing rules across projects using symbolic links
+
+### Updates to Existing Content
+- **Memory Hierarchy Table** - Update to include Project Rules and Project Local as additional memory types
+- **Enterprise Policy Windows Path** - Correct to `C:\Program Files\ClaudeCode\CLAUDE.md` (currently shows `C:\ProgramData\ClaudeCode\CLAUDE.md`)
+- **Memory Lookup Algorithm** - Add detailed explanation of recursive upward search behavior
+- **Best Practices Section** - Add guidelines for `.claude/rules/` organization
+
+### Structure Improvements
+- Add new section: "Modular Rules with `.claude/rules/`"
+- Add new section: "Path-Specific Rules"
+- Update directory structure example to show `.claude/rules/` organization
+- Improve organization of content to match official documentation structure
+
+## Impact
+
+- **Affected files**: `blog-posts/02-memory.md`
+- **User benefit**: Readers will learn about complete memory capabilities including modular rules and path-specific scoping
+- **No breaking changes**: All existing content remains valid; this adds new sections and updates outdated information

openspec/changes/update-memory-lesson/specs/memory-lesson/spec.md

@@ -0,0 +1,69 @@
+## MODIFIED Requirements
+
+### Requirement: Memory Hierarchy Documentation
+The memory lesson SHALL document the complete 5-level memory hierarchy including Enterprise Policy, Project Memory, Project Rules, User Memory, and Project Local memory types.
+
+#### Scenario: Complete hierarchy explanation
+- **WHEN** a reader views the memory hierarchy section
+- **THEN** they SHALL see all 5 memory levels with their locations, scopes, and sharing capabilities
+
+#### Scenario: Enterprise Policy Windows path
+- **WHEN** a reader views the Enterprise Policy location for Windows
+- **THEN** the path SHALL be `C:\Program Files\ClaudeCode\CLAUDE.md`
+
+#### Scenario: Memory type comparison table
+- **WHEN** a reader views the memory type comparison table
+- **THEN** it SHALL include Project Rules (`.claude/rules/*.md`) and Project Local (`CLAUDE.local.md`) as distinct types
+
+## ADDED Requirements
+
+### Requirement: Modular Rules Documentation
+The memory lesson SHALL document the `.claude/rules/` directory for organizing instructions into topic-specific markdown files.
+
+#### Scenario: Rules directory structure
+- **WHEN** a reader views the modular rules section
+- **THEN** they SHALL see an example directory structure showing `.claude/rules/` with subdirectories
+
+#### Scenario: Benefits explanation
+- **WHEN** a reader views the modular rules section
+- **THEN** they SHALL understand the benefits of topic-specific rule files for organization
+
+### Requirement: Path-Specific Rules Documentation
+The memory lesson SHALL document how to use YAML frontmatter with `paths:` directive to scope rules to specific file patterns.
+
+#### Scenario: YAML frontmatter example
+- **WHEN** a reader views the path-specific rules section
+- **THEN** they SHALL see an example of YAML frontmatter with `paths:` directive
+
+#### Scenario: Glob pattern table
+- **WHEN** a reader views the path-specific rules section
+- **THEN** they SHALL see a table of glob pattern examples with explanations
+
+### Requirement: Project Local Memory Documentation
+The memory lesson SHALL document `CLAUDE.local.md` files for personal project preferences that are auto-gitignored.
+
+#### Scenario: Local memory explanation
+- **WHEN** a reader views the project local memory section
+- **THEN** they SHALL understand that `CLAUDE.local.md` is for personal preferences on shared projects
+
+#### Scenario: Auto-gitignore behavior
+- **WHEN** a reader views the project local memory section
+- **THEN** they SHALL understand that these files are automatically excluded from git
+
+### Requirement: Symlink Support Documentation
+The memory lesson SHALL document how to share rules across projects using symbolic links.
+
+#### Scenario: Symlink examples
+- **WHEN** a reader views the symlink support section
+- **THEN** they SHALL see bash examples for creating symlinks to shared rule files and directories
+
+### Requirement: Memory Lookup Algorithm Documentation
+The memory lesson SHALL document how Claude Code discovers and loads memory files recursively.
+
+#### Scenario: Recursive search explanation
+- **WHEN** a reader views the memory lookup section
+- **THEN** they SHALL understand the recursive upward search from current directory to root
+
+#### Scenario: Subtree discovery
+- **WHEN** a reader views the memory lookup section
+- **THEN** they SHALL understand that subtree files are discovered when those files are accessed

openspec/changes/update-memory-lesson/tasks.md

@@ -0,0 +1,46 @@
+## 1. Update Memory Hierarchy Section
+- [ ] 1.1 Update the memory hierarchy table to include 5 levels (Enterprise, Project, Project Rules, User, Project Local)
+- [ ] 1.2 Update the mermaid diagram to show the complete hierarchy
+- [ ] 1.3 Fix Windows Enterprise Policy path from `C:\ProgramData\ClaudeCode\CLAUDE.md` to `C:\Program Files\ClaudeCode\CLAUDE.md`
+- [ ] 1.4 Add explanation of precedence and loading order
+
+## 2. Add Modular Rules Section
+- [ ] 2.1 Create new section "Modular Rules with `.claude/rules/`"
+- [ ] 2.2 Add directory structure example showing `.claude/rules/` organization
+- [ ] 2.3 Explain benefits of topic-specific rule files
+- [ ] 2.4 Add examples of modular rule filenames (code-style.md, testing.md, security.md)
+
+## 3. Add Path-Specific Rules Section
+- [ ] 3.1 Create new section "Path-Specific Rules with Glob Patterns"
+- [ ] 3.2 Explain YAML frontmatter with `paths:` directive
+- [ ] 3.3 Add table of glob pattern examples (`**/*.ts`, `src/**/*`, etc.)
+- [ ] 3.4 Include practical example of path-scoped API rules
+
+## 4. Add Project Local Memory Section
+- [ ] 4.1 Add explanation of `CLAUDE.local.md` file
+- [ ] 4.2 Explain auto-gitignore behavior
+- [ ] 4.3 Add use case examples (personal preferences on shared projects)
+
+## 5. Add Symlink Support Section
+- [ ] 5.1 Add section on sharing rules across projects using symlinks
+- [ ] 5.2 Include bash examples for creating symlinks to shared rules
+
+## 6. Update Memory Lookup Algorithm
+- [ ] 6.1 Add detailed explanation of recursive upward search
+- [ ] 6.2 Explain subtree discovery behavior
+- [ ] 6.3 Add example of which files are loaded from different directories
+
+## 7. Update Best Practices
+- [ ] 7.1 Add best practices for `.claude/rules/` organization
+- [ ] 7.2 Add guidelines for using path-specific rules sparingly
+- [ ] 7.3 Add tips for symlink-based rule sharing
+
+## 8. Update Directory Structure Example
+- [ ] 8.1 Update the directory structure to show `.claude/rules/` hierarchy
+- [ ] 8.2 Include subdirectory examples (frontend/, backend/)
+
+## 9. Review and Polish
+- [ ] 9.1 Ensure all mermaid diagrams are updated
+- [ ] 9.2 Review table formatting consistency
+- [ ] 9.3 Update "Official Documentation" links if needed
+- [ ] 9.4 Verify all code examples are accurate

openspec/specs/skills-lesson/spec.md

@@ -0,0 +1,67 @@
+# skills-lesson Specification
+
+## Purpose
+TBD - created by archiving change update-skills-lesson. Update Purpose after archive.
+## Requirements
+### Requirement: Managing Skills Documentation
+The skills lesson SHALL provide comprehensive guidance for managing skills including viewing available skills, testing skills, updating skills with restart requirements, and removing skills.
+
+#### Scenario: User wants to view available skills
+- **WHEN** a user wants to see what skills are available
+- **THEN** the documentation provides both CLI method (asking Claude "What Skills are available?") and filesystem method (ls ~/.claude/skills/ and ls .claude/skills/)
+
+#### Scenario: User wants to test a skill
+- **WHEN** a user wants to test if their skill works
+- **THEN** the documentation explains that skills activate automatically based on matching descriptions, with example test queries
+
+#### Scenario: User wants to update a skill
+- **WHEN** a user modifies a SKILL.md file
+- **THEN** the documentation explains that changes take effect on next Claude Code startup and restart is required if already running
+
+#### Scenario: User wants to remove a skill
+- **WHEN** a user wants to remove a skill
+- **THEN** the documentation provides rm -rf commands for both personal and project skills, with git commit for project skills
+
+### Requirement: Enhanced Debugging Guidance
+The skills lesson SHALL provide detailed debugging guidance for common skill issues including skipped skills, YAML errors, script permissions, and path formats.
+
+#### Scenario: Skill not being discovered
+- **WHEN** Claude doesn't use a user's skill
+- **THEN** the documentation explains to check: description specificity, YAML syntax validity (opening/closing ---, no tabs), and correct file path location
+
+#### Scenario: Skill has errors
+- **WHEN** a skill has runtime errors
+- **THEN** the documentation explains to check: dependency installation, script execute permissions (chmod +x), and forward slash usage in paths
+
+#### Scenario: Multiple skills conflict
+- **WHEN** multiple skills are activated unexpectedly
+- **THEN** the documentation explains using distinct trigger terms in descriptions to help Claude choose the right skill
+
+### Requirement: Version History Documentation
+The skills lesson SHALL include a best practice example for documenting skill version history in SKILL.md files.
+
+#### Scenario: User wants to track skill versions
+- **WHEN** a user maintains a skill over time
+- **THEN** the documentation provides a version history markdown template with date and description format
+
+### Requirement: Enhanced Tool Access Control Documentation
+The skills lesson SHALL provide expanded documentation for the allowed-tools feature including use cases, security examples, and behavior when not specified.
+
+#### Scenario: User wants a read-only skill
+- **WHEN** a user wants to create a skill that cannot modify files
+- **THEN** the documentation provides an example with allowed-tools: Read, Grep, Glob
+
+#### Scenario: User wants security-sensitive workflow
+- **WHEN** a user has a security-sensitive skill
+- **THEN** the documentation explains how allowed-tools restricts Claude's capabilities within that skill context
+
+#### Scenario: allowed-tools not specified
+- **WHEN** a user doesn't specify allowed-tools
+- **THEN** the documentation explains that Claude will ask for permission as normal
+
+### Requirement: Multi-File Skill Example
+The skills lesson SHALL include a comprehensive example of a multi-file skill showing directory structure with multiple reference files, scripts, and templates.
+
+#### Scenario: User wants to create complex skill
+- **WHEN** a user needs a skill with supporting files
+- **THEN** the documentation provides a complete directory structure example showing SKILL.md, reference files (FORMS.md, REFERENCE.md), scripts subdirectory, and progressive disclosure explanation