skill-self-check

Files (30)

• CHECKLIST.md
• REPORT-TEMPLATE.md
• SKILL.md
• before-after.md · examples/
• SKILL.md · examples/fixtures/bad-commit-helper/
• role-contract.example.json · examples/
• role-prompt-behavior.example.json · examples/
• smoke-report-before-business.md · examples/
• smoke-report-before.md · examples/
• workflow-prompts.example.json · examples/
• deep-qualitative-audit.md · references/
• fix-templates.md · references/
• fix-verification.md · references/
• full-static-audit.md · references/
• gap-questions.md · references/
• pdca-smart.md · references/
• plain-language-response.md · references/
• prompt-optimization.md · references/
• role-archetypes.md · references/
• role-contract-audit.md · references/
• role-contract.json · references/
• role-prompt-behavior-eval.md · references/
• role-prompt-review.md · references/
• workflow-prompt-audit.md · references/
• hard_gates.py · scripts/
• role_contract_audit.py · scripts/
• role_prompt_behavior_check.py · scripts/
• run_full_audit.py · scripts/
• verify_fix.py · scripts/
• workflow_prompt_audit.py · scripts/

SKILL.md (first lines)

# Skill Self-Check

Run a fast static review with deterministic gate status and ranked fixes.
Full checks: [CHECKLIST.md](CHECKLIST.md).

Workflow prompt audit: N/A — one agent instruction context; no separate model calls.

## Role contract

- **Role:** Skill audit verifier
- **Purpose:** Report script gates and verify approved fixes.
- **Responsibilities:** Run the standard static checkers before reporting.
- **Responsibilities:** Separate model advice from script results.
- **Out of scope:** Do not create Skills, run behavior tests, or make unapproved edits.
- **Decision authority:** Report only the script gate_verdict.
- **Decision authority:** Verify approved fixes against a baseline.
- **Handoff to:** Send business-readiness gaps to agent-work-readiness.
- **Handoff to:** Send external-action safety to skill-ship-safety.

Machine contract: [references/role-contract.json](references/role-contract.json).

<authority_contract>

- [hard_gates.py](scripts/hard_gates.py) owns package health, `gate_verdict`,
  script findings, severity, and exit code.
- [verify_fix.py](scripts/verify_fix.py) owns saved-baseline verification.
- Script scores are informational only.
- Model review cannot change script status, counts, severity, or exit code.
- Edit the target only after explicit user authorization.

</authority_contract>

## When to use

- Review an existing Skill before controlled use, installation, or sharing.
- Diagnose deterministic blockers and provide paste-ready fixes.
- Recheck user-authorized repairs against a saved baseline.

## When NOT to use

- Create a Skill from scratch.
- Run behavioral evaluations or multi-agent smoke tests.
- Generate profiles, presentations, or visual scorecards.

## Check axes

[CHECKLIST.md](CHECKLIST.md) owns four result families:

- **Gate:** package health and `gate_verdict` (script; blocking);
- **Diagnostics:** structure, contract, support, token, and loops (script);
- **Qualitative:** Predictability, Anatomy, PDCA, SMART (explicit advisory route);
- **Role/Prompt:** workflow applicability and role contract (standard static
  status), plus explicit model-owned optimization.

## Inputs

1. Locate the target skill directory (must contain `SKILL.md`).
2. Prefer an explicit path from the user.
3. If missing: ask once, or use the skill they just created/opened in this conversation.

**Completion criterion:** You know the absolute path to the target skill directory.

## Process

### Standard audit — three static statuses

For every general audit, review, or self-check, run all three bundled checkers:

```bash
python scripts/hard_gates.py /absolute/path/to/target-skill --pretty
python scripts/workflow_prompt_audit.py /absolute/path/to/target-skill --pretty
python scripts/role_contract_audit.py /absolute/path/to/target-skill --pretty
```

`hard_gates.py` alone owns `gate_verdict`; workflow and role statuses remain
separate. Run only `hard_gates.py` when the user explicitly asks for a fast or
gate-only check.

For multi-Skill packs, pass `--repo-root /absolute/repository` and preserve it
during [fix verification](references/fix-verification.md). Escaping paths stay Critical.

If fixes may follow, save the same run as a baseline outside the target and
source repository:

```bash
python scripts/hard_gates.py /absolute/path/to/target-skill \
  --out-json /private/path/baseline.json --pretty
```

- Parse stdout JSON; stderr is a human summary.
- Read `package_health`, `gate_verdict`, `gate_reasons`, and `findings` first.
- Exit 1 means the gate failed; report fixes normally.
- Scores/metrics are informational. Show maturity only for an assessable package.

**Completion criterion:** All three JSON reports are parsed; core gate reasons,
workflow applicability, and role mode/status are available.

### Rank and explain deterministic findings

Map script `findings` into [plain-language response](references/plain-language-response.md)
without changing any Critical or creating a second audit.

For mechanical `PKG.*`/`EFF.*`, write the rewrite from
[fix-templates.md](references/fix-templates.md) instead of asking.

<output_contract>

1. Gate verdict plus workflow Prompt and role-contract statuses.
2. Every script Critical, each with 问题 → 为什么 → 可直接采用的建议改法.
3. At most three highest-priority Should fix findings.
4. One next action: 「按意见改」, or request a named advisory/full route.

</output_contract>

## Selected routes

Load only selected references. A request that names Prompt, context, workflow,
role, enhancement, or optimization selects that route. “Did you review X?” also
means run the read-only X route now unless the user explicitly asks for status

From xenos2025/Skill-Self-Check, MIT.

More from xenos2025/Skill-Self-Check