# Skills 2 0 Upgrade

> Use when upgrading Claude Code skills to Skills 2.0 compliance, when diagnosing skill health scores, when frontmatter is missing or malformed, when skills exceed 500-line limit, when skill directories lack SKILL.md structure, or when compliance score needs improvement

- **Type:** Skill
- **Install:** `agentstack add skill-treylom-skills-2-0-upgrade-skills-2-0-upgrade`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [treylom](https://agentstack.voostack.com/s/treylom)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [treylom](https://github.com/treylom)
- **Source:** https://github.com/treylom/skills-2.0-upgrade/tree/master/skills/skills-2.0-upgrade

## Install

```sh
agentstack add skill-treylom-skills-2-0-upgrade-skills-2-0-upgrade
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Skills 2.0 Upgrade

## Overview

Skills 2.0 is Anthropic's 2026 skill framework built on Progressive Disclosure:
1. **Frontmatter** — fast routing and discovery
2. **SKILL.md** — working guide (500 lines)
- `orphan directory` (skill folder without `SKILL.md`)
- `broken reference` (invalid `references/` links)
- description missing `Use when...` pattern
- low or declining compliance score

Do not use for normal feature work inside a skill.

## Upgrade Workflow — Phase-by-Phase Guide

Start by selecting which skills to upgrade, then diagnose and proceed phase by phase.

### Step 0: Select target (always start here)

Ask the user what to upgrade before scanning anything:

```
What would you like to upgrade?
  1. A specific skill — enter the skill name
  2. Multiple skills — enter comma-separated names
  3. All skills — scan the entire directory
```

Resolve skill names to file paths:
- `my-skill` → `$SKILLS_DIR/my-skill.md` or `$SKILLS_DIR/my-skill/SKILL.md`
- If not found, list available skills and ask the user to pick

All subsequent steps operate only on the selected scope.

### Step 1: Diagnose

```bash
scripts/diagnose.sh  [--json|--verbose]
```

Present the user with:
- per-skill score and failed checks (if specific skills selected)
- overall compliance score and issue breakdown (if all skills)
- top impactful issues

Then explain the upgrade path:

```
Your skills score X%. Here's what each upgrade phase would improve:

| Phase | Fixes | Expected Impact | Automation |
|-------|-------|-----------------|------------|
| P1-P2 | Frontmatter + name | +10-16%p | Fully automatic |
| P3    | Description "Use when..." | +8-16%p | Semi-auto (batch) |
| P4    | Invocation control | +1-3%p | Semi-auto (confirm) |
| P5+   | File splitting + structure | +2-6%p | Manual (Opus) |

Which phase would you like to run? (P1-P2 / P1-P3 / P1-P4 / all)
```

### Step 2: Execute chosen phases

Run `scripts/backup.sh ` before any changes.

**P1-P2 (Automatic):**
Run `scripts/batch-p1p2p3.py  --dry-run` to preview, then apply.
- P1 adds missing frontmatter with auto-generated name and description
- P2 normalizes name fields to kebab-case
- No user confirmation needed — deterministic pattern matching

**P3 (Semi-automatic):**
Run `scripts/batch-p1p2p3.py ` which also handles P3.
- Transforms existing descriptions to "Use when..." pattern
- Preserves Korean text, proper nouns, and acronyms
- Show the user a sample of changes before applying

**P4 (Confirm with user):**
Identify reference-type skills using heuristics (name contains guide/reference/spec/examples/templates/schema/collection/strategies/checklist).
- Present candidate list to user
- Add `disable-model-invocation: true` to confirmed files

### Step 3: Re-diagnose and report

Run diagnosis again and show before/after comparison:

```
Compliance improved: X% → Y% (+Z%p)

| Priority | Before | After | Fixed |
|----------|--------|-------|-------|
| P1       | N      | 0     | N     |
| P2       | N      | 0     | N     |
| P3       | N      | M     | N-M   |
| P4       | N      | M     | N-M   |
| P5+      | N      | N     | (manual) |
```

### Step 4: Guide beyond P4 (final optimization)

After P1-P4, explain remaining issues and how to resolve them:

```
Remaining issues for 100% compliance:

1. Body >500 lines (P5) — N skills
   → Requires content understanding to split into SKILL.md + references/
   → Recommended: Opus model with high effort
   → Run: /skills-upgrade --split  (interactive, one at a time)

2. Broken references — N skills
   → Referenced files in references/ don't exist
   → Fix: create the missing files or remove the broken links

3. Imperative form — N skills
   → Body uses "you should" instead of direct commands ("Run", "Check")
   → Fix: rewrite advisory phrasing to imperative

4. Orphan directories — N skills
   → Skill folders without SKILL.md entry point
   → Fix: add SKILL.md or restructure into parent skill

Would you like to start P5 splitting for the longest skills?
```

For P5 splitting, guide the user through each skill:
1. Read the full content
2. Identify logical sections that can become reference files
3. Propose a split plan (what stays in SKILL.md, what moves to references/)
4. Add progressive disclosure pointers linking to the new reference files
5. Execute after user approval

## Quick Reference

| # | Check | Weight |
|---|-------|--------|
| 1 | Frontmatter exists | 20% |
| 2 | `name:` field valid | 8% |
| 3 | `description:` field exists | 10% |
| 4 | Description "Use when..." | 5% |
| 5 | Description third-person | 3% |
| 6 | Body ≤500 lines | 15% |
| 7 | Directory structure | 10% |
| 8 | `disable-model-invocation` | 8% |
| 9 | No orphan directories | 5% |
| 10 | No broken references | 5% |
| 11 | Progressive Disclosure | 5% |
| 12 | Imperative form | 6% |

See `references/diagnostic-criteria.md` for scoring details.

## Model Guide

| Task | Model | Effort |
|------|-------|--------|
| Diagnosis | Any (bash) | N/A |
| P1-P3 batch fix | Sonnet | medium |
| P4 invocation control | Sonnet | medium |
| P5 file splitting | Opus | high |
| Full upgrade | Opus | high |

## Real-World Impact

151 skills, measured results:

| Phase | Compliance | Gain |
|-------|-----------|------|
| Baseline | 62% | — |
| After P1-P2 | 78% | +16%p |
| After P1-P3 | 94.3% | +16.3%p |
| After P1-P4 (est.) | ~97% | +2.7%p |
| After P5+ (est.) | ~100% | +3%p |

## Pre-Deployment Security Scan

Before publishing skills or pushing to GitHub, run the security scanner:

```bash
scripts/diagnose.sh  --security
scripts/diagnose.sh  --security --json
```

Detects 13 patterns across 3 severity levels:

| Severity | What it catches |
|----------|----------------|
| Critical | API keys (`sk-`, `ntn_`, `ghp_`), private key blocks |
| High | Bearer tokens, API key/secret assignments, password assignments |
| Medium | Hardcoded user paths (`/home/user`, `/mnt/c/Users`, `C:\Users`) |

False positives can occur when scanning code that contains detection patterns as string literals (e.g. the scanner's own source code). Review each finding before acting.

## Common Mistakes

- Editing without running diagnosis first
- Skipping backup before upgrade
- Putting workflow summary in `description` instead of triggers
- Skipping P3 even though it has the highest aggregate impact
- Running P5 with Sonnet instead of Opus (content understanding needed)
- Forgetting to re-diagnose after fixes
- Deploying without running `--security` scan first

See `references/upgrade-actions.md` for detailed P1-P7 procedures.
See `references/trigger-optimization.md` for description optimization strategy.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [treylom](https://github.com/treylom)
- **Source:** [treylom/skills-2.0-upgrade](https://github.com/treylom/skills-2.0-upgrade)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-treylom-skills-2-0-upgrade-skills-2-0-upgrade
- Seller: https://agentstack.voostack.com/s/treylom
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.