Agent-Skills.md

Agent Skills: Upgrade Assessment

Assess platform upgrade readiness for Claude model and CC version changes. Use when evaluating upgrades.

document-asset-creationID: yonatangross/orchestkit/upgrade-assessment

Repository

yonatangross/orchestkit
yonatangrossLicense: MIT
13314

Install this agent skill to your local

pnpm dlx add-skill https://github.com/yonatangross/orchestkit/tree/HEAD/src/skills/upgrade-assessment

Skill Files

Browse the full folder contents for upgrade-assessment.

Download Skill

Loading file tree…

src/skills/upgrade-assessment/SKILL.md

Skill Metadata

Name
upgrade-assessment
Description
"Assess platform upgrade readiness for Claude model and CC version changes. Use when evaluating upgrades."

Upgrade Assessment

Evaluate platform upgrade readiness for Claude model transitions, Claude Code version bumps, and OrchestKit plugin updates. Produces a structured JSON assessment report with a 0-10 readiness score across 6 dimensions.

When to Use

  • Before upgrading the Claude model (e.g., Sonnet 4 to Opus 4.6)
  • Before upgrading Claude Code to a new major/minor version
  • Before upgrading OrchestKit to a new major version
  • When evaluating whether a team environment is ready for a platform change
  • As part of release planning for model or platform migrations

Quick Start

/ork:upgrade-assessment           # Interactive assessment
/ork:upgrade-assessment --json    # Machine-readable output

6-Phase Workflow

Phase 0: Scope Definition

Tool: AskUserQuestion

Determine the assessment scope before scanning. Ask the user:

What type of upgrade are you assessing?

  1. Full platform - Model + CC version + OrchestKit (comprehensive)
  2. Model only - Switching Claude model (e.g., Sonnet 4.5 to Opus 4.6)
  3. CC version only - Claude Code version bump (e.g., 2.1.32 to 2.1.33)
  4. OrchestKit only - Plugin version upgrade (e.g., 5.x to 6.x)

Record the scope and target versions. If the user does not specify target versions, research the latest available in Phase 2.

Phase 1: Detection

Tools: Bash, Read, Grep, Glob

Run precondition checks and environment detection. Load details: Read("${CLAUDE_SKILL_DIR}/rules/detection-checks.md") for verification scripts and expected output format.

Phase 2: Research

Tools: WebSearch, WebFetch

Research the target versions for new capabilities and breaking changes:

  1. Model changes: Search for target model capabilities, breaking changes, new tool support
  2. CC version changes: Search for changelog, new hook types, skill format changes, deprecated fields
  3. OrchestKit changes: Read CHANGELOG.md, identify new/removed/renamed skills, hook migration needs

Research queries:

"Claude {target_model} capabilities release notes"
"Claude Code {target_version} changelog breaking changes"
"Claude {target_model} vs {current_model} differences"

Phase 3: Codebase Scan

Tools: Grep, Glob, Read

Scan the codebase for patterns affected by the upgrade. Load details: Read("${CLAUDE_SKILL_DIR}/rules/codebase-scan-patterns.md") for grep patterns and severity classification.

Phase 4: Scoring

Rate readiness 0-10 across 6 dimensions using the scoring rubric from platform-upgrade-knowledge. Load details: Read("${CLAUDE_SKILL_DIR}/references/scoring-rubric.md") for per-dimension thresholds, weights, and score interpretation.

Phase 5: Recommendations

Generate prioritized action items based on Phase 3 findings and Phase 4 scores. Load details: Read("${CLAUDE_SKILL_DIR}/references/recommendation-format.md") for priority assignment algorithm, effort estimation, and recommendation structure.

Output Format

The assessment produces a structured JSON report. Load details: Read("${CLAUDE_SKILL_DIR}/references/output-format.md") for the full schema and example.

Execution Notes

For Model-Only Upgrades

Focus on Phases 1, 2, and 3. Key areas:

  • Agent model: fields
  • Context window / output token assumptions
  • Capability-dependent skill content (e.g., vision, audio)

For CC Version Upgrades

Focus on hook compatibility and skill format:

  • Hook type registry changes
  • Skill frontmatter field additions/removals
  • Permission rule format changes
  • New built-in tools or removed tools

For OrchestKit Upgrades

Focus on plugin structure:

  • Manifest schema changes
  • Build system changes
  • Skill/agent rename or removal
  • Hook source reorganization

Rules Quick Reference

Load on demand with Read("${CLAUDE_SKILL_DIR}/rules/<file>"):

| Rule | Impact | What It Covers | |------|--------|----------------| | detection-checks.md | HIGH | Precondition checks, environment detection scripts | | codebase-scan-patterns.md | HIGH | Grep patterns, severity classification | | knowledge-evaluation.md | HIGH | 6-dimension scoring rubric, severity classification | | knowledge-compatibility.md | HIGH | Version compatibility matrix, breaking change detection |

Related Skills

  • platform-upgrade-knowledge - Scoring rubric details and compatibility matrix
  • ork:doctor - Post-upgrade health validation
  • ork:explore - Codebase exploration for impact analysis
  • ork:verify - Verification of changes after migration
  • ork:devops-deployment - CI/CD pipeline updates

References

Load on demand with Read("${CLAUDE_SKILL_DIR}/references/<file>"):

| File | Content | |------|---------| | scoring-rubric.md | Detailed dimension scoring thresholds | | recommendation-format.md | Priority assignment and effort estimation | | output-format.md | JSON report schema and example |

  • See platform-upgrade-knowledge/references/scoring-rubric.md for additional scoring details
  • See platform-upgrade-knowledge/references/compatibility-matrix.md for version compatibility tracking