skill-lint

Skill Lint

This skill is responsible for design pre-checks before Skill creation and quality acceptance after creation: reviewing whether a Skill is structurally compliant, documentation-consistent, releasable, evaluable, and controllable in terms of security risk, determining whether it genuinely carries a business process, and checking whether a "complete" conclusion is supported by candidate-bound evidence and multiple rounds of real artifacts.

This skill does not replace the primary creator or domain validator. When creating or significantly modifying a Skill, use it to first review the Harness design, then implement with the creation tool, and after completion return to this skill for candidate-bound acceptance.

Working Principles

• Look at hard problems first, then optimization problems.
• Perform static review first, then judge the depth of the business flow.
• Locate the review unit first, then review the target Skill directory and the explicitly provided context.
• Do not equate format compliance with passing task effectiveness.
• Do not trust the producer's self-reported PASS; formal acceptance must be bound to the current candidate, current rules, and actual logs.
• Do not treat "having a checker" as "complete coverage"; every hard constraint must be traced to an appropriate modality, the correct artifact stage, and a regression test case.
• Do not compare whole-file hashes of natural language output; compare only the key coverage sets and observable invariants declared in the contract.
• Objective defects fail-closed; semantic quality retains human judgment and is not disguised as all-purpose automation.
• Only review the coverage, modality, and evidence of domain checkers; do not misrepresent insufficient evidence as having discovered specific domain algorithm errors.
• Known false negatives must have a minimal violating counterexample, and known false positives must have a legitimate approximate positive example; both are defined by the target Skill's domain checker.
• Mark capabilities that cannot be confirmed as "not mentioned/to be supplemented".

Input

Reviewing requires at least:

• Target path or repository address: can be a single Skill directory, monorepo root directory, GitHub repository, or a set of prompts to be transformed
• Review purpose: design pre-check before creation, acceptance before release, transformation evaluation, review of others' Skills, regression check, etc.

Optional input:

• Special preferences or project rules given by the user
• Local review configuration file, such as config/review-profile.local.yaml
• List of issues requiring focused attention

If you need to configure personal or project release metadata policy, first copy config/review-profile.example.yaml to config/review-profile.local.yaml, then fill in local values. Personal preferences are used only as local context, are not written into public files, and are not copied into review reports unless the user explicitly requests disclosure.

Review process

0. Select mode

• Creation pre-check: the target has not yet been implemented or will undergo significant transformation. First read references/harness-reliability-standards.md, produce a seven-layer Harness design, Hard Fail, and at least one escape counterexample; do not directly expand the prompt.
• Quick review: check third-party Skills, drafts, or local issues. You may perform only static and semantic review, but the conclusion must state NOT_VERIFIED, and must not claim that functionality has been accepted.
• Legacy stability review: check older versions, multi-dimensional review, visual production, or Skills with repeated omissions. First read references/instruction-stability-standards.md and run static assess; when constraint tracking contracts or multi-round evidence are missing, mark NOT_VERIFIED, and do not infer stability from a single successful execution.
• Formal acceptance: before release, delivery, or claiming "stably complete", in addition to all review modules, the candidate-bound evidence gate must also be run. Dynamic execution is only used for user-confirmed self-owned/trusted candidates; unknown third-party candidates stop by default at NOT_VERIFIED, unless the user explicitly authorizes it and an isolated environment is used.

After creation preflight is complete, implementation is carried out by the user-specified creation tool or implementer; this skill re-enters formal acceptance after implementation is complete. This moves the reliability philosophy earlier while keeping the reviewer and the producer from merging into the same responsibility.

1. Confirm scope

First read references/repository-skill-discovery-standards.md, and determine which category the input target belongs to:

• Single Skill directory: the target directory itself contains SKILL.md
• monorepo / Skill collection: the repository root is only a container, and multiple subdirectories inside are the smallest Skill units
• Loose prompt collection: there is no standard SKILL.md unit, but there is Markdown with name / description frontmatter or a README index
• Ordinary repository: there is not enough evidence to indicate it contains Skills

Do not judge the entire repository as unqualified merely because the repository root lacks SKILL.md . A missing SKILL.md at the root should only be treated as a serious issue when the user explicitly specifies that the root is a single Skill, or when the repository declares itself to be a loadable Skill root.

After candidate units are discovered, first list:

• Confirmed Skill units: the directory contains SKILL.md
• Non-standard but migratable Skill-like documents: a single Markdown file with name / description frontmatter, or a README explicitly called a skill
• Repository-level governance files: README, LICENSE, CHANGELOG, Marketplace, contribution instructions

If there are many candidate units, first review according to the scope specified by the user; when the user has not specified one, prioritize reviewing confirmed Skill units and sample Skill-like documents, and state the sampling scope in the report.

2. Scan files

For each confirmed or selected candidate unit, list the files and focus on checking:

• SKILL.md
• CHANGELOG.md
• LICENSE.txt
• config/*.example.*
• references/*.md
• scripts/*
• assets/*
• templates/*
• archive/.gitkeep

If within a Skill unit there appears .env, real secrets,__pycache__/、docs/、test/ , or other content that should not be included in a release, record it by severity. The repository root's README, docs, LICENSE, and CHANGELOG may be monorepo governance files and should not be misjudged according to a single Skill directory structure.

3. Modular rule review

First read references/skill-standards.md as the review index, then read the corresponding modules according to the issue type. Do not mix all detailed rules into one report logic at once.

Default modules:

• repository-skill-discovery-standards.md: repository type, monorepo, smallest Skill unit, and candidate document discovery
• structure-standards.md: directory structure, file reachability, references naming
• frontmatter-metadata-policy.md: layering of general fields and release fields
• trigger-description-standards.md：name and description trigger boundaries
• configuration-privacy-standards.md: configuration templates, local configuration isolation, de-specification of public content
• security-assessment-standards.md: dangerous execution, sensitive access, data exfiltration, credentials, dependencies, MCP, and prompt security
• publishing-standards.md: LICENSE, CHANGELOG, version, README / marketplace synchronization
• workflow-output-standards.md: SKILL.md body, dependencies, scripts, output, and orchestratability
• business-flow-rubric.md: business flow depth, Hard Fail, and foundations for evaluability
• harness-reliability-standards.md: Seven-layer Harness, independent verification, candidate-bound evidence, fault injection, and closed loop
• instruction-stability-standards.md: Constraint tracking, verification modality, artifact stages, multi-round coverage, and drift determination
• reporting-standards.md: Issue grading and report structure

LICENSE.txt、version, README, and Marketplace belong to release governance, not to ordinary directory structure hard requirements. When reviewing private or third-party ordinary Skills, only judge by the release module when the user provides a release target or project rules.

4. Security Assessment

Read references/security-assessment-standards.md, and perform a security risk assessment on the Skill units included in the review.

First run the deterministic static security scan(corresponding to NVIDIA SkillSpector's vulnerability patterns):

# 单个 Skill
python3 scripts/security_scan.py audit --candidate-root /path/to/skill

# Skill 集合 / monorepo（递归发现所有含 SKILL.md 的最小单元）
python3 scripts/security_scan.py batch --root /path/to/skills

# 联网查询 OSV 已知漏洞（默认离线只做版本 pin 检查）
python3 scripts/security_scan.py audit --candidate-root /path/to/skill --online

The scanner outputs structured JSON containing files, line numbers, capability signals, severity, confidence, and remediation suggestions; when critical/high findings exist, the exit code is 1 (FAIL), and when SKILL.md is not found, the exit code is 2. Coverage: dangerous execution (subprocess/os.system/eval/exec/dynamic import), network exfiltration, environment variable/sensitive file access, runtime auto-installation, unpinned dependencies and known CVEs, hardcoded credentials, prompt injection, taint flow (env/argv/input → subprocess), filesystem enumeration, hidden Unicode characters, MCP wildcard permissions, as well as "capability exists but documentation does not disclose/declare permissions" (Missing User Warnings / MCP Least Privilege / Context-Inappropriate Capability) and documentation-level scope creep (commit skills guiding release/modifying allowlist and other undisclosed high-risk actions).

Key checks:

• SKILL.md and references contain prompt injection, bypassing security restrictions, hidden execution, sensitive data collection, or deceptive descriptions
• scripts contain dangerous command execution, download and execute, privilege escalation, unbounded deletion, sensitive file access, data exfiltration, dynamic import, or obfuscation
• config/example contain real credentials, real endpoints, real webhooks, or local sensitive paths
• dependencies, install hooks, MCP, network requests, and external tool permissions have purpose descriptions, scope limits, and user confirmation
• During GitHub repository review, whether the commit history has had sensitive information leaks, abnormal delete-and-re-add, or commits inconsistent with the Skill's behavior

Security assessment is not equivalent to a full penetration test. For scanner hits, determine false positives in context; however, for issues involving credential leaks, download and execute, privilege escalation, persistence, unconfirmed data exfiltration, hidden prompt instructions, etc., treat them as serious issues by default.

5. In-Depth Business Flow Review

Use references/business-flow-rubric.md to check:

• Trigger: whether it clearly states when to trigger and when not to trigger
• Intake: whether it identifies input gaps and specifies how to ask follow-up questions
• Reasoning: whether it distinguishes facts, induction, judgment, and basis
• Output: whether it defines the output structure, acceptance criteria, and follow-up actions
• Safety: whether it controls privacy, overpromising, and high-risk scenarios

By default, use medium strictness: Hard Fail is a hard indicator, and the five-layer assessment objects are soft indicators.

6. Harness Reliability Review

Pre-check creation, major overhauls, and formal acceptance must read references/harness-reliability-standards.md, and check layer by layer Contract / Producer / Verifier / Evidence Binding / Fault Injection / Closure / Composition. For legacy versions, multi-dimensional review, visual production, or when user feedback shows "repeated omissions/production drift," you must also read references/instruction-stability-standards.md。

First run a concrete failure review that does not execute candidate code. Single Skill:

python3 scripts/harness_failure_audit.py audit \
  --candidate-root /path/to/skill

Skill collection or monorepo:

python3 scripts/harness_failure_audit.py batch \
  --root /path/to/skills

This reviewer recursively discovers the smallest units containing SKILL.md and outputs stable JSON with files, line numbers, evidence, impact, and remediation suggestions; hard findings return 1, and out-of-scope or zero Skills in the collection returns 2. Rule IDs and boundaries are in references/harness-reliability-standards.md. By default it performs only static review, without execution, installation, or network access.

Legacy structural stability review:

python3 scripts/instruction_stability_gate.py assess \
  --candidate-root /path/to/skill

When config/instruction-stability-contract.json is missing,assess returns exit code 2 and INSTRUCTION_STABILITY_NOT_VERIFIED, while also giving ISG structural findings and HFA/HRA concrete implementation findings. Visual/geometric semantics are identified only from the normative context of SKILL.md and references/**/*.md ; historical discussion in TASKS/DECISIONS/CHANGELOG does not trigger visual modality. This mode does not execute candidate code, making it suitable for legacy and unknown third-party Skills.

ISG-002 lists the normative sources and line numbers that trigger visual/geometric requirements, but it only proves that the candidate lacks domain validation evidence for the appropriate modality. Do not use it to claim that overlap, cropping, or other specific business errors have already been detected; the target Skill should be required to provide its own checker, minimal violating counterexamples, and valid near-positive examples, which are then recomputed by the formal gate.

Before claiming "stable instruction following" or "no missed items across multiple rounds," the target Skill must provide a constraint-tracking contract. Each hard constraint uses a unique <!-- skill-lint:constraint CONSTRAINT-ID --> anchor in the authoritative source; the candidate-external evaluator-signed baseline must be consistent with all anchors, normative lines, contracts, and the current candidate hash. First obtain reproducible Harness review evidence for the current candidate, then independently execute at least three rounds with the same input/configuration; each round must retain a unique execution nonce, an evaluator-signed producer log, and the real artifacts in an independent directory. Each hard constraint must also have candidate-external evaluator-signed held-out positive and negative examples. After completing the static security review, disclosing the checker, and obtaining user confirmation that the candidate is their own/trusted code, run:

python3 scripts/instruction_stability_gate.py verify \
  --candidate-root /path/to/skill \
  --evaluator-public-key /path/to/review/evaluator-public.pem \
  --requirements-baseline /path/to/review/requirements-baseline.json \
  --harness-evidence /path/to/review/harness-review.json \
  --held-out-cases /path/to/review/held-out-cases.json \
  --held-out-root /path/to/review/held-out \
  --run-evidence /path/to/review/runs.json \
  --runs-root /path/to/review/runs \
  --receipt /path/to/review/instruction-stability-receipt-draft.json \
  --confirm-trusted-candidate

This gate is fixed to use the current trusted skill-lint to recompute HARNESS_REVIEW_VERIFIED, and then reruns the active checker round by round. It requires each hard constraint to be precisely mapped to an explicit source anchor, automatically discovered and signed enumerated requirements sources/exclusions, checker, correct validation modality, correct artifact stage, typed/conditional/thresholded measurement, signed hidden positive and negative examples, and known historical regressions; the contract omitting normative lines, invalid signatures, reused paths across three rounds, replay of old candidate/old producer logs, negative cases failing due to other constraints, underreporting a constraint id, the checker modifying artifacts, or key observable drift will all block. Public, hidden, and real run artifacts all use the same kind of random temporary paths to avoid the checker branching by sample category.

verify only generates the INSTRUCTION_STABILITY_EVIDENCE_READY draft. The evaluator must run sign-evidence --private-key ...with the Ed25519 private key in an isolated environment that does not execute candidate code, and then use verify-receipt , which holds only the candidate-external public key, to re-verify all bindings; only if the latter step outputs INSTRUCTION_STABILITY_VERIFIED can stability be declared. The private key must not appear in the process tree, environment, or readable workspace of the producer/checker; see references/instruction-stability-standards.md。

for the full commands. Objective Hard Fails always block. Formal acceptance should first use scripts/harness_evidence_gate.py snapshot to freeze the candidate and rule read set, and fill in the expected failure codes for the candidate-internal checker, parameters, timeouts, and fault cases. After completing the static security review and obtaining user confirmation that the candidate is their own/trusted candidate, then personally rerun with verify --confirm-trusted-candidate . Self-reported exit codes, PASS, and logs must not be filled in or trusted in the JSON. Only when the exit code is 0 and HARNESS_REVIEW_VERIFIEDappears can it be said that "the Harness review evidence for the current candidate has been verified." This mark does not replace the target Skill's own DOMAIN_VERIFIED, and the gate is not a third-party code sandbox either.

Completion markers cannot substitute for one another:

• HARNESS_REVIEW_VERIFIED: the current candidate, rules, checker, and failure-case evidence are valid.
• INSTRUCTION_STABILITY_EVIDENCE_READY: dynamic recomputation is complete, but the draft has not yet been offline-signed and verified, so it cannot serve as a completion marker.
• INSTRUCTION_STABILITY_VERIFIED: the evaluator Ed25519 signature receipt has been re-verified, the external hard-constraint baseline/held-out, current Harness evidence, candidate/producer binding, and at least three rounds of real artifacts pass constraint by constraint, and the measurement/observable has not drifted.
• DOMAIN_VERIFIED: the domain validator confirms that the specific business artifact is correct.

As long as a Skill claims "stable completion", it must satisfy the first two items at the same time; if it also claims that the business result is correct, add the third item. For any layer that has not been run, always write NOT_VERIFIED。

7. Evaluability review

Confirm whether the Skill has the foundation for subsequent eval:

• Whether the evaluation scope is declared
• Whether Hard Fail is declared
• Whether a benchmark case or example is provided
• Whether output acceptance criteria are provided
• Whether static checks and dynamic evaluation are distinguished
• Whether there is a constraint-by-constraint traceability contract, validation modality, and artifact stage
• Whether at least three rounds of fixed input are used to check the key coverage set and historical regression
• Whether known false negatives have a minimal violation counterexample, and known false positives have a legitimate near-positive example

The absence of these contents does not necessarily block release, but should be recorded as a quality risk.

8. Generate review report

The review report should list problems first, then give a summary. Serious problems must be specific to the file and location.

If the user needs a final deliverable, pre-release opinion, or formal quality conclusion, use templates/skill-quality-opinion-report.md to generate a "Skill Quality Opinion Report". The report must state the problem, impact, correction method, and re-review criteria.

For structural suggestions that carry design principles (decomposition disclosure, trigger boundaries, context focus, freedom matching, machine-judgeable acceptance, etc.), explain the underlying writing principle in one sentence in the finding's "Design Philosophy" field, and refer back to the "Design Philosophy" subsection of the corresponding standards file, so that the report also has skill-writing teaching value; purely factual problems (missing files, broken references, naming case) may be omitted. Stability findings must specifically point out which constraint, validation modality, artifact stage, case, or run was missed, and must not use unreviewable generic phrases such as "unstable compliance".

After generating the formal quality opinion report, follow references/archive-standards.md to determine whether to archive it. When archiving is needed, save the report, metadata, and evidence index under this skill's archive/YYYYMMDD_HHMMSS_<target-slug>/ ; the actual archived content is not committed to Git.

Problem severity levels

Level	Description	Handling
❌ Serious	Blocks loading, release, safe use, or quality acceptance	Must fix
⚠️ Warning	Affects maintenance, reuse, review credibility, or evaluability	Recommended fix
ℹ️ Info	Style, clarity, or follow-up improvement suggestion	Optional handling

Hard Fail is always handled as a serious problem.

Report template

The formal quality opinion report template is at templates/skill-quality-opinion-report.mdIn addition to the original structure, security, business flow, and assessability, the report must separately list the Harness seven-layer conclusions, evidence levels, and completion markers.

Key points of the template's design philosophy (the "Design Philosophy" field is required for structural recommendations and may be omitted for purely factual questions):

• Critical issue: location + basis + impact + correction method + design philosophy + optimal design + recheck criteria
• Warning issue: location + impact + recommended correction + design philosophy + optimal design + priority
• Security assessment: risk category + security level + context (to avoid pure keyword false positives)
• Recheck checklist: critical issues closed + warning issues handled or logged + file references reachable + privacy redacted + security coverage + release governance synchronized

Reference rules

• references/skill-standards.md: review index and module routing
• references/repository-skill-discovery-standards.md: repository type identification, monorepo unit discovery, and candidate document grading
• references/structure-standards.md: directory structure, file reachability, and references naming
• references/frontmatter-metadata-policy.md: layered strategy for common Frontmatter fields and project release fields
• references/trigger-description-standards.md：name and description trigger boundaries
• references/configuration-privacy-standards.md: configuration templates, local configuration isolation, and de-specification of public content
• references/security-assessment-standards.md: dangerous execution, sensitive access, data exfiltration, credentials, dependencies, MCP, and prompt security
• references/publishing-standards.md: LICENSE, CHANGELOG, version, and release index
• references/workflow-output-standards.md: body workflow, dependencies, scripts, output, and orchestratability
• references/business-flow-rubric.md: criteria for business flow depth and assessability
• references/harness-reliability-standards.md: Harness seven-layer reliability, Hard Fail, creation precheck, and candidate binding evidence gates
• references/instruction-stability-standards.md: legacy version identification, constraint tracking, modality/stage matching, multi-round execution, and output drift gates
• references/reporting-standards.md: issue grading and review report template
• references/archive-standards.md: internal archiving mechanism for formal review reports
• references/skill-dev-guide.md: Skill development specification reference
• references/skill-orchestration-guide.md: complex orchestration specification reference
• config/review-profile.example.yaml: personal/project review configuration template
• config/instruction-stability-contract.example.json: constraint tracking contract example for the target Skill
• config/instruction-stability-requirements-baseline.example.json: example format for a candidate-external independent hard constraint baseline
• config/instruction-stability-held-out-cases.example.json: format for an evaluator-signed candidate-external hidden positive and negative example list
• scripts/harness_evidence_gate.py: Harness review evidence for generating and recomputing candidate binding
• scripts/harness_failure_audit.py: static review of specific Harness failure modes for a single Skill / Skill set
• scripts/instruction_stability_gate.py: statically identify legacy structure risks and verify per-constraint coverage stability of multi-round real artifacts
• templates/skill-quality-opinion-report.md: final Skill quality opinion report template