skill auditor

Security Community

Skill notes

⚠️ Critical Constraints

Auditor is read-only. Reports findings; never modifies the target. Why: PR-002 (external validation) — the auditor must remain a separate gate from the implementer. To repair findings: use heal-skill --fix for Pass-1 issues, hand-edit for Pass-2 issues. Pass 1 delegates, never reimplements. The auditor calls /heal-skill --check <target> and parses its output. Why: PR-006 (cross-layer consistency) — heal-skill's checks are the source of truth for structural hygiene; reimplementation creates drift.

Pass 1 — delegated to heal-skill

heal.sh code · Check MISSING_NAME · frontmatter name present MISSING_DESC · frontmatter description present NAME_MISMATCH · frontmatter name matches directory UNLINKED_REF · references/*.md linked from SKILL.md

Pass 2 — 8 NEW checks

· Check id · Severity 1 · description-has-triggers · WARN (downgraded from FAIL after pilot) 2 · constraints-frontloaded · WARN 3 · rationale-present · WARN 4 · verification-checkpoints · WARN

Advisory density report

The JSON report includes a separate density block with six report-only fields: intent, boundary, evidence, decision, constraint, and next_action. Read references/context-density-checks.md for detection rules, limits, and false-positive handling.

Pass 3 — rubric scoring (10 categories, advisory)

audit.sh runs scripts/score_agentops_skill.py --audit-block and folds the result into audit-report.json under a rubric key. The 10 categories come verbatim from docs/reference/skill-quality-rubric.md (read it for the per-score 0/1/2/3 definitions): trigger_quality, kernel_clarity, progressive_disclosure, helper_scripts, validation,

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
Security
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@boshu2 · no license declared
Token usage
Lean
Setup complexity
Guided setup
External API key
Not required
Operating systems
Unspecified (assume cross-platform)
Runtime requirements
No explicit requirements detected
Detected file/system behavior
  • Read-only
  • Write / modify
  • Shell exec
Network behavior
Local-only
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

01
Step 1: Pass 1 (heal-skill delegation)

Capture stdout. Each line `[CODE] <path>: <msg>` becomes one Pass-1 finding.

02
Step 2: Pass 2 (8 NEW checks)

For each `check_*` function in `scripts/audit.sh`, run against `<target>/SKILL.md`. Each emits `pass`, `warn`, or `fail` to stdout. Checkpoint: Pass 2 must run independently of Pass 1 (no shared state); a heal.sh failure does NOT short-circuit Pass 2.

03
Step 3: Pass 3 (rubric scoring)

`audit.sh` calls this and embeds the result under the report's `rubric` key. Each of the 10 rubric categories gets a 0-3 score + reason; total 0-30, rating band C/B/A/S. If `python3` or the scorer is unavailable, `rubric` is emitted as `null` (fail-open) and the JSON stays valid. Checkpoint: Pass 3 is advisory — its score is computed but NOT counted in the verdict.

04
Step 4: Aggregate verdict

Density coverage and the Pass-3 rubric are computed before emission but are NOT counted in the verdict.

05
Step 5: Emit report

JSON conforming to `schemas/audit-report.json` to stdout (or to file with `--json <path>`); markdown summary (including the Pass-3 rubric line) to stderr.

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.