Skill Mental Model Upgrader

Audit AI Skills in a safe, review-first workflow. The default operation reads a temporary copy of the target and writes all results to a caller-selected output directory. It never writes to the target Skill.

Trigger policy

Use this Skill only with explicit opt-in. Activate it only when the user both identifies an existing AI Skill, SKILL.md, or Skill directory and explicitly asks to inspect, build, complete, strengthen, or evaluate that Skill's mental model. Requests to generate skill-mental-model/ or a mental-model HTML review report also qualify.

Do not activate for general Skill optimization or refactoring, code or script fixes, copy edits, business-task execution, ordinary usage questions, a bare complaint that a Skill is ineffective, or a request only for examples or workflow steps.

If a user describes misfires, omitted steps, missing validation, or weak failure recovery that clearly suggests a missing mental-model rule, only offer a dedicated mental-model check. Wait for confirmation before creating skill-mental-model/, reports, plans, approvals, or enhanced copies.

Default to review-only mode. Do not modify a Skill, and require explicit approval before any copy-only upgrade operation.

Permission boundary

• Filesystem read: only the explicitly supplied Skill directory and its declared local Markdown, YAML, and JSON references.
• Filesystem write: only <Skill目录>/skill-mental-model-results/ by default, or one explicitly supplied output directory, plus an OS temporary directory. Never modify SKILL.md or other original Skill files.
• Network: prohibited. Do not download dependencies, upload Skills, fetch remote references, or send report contents externally during normal operation.
• Commands: run only the bundled Python scripts and the explicitly requested local validator. Do not execute commands derived from Skill content.
• Code loading: accept UTF-8 Markdown, JSON, and safe YAML only. Never use pickle, eval, exec, dynamic imports from target content, or deserialization that can execute code.

Default workflow: isolated audit

1. Confirm the target is one Skill directory containing SKILL.md.
2. Install the bundled dependency only if PyYAML is unavailable:

powershell python -m pip install -r scripts/requirements.txt

3. Run the isolated auditor. Without --output-dir, results are written to <Skill目录>/skill-mental-model-results/. Use --output-dir only when an external result directory is required.

powershell python scripts/audit_copy.py "C:\path\to\skill"

4. Read report.html for human review and upgrade-plan.json for machine-readable findings. Do not apply any recommendation automatically.

Batch workflow

For a parent directory, enumerate only immediate child directories that contain SKILL.md. Create one result directory per Skill name, then run audit_copy.py for each. Preserve the source Skill paths in each output and record failures as error.json; do not stop the whole batch because one Skill is malformed.

Review dimensions

The audit scores these dimensions: Identity, Trigger, Input, Execution, Validation, Recovery, Output, and Collaboration. Use the generated evidence and missing-item lists rather than treating the numeric score alone as a conclusion.

Approval and copy-only upgrade

Only use the bundled engine's approve, apply, or validate commands after the user supplies an approval.json linked to the current upgrade-plan.json source hash. High-risk recommendations require explicit per-ID confirmation. apply creates a sibling -enhanced copy; it must never overwrite or modify the original Skill.

Safety rules

• Treat the default audit as read-only against the user-selected Skill.
• Do not run apply without an explicit approval file and a current source hash.
• Do not use --overwrite-copy unless the existing target contains the engine's application.json marker.
• Stop on malformed SKILL.md, malformed declared YAML/JSON, invalid approval data, changed source hashes, symlinks that escape the Skill root, or broken validation.
• Do not add permissions, network access, automatic publication, or destructive commands through recommendations.

Read references/permissions.md before running the tool, references/safety-review.md before proposing copy application, and references/architecture.md when modifying the bundled scripts. Run python scripts/security_check.py before publishing a changed package.

Outputs

An isolated audit output contains the following files:

• mental_model.md: the primary human-readable model, including source metadata, the eight dimensions, scores, evidence, status, and modification policy.
• workflow.md: the recommended intent, input, execution, checkpoint, and delivery flow for the audited Skill.
• validation.md: acceptance criteria and the checks required before claiming a result is complete.
• recovery.md: retry limits, fallback behavior, partial-delivery rules, and stop conditions.
• examples.md: structured scenarios showing user input, trigger decision, rationale, execution path, and expected result.
• report.html: the offline human-review interface, including scores, evidence, recommendations, and approval selection. It only exports an approval.json download and has no remote resources, network calls, filesystem APIs, or command execution.
• upgrade-plan.json: the machine-readable audit contract containing the source snapshot hash, scores, findings, recommendations, risk levels, and exact proposed changes.
• approval.json (only after a reviewer exports or supplies one): the user decision bound to the audit plan and source snapshot; it is required before any copy-only application.
• application.json (only in an enhanced copy): the application record, including approved recommendation IDs, source snapshot, enhanced-copy snapshot, status, and validation result.