session-start-routine

name	session-start-routine
description	Execute work session initialization routine at conversation start. Identifies new skills, researches improvements for existing skills, and updates skill library. Triggers automatically at session start.
version	2.0.0
category	meta
last_updated	"2026-01-02T00:00:00.000Z"
related_skills	["skill-creator","compliance-check","repo-sync"]

Session Start Routine Skill

Version: 2.0.0 Created: 2025-12-30 Last Updated: 2026-01-02

Overview

This meta-skill defines the mandatory work session initialization routine. At the start of every conversation, Claude should execute this routine to maintain and improve the skills library.

Quick Start

1. Trigger - Say "session start" or /session-start-routine
2. Health check - Claude scans skill locations
3. Review report - See skills health summary
4. Act on findings - Update stale skills if needed

# Quick health check command
find ~/.claude/skills -name "SKILL.md" -mtime +30 -exec echo "Stale: {}" \;

# Count skills
find ~/.claude/skills -name "SKILL.md" | wc -l

When to Use

• MANDATORY at every session start
• First message in a new conversation
• When explicitly requested with /session-start-routine
• After extended breaks between sessions
• When noticing skill-related issues

When to Trigger

MANDATORY at every session start:

• First message in a new conversation
• When explicitly requested with /session-start-routine

Session Routine Steps

Step 1: Skills Health Check

1. Scan both skill locations:
   - User-level: ~/.claude/skills/
   - Project-level: .claude/skills/

2. For each skill:
   - Verify SKILL.md exists and is valid
   - Check for version history section
   - Identify last update date
   - Flag skills not updated in 30+ days

3. Dependency Verification:
   - Check if tools/libraries referenced in skills still exist
   - Verify MCP servers mentioned are still available
   - Test that code examples are still valid
   - Flag skills with broken dependencies

Step 1b: Integration Check

1. MCP Server Compatibility:
   - List skills that reference MCP servers
   - Verify those servers exist in ~/.claude.json or .mcp.json
   - Check for deprecated MCP tool names

2. Agent Compatibility:
   - Verify skills work with current Claude Code agents
   - Check for deprecated agent patterns
   - Update agent references if needed

Step 1c: Cross-Skill Dependencies

1. Build dependency map:
   - Extract "Related Skills" sections
   - Identify which skills reference others
   - Detect orphaned or circular dependencies

2. Dependency Graph:
   skill-creator
     +-- sparc-workflow
     +-- mcp-builder
   rag-system-builder
     +-- knowledge-base-builder
     +-- semantic-search-setup
     +-- pdf-text-extractor

Step 2: Research & Improvement Identification

For each skill category, research:
1. Official documentation updates
   - Anthropic Claude documentation
   - Tool/library changelogs

2. Community best practices
   - GitHub trending repositories
   - Stack Overflow discussions

3. Industry trends
   - New tools/libraries
   - Methodology updates
   - Security advisories

Step 3: Skill Updates

For skills needing updates:
1. Research latest best practices online
2. Identify specific improvements:
   - New features to document
   - Deprecated approaches to remove
   - Better code examples
   - Performance optimizations

3. Apply updates with version comment:
   ---
   ## Version History
   - **X.Y.Z** (YYYY-MM-DD): [Changes made]
   ---

Step 4: New Skill Identification

Evaluate need for new skills based on:

1. GAPS: Missing capabilities discovered during work
   - "I needed to do X but no skill existed"
   - Repeated manual processes

2. PATTERNS: Common workflows across sessions
   - Frequently used tool combinations
   - Repeated prompt patterns

3. TRENDS: Industry/technology developments
   - New Claude Code features
   - New MCP servers
   - Popular libraries/tools
   - AI/ML advancements

Step 5: Documentation Update

1. Update skills/README.md with:
   - New skills added
   - Skills updated
   - Skills deprecated

2. Commit changes with descriptive message

Session Report Template

At the end of routine, provide summary:

## Session Start Report - [DATE]

### Skills Health
- Total Skills: [N]
- User-Level: [N] | Project-Level: [N]
- Updated This Session: [N]
- Flagged for Review: [N]

### Improvements Made
| Skill | Version | Changes |
|-------|---------|---------|
| skill-name | X.Y.Z | Brief description |

### New Skills Identified
| Proposed Skill | Category | Rationale |
|----------------|----------|-----------|
| skill-name | category | Why needed |

### Research Findings
- [Key finding 1]
- [Key finding 2]

### Next Session Priorities
1. [Priority 1]
2. [Priority 2]

Execution Checklist

Before routine:

• Session context established
• Access to skill directories confirmed
• Network access for research (optional)

During routine:

• User-level skills scanned
• Project-level skills scanned
• Stale skills identified (30+ days)
• Broken dependencies flagged
• Cross-skill dependencies mapped

After routine:

• Session report generated
• Priority actions identified
• Updates committed (if any)
• README updated (if changes)

Skill Update Guidelines

Version Numbering

MAJOR.MINOR.PATCH

MAJOR: Breaking changes, complete rewrites
MINOR: New features, significant improvements
PATCH: Bug fixes, small updates, typo fixes

Version Comment Format

Add at end of SKILL.md:

---

## Version History

- **1.2.0** (2025-12-30): Added new section for X, updated examples
- **1.1.1** (2025-12-15): Fixed typo in command example
- **1.1.0** (2025-12-01): Added integration with tool Y
- **1.0.0** (2025-11-15): Initial release

Error Handling

Common Errors

Error: Skill directory not accessible

• Cause: Permissions or path issues
• Solution: Verify ~/.claude/skills/ exists and is readable

Error: SKILL.md parsing fails

• Cause: Invalid YAML frontmatter or markdown
• Solution: Validate frontmatter syntax, check for unclosed code blocks

Error: MCP server not found

• Cause: Referenced MCP server not configured
• Solution: Update skill to remove reference or add server to config

Error: Circular dependency detected

• Cause: Skills reference each other in loop
• Solution: Review related_skills, break the cycle

Error: Too many stale skills

• Cause: Routine not run regularly
• Solution: Prioritize most-used skills, update in batches

Research Sources

Official Documentation

• Claude Code Documentation
• MCP Specification
• Anthropic Cookbook

Community Resources

• Anthropic Skills Repository
• Claude Code Community
• GitHub trending repositories

Technology Updates

• Python/Node.js changelogs
• Library release notes
• Security advisories (CVE databases)

Integration Points

With Other Skills

• Uses skill-creator patterns for new skills
• Follows compliance-check standards
• Updates workspace-hub skills as needed

With Workflows

• Can trigger before SPARC workflow
• Integrates with git operations for commits
• Works with Agent OS task execution

Automation Hooks

Pre-Session Check

# Quick health check script
find ~/.claude/skills -name "SKILL.md" -mtime +30 -exec echo "Stale: {}" \;

Post-Update Commit

# Commit pattern for skill updates
git add ~/.claude/skills/
git commit -m "chore(skills): session update - [YYYY-MM-DD]

- Updated: [skill1], [skill2]
- Added: [new-skill]
- Research: [topic]"

Usage Analytics

Track skill usage to prioritize improvements:

1. Usage Tracking:
   - Note which skills are triggered during sessions
   - Track frequency of skill invocations
   - Identify most/least used skills

2. Prioritization Matrix:
   HIGH PRIORITY (Frequently used, needs update):
   - mcp-builder (used 50+/month, last update 30+ days)

   MEDIUM PRIORITY (Used often, recently updated):
   - rag-system-builder (used 30+/month, updated recently)

   LOW PRIORITY (Rarely used):
   - algorithmic-art (used 2/month)

3. Usage Log Format:
   ~/.claude/skills/.usage-log.json
   {
     "2025-12-30": {
       "mcp-builder": 3,
       "rag-system-builder": 2,
       "sparc-workflow": 5
     }
   }

Deprecation Review

Flag outdated skills for removal or major update:

1. Deprecation Criteria:
   - Not updated in 90+ days
   - References deprecated tools/APIs
   - Superseded by better skill
   - Zero usage in 60+ days

2. Deprecation Process:
   a. Add DEPRECATED prefix to description
   b. Add deprecation notice at top of SKILL.md
   c. Point to replacement skill
   d. Remove after 30-day grace period

3. Deprecation Notice Template:
   ---
   name: old-skill-name
   description: DEPRECATED - Use new-skill-name instead. [Original description]
   deprecated: true
   deprecated_date: 2025-12-30
   replacement: new-skill-name
   ---

   > **DEPRECATED**: This skill is deprecated. Use [new-skill-name](../new-skill-name/SKILL.md) instead.
   > Will be removed after 2025-01-30.

Metrics

Track over time:

Metric	Target	How to Measure
Skills updated per session	1-3	Count of version bumps
New skills added per month	2-5	New SKILL.md files
Stale skill ratio	<20%	Skills 30+ days old / total
Trigger accuracy	>90%	Correct activations
Integration health	100%	Working MCP/agent refs
Deprecation candidates	<5%	Unused 60+ days

Best Practices

1. Consistency: Run at every session start
2. Brevity: Keep updates focused, don't over-engineer
3. Documentation: Always add version comments
4. Research First: Check online before updating
5. Prioritize: Focus on most-used skills first
6. Test: Verify updated skills still work correctly

Related Skills

Note: Skills may be at user-level (~/.claude/skills/) or workspace-level (workspace-hub/.claude/skills/)

Skill	Purpose	Location
skill-creator	Create new skills	workspace-hub/.claude/skills/builders/skill-creator/
context-management	Manage context limits	.claude/skills/context-management/
dev-workflow	Development workflow	.claude/skills/workflows/dev-workflow/
codex-review	Cross-review with Codex	.claude/skills/workflows/codex-review/

---

Version History

• 2.0.1 (2026-01-20): Fixed related skills links - replaced broken relative paths with table format showing actual locations
• 2.0.0 (2026-01-02): Upgraded to v2 template - added Quick Start, When to Use, Execution Checklist, Error Handling, enhanced Metrics sections; enhanced frontmatter with version, category, related_skills
• 1.0.0 (2025-12-30): Initial release - session start routine skill