/skill

Skill Stocktake

Review Claude skills and commands with /skill-stocktake.

Use one of two modes:

• Quick scan: Review files that changed since the last run.
• Full review: Review every found skill.

Scope

Use the folder where the command was started as {cwd}.

Scan these paths:

At the start, list each path and say if it was found.

Do not follow links that lead outside these paths. Skip unreadable files and report them. If the same skill name is in both paths, treat them as two files. Show the full path for each one.

Only review skill files and command files found by the scan script. Ignore cache folders, build output, hidden backup files, and files inside the stocktake result folder.

Review a project

Run the command from the project root:

cd ~/path/to/my-project
/skill-stocktake

If {cwd}/.claude/skills/ does not exist, review only global files.

Modes

Result file:

~/.claude/skills/skill-stocktake/results.json

If the result file cannot be read or parsed, report the problem and run a full review. Do not erase the bad file without user approval.

Quick scan

A quick scan checks files that changed since the last completed review.

1. Read results.json.
2. Run:

bash ~/.claude/skills/skill-stocktake/scripts/quick-diff.sh \
  ~/.claude/skills/skill-stocktake/results.json

The script finds $PWD/.claude/skills on its own. Pass a project path only when auto-find does not work.

3. Check the script exit code before using its output.
4. If the output is [], report:

No skill files changed since the last review.

Then stop.

5. Review each added, changed, moved, or removed file.
6. Use the same rules as the full review.
7. Keep old results only for files that still exist and did not change.
8. Do not keep a result when its file was removed.
9. Show only changed results in the report.
10. Save the full merged result set, not only the changed rows:

bash ~/.claude/skills/skill-stocktake/scripts/save-results.sh \
  ~/.claude/skills/skill-stocktake/results.json <<< "$EVAL_RESULTS"

If a file time changed but its content did not, keep the old verdict. Restate the useful reason. Do not write only Unchanged.

If either script fails, report its exit code and error text. Do not save partial or empty data as a completed review.

Full review

Phase 1: Build the list

Run:

bash ~/.claude/skills/skill-stocktake/scripts/scan.sh

The script lists files, reads frontmatter, and records file change times in UTC. It finds $PWD/.claude/skills on its own.

Check the exit code. If the scan fails, stop and report the error. If no skill files are found, report that fact and do not start review agents.

Show the paths that were checked:

Scanning:
  Found: ~/.claude/skills/      (17 files)
  Missing: {cwd}/.claude/skills/

Then show this table:

Use Unknown when use data is not available. Do not guess use counts.

Phase 2: Review quality

Split the list into batches of about 20 files. Run the batches one at a time. This keeps each review small and easy to check.

Give each general agent the full file paths, the review rules, and any local files needed to check overlap.

Agent(
  subagent_type="general-purpose",
  prompt="
Read and review each file in this list.

[INVENTORY]

Use these rules:

[CHECKLIST]

Return one JSON object per file:
{
  \"name\": \"skill-name\",
  \"path\": \"/full/path/to/SKILL.md\",
  \"verdict\": \"Keep\" | \"Improve\" | \"Update\" | \"Retire\" | \"Merge into [X]\",
  \"reason\": \"Clear facts that support the verdict\"
}
"
)

After each batch, save valid results with:

"status": "in_progress"

Do not mark the review complete until every found file has one valid result.

If one result is missing or has bad JSON, retry only that file. If it still fails, record the file as not reviewed and keep the run in progress.

When all files are done, set:

"status": "completed"

Then continue to Phase 3.

Resume an unfinished review

If results.json has status: "in_progress":

1. Check that saved paths still exist.
2. Check whether saved files changed after their saved mtime.
3. Keep valid results for files that did not change.
4. Review changed files again.
5. Start with the first file that has no valid result.
6. Add new files and drop removed files from the active list.

Review checklist

Check each file for:

• Copy of content from another skill.
• Copy of rules already in MEMORY.md or CLAUDE.md.
• Clear steps that a user or agent can follow.
• A name, trigger, and body that match.
• Commands, flags, paths, and APIs that match the local tools.
• Value that is not already given by another local file.
• Use data, if valid use data exists.
• Broken links or missing local files.
• Unsafe steps, such as deleting files without approval.
• Missing steps for errors, empty input, bad data, or a stopped run.

Do not make any web calls. Check facts with installed help text, local docs, local source files, and tool version output. If a fact cannot be checked, say so in the reason. Do not guess.

Verdicts

Use judgment. Do not make a number score.

Judge these points:

• Action: Can a person follow the steps now?
• Fit: Do the name, trigger, and content match?
• Unique value: Does the file add something useful?
• Current state: Do its tool facts match local proof?
• Safety: Does it guard risky file changes?
• Edge cases: Does it handle missing files, bad data, and failed commands?

Reason rules

Each reason must stand on its own. Name the facts that led to the verdict.

For Retire, include:

1. The exact flaw.
2. The skill or rule that meets the same need.
3. Any known effect of removal.

Bad:

{"reason":"Replaced"}

Good:

{
  "reason":"This file repeats all steps from continuous-learning-v2 and adds no new case. No local file links to it. Retire it after user approval."
}

For Merge into [X], name the target and what to move.

Bad:

{"reason":"Overlaps with X"}

Good:

{
  "reason":"The upload steps match media-tools. Move the retry note and file-size check into media-tools, then retire this file after approval."
}

For Improve, name the section and the needed edit.

Bad:

{"reason":"Too long"}

Good:

{
  "reason":"The Framework Comparison section repeats ai-era-architecture-principles. Remove that section and keep the short setup steps."
}

For Update, name the old fact and the local proof for the new fact.

For Keep, state the skill's useful and unique value. If only the file time changed, say that the content matched the saved copy and restate the old proof.

Phase 3: Show the results

Show this table:

Also list:

• Files that could not be read.
• Files that could not be reviewed.
• Facts that could not be checked.
• Name clashes between global and project skills.

Phase 4: Plan changes

Do not edit, move, archive, merge, or delete skill files during the review.

For each Retire or Merge into [X] result, show:

• The exact problem.
• The skill or rule that covers the same need.
• The target file and text to move, for a merge.
• Skills, rules, or work steps that may break.
• Any missing proof about the effect.

Ask for clear user approval before any archive, move, merge, or delete action. Approval for one file does not cover other files.

For each Improve result, show:

• What to change.
• Where to change it.
• Why the change helps.
• A rough size goal only when it is useful.

For each Update result, show:

• The old text.
• The checked local source.
• The new text to use.

Check the line count of each found MEMORY.md. If one is over 100 lines, suggest a shorter version. Do not change it without approval.

Result file

Store results at:

~/.claude/skills/skill-stocktake/results.json

Set evaluated_at to the real UTC time when the review ends:

date -u +%Y-%m-%dT%H:%M:%SZ

Never use a made-up time such as T00:00:00Z.

Use this shape:

{
  "evaluated_at": "2026-02-21T10:00:00Z",
  "mode": "full",
  "batch_progress": {
    "total": 80,
    "evaluated": 80,
    "status": "completed"
  },
  "skills": {
    "skill-name": {
      "path": "~/.claude/skills/skill-name/SKILL.md",
      "verdict": "Keep",
      "reason": "Gives clear setup and retry steps that no other local skill has.",
      "mtime": "2026-01-15T08:30:00Z"
    }
  }
}

The evaluated count must match the number of valid skill results. The total count must match the current scan. Use a path-based key when two files have the same skill name.

Write the result file in a safe way. First write valid JSON to a new file. Check that it can be parsed. Then replace the old result file. Keep the old file if the new data is bad.

Example

A user runs:

cd ~/work/shop-app
/skill-stocktake full

The scan finds 18 global skills and 2 project skills. The review runs one batch of 20 files. It finds:

• api-check: Keep, because it has clear local API test steps.
• old-upload: Merge into media-tools, because both have the same upload steps.
• deploy-help: Update, because its flag is not shown by the installed tool's help text.

The final report explains each result. It does not change any files. It asks the user before merging old-upload into media-tools.

Rules

• Review all sources in the same way. Do not favor ECC, local, or generated files.
• Do not send file text, names, or results to an outside service.
• Do not add tracking, logs about user behavior, analytics, or telemetry.
• Never archive, move, merge, or delete a file without clear user approval.
• Never hide failed checks.
• Never guess missing use data or tool facts.