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

• Trigger - Say "session start" or /session-start-routine

• Health check - Claude scans skill locations

• Review report - See skills health summary

• 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

New Skills Identified

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 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

• Consistency: Run at every session start

• Brevity: Keep updates focused, don't over-engineer

• Documentation: Always add version comments

• Research First: Check online before updating

• Prioritize: Focus on most-used skills first

• 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