AGENT SKILL

secretzero-precommit-validation

Use before completing feature work, after making code changes, or when preparing for commit/merge. Runs the full pre-commit validation suite, auto-resolves common failures (lint, formatting, test count mismatches), and reports structured results. Integration point for verification-before-completion, finishing-a-development-branch, and code review workflows.

License 许可
Apache-2.0
所属仓库
zloeber/SecretZero
最近更新
2026-10-31
Stars
★ 8
Forks
0

01 前言 Front Matter

name
secretzero-precommit-validation
metadata
{ "internal": true }
description
Use before completing feature work, after making code changes, or when preparing for commit/merge. Runs the full pre-commit validation suite, auto-resolves common failures (lint, formatting, test count mismatches), and reports structured results. Integration point for verification-before-completion, finishing-a-development-branch, and code review workflows.

03 SKILL.md 正文

SecretZero Pre-Commit Validation Skill

Use this skill to validate code quality and test coverage before completing any feature work, committing changes, or preparing for code review.

When to Use

MUST use before:

  • Completing feature implementation
  • Creating a commit or PR
  • Claiming work is ready for review
  • Merging code to main

Triggers:

  • "run pre-commit", "run pre-commit tests", "validate before commit"
  • "complete the feature", "finish this work", "ready to commit"
  • Automatic gate in verification-before-completion or finishing-a-development-branch skills

What It Does

The skill executes the full pre-commit validation suite:

  1. Linting (task lint): Python static analysis, unused variables, code quality
  2. Testing (task test): Full pytest suite (1180+ tests)
  3. Security scan (task security:scan): pip-audit + bandit
  4. Formatting (auto): Black code formatting on violations
  5. Schema validation: Secretfile manifests
  6. Documentation links (optional): Hyperlink validation

Output

Returns a structured report:

{
  "status": "passed" | "failed",
  "tests_passed": 1180,
  "tests_failed": 0,
  "lint_issues": 0,
  "formatting_fixed": 0,
  "failures": [],
  "details": "All checks passed! Ready for commit."
}

Common Failures & Auto-Resolution

Unused Variable Warnings

Symptom: F841 Local variable 'x' is assigned but never used

Resolution: The skill auto-identifies and removes unused variable assignments. Example:

# Before
style_name = style.get("Style Category", "")  # Assigned but never used
keywords = style.get("Keywords", "")  # Used

# After
keywords = style.get("Keywords", "")  # Only used variables remain

Code Formatting Issues

Symptom: would reformat /path/to/file.py

Resolution: Auto-runs task format and re-validates.

Test Count Mismatches

Symptom: Test expects 5 capabilities but finds 6 (or vice versa)

Resolution: The skill identifies the mismatch and provides guidance:

AWS provider now has 6 capabilities (added retrieve_iam_user_credentials).
Update test assertion from len(capabilities) == 5 to == 6
Add assertion: assert caps.get_capability("retrieve_iam_user_credentials") is not None

Schema Validation Failures

Symptom: Secretfile manifests invalid or out of sync with schema

Resolution: Runs task schema:update to regenerate schema and example files.

Security Vulnerabilities

Symptom: pip-audit reports known vulnerabilities (GHSA/CVE), e.g. vulnerable transitive packages.

Resolution:

  • Bump dependency floors in pyproject.toml ([tool.uv.override-dependencies])
  • Add package to exclude-newer-package when needed to bypass the global recency window
  • Refresh uv.lock
  • Re-run task security:scan and then full pre-commit validation

Invocation

Direct Usage (Standalone)

# Run and report results
./scripts/agent.pre-commit.sh --mode full

# Quick validation (lint + format only)
./scripts/agent.pre-commit.sh --mode fast

Within a Skill Workflow

When called by another skill (e.g., verification-before-completion):

  1. Executes validation suite
  2. Catches and auto-resolves common failures (formatting, unused vars)
  3. Reports pass/fail with structured output
  4. Guides user through manual fixes if needed (test count updates, etc.)

Example from verification-before-completion:

## ✅ Pre-Commit Validation Passed

- All 1180 tests passed ✓
- Linting clean ✓
- Formatting applied ✓
- Ready for commit

Example from finishing-a-development-branch (auto-gate):

Pre-commit validation is required before merge. Running now...

[Output shows failures + auto-fixes applied]

Retry validation...

[All checks now pass]

Proceeding with branch completion.

Integration Points

With verification-before-completion Skill

completion-claimed → invoke this skill → pass? → proceed : halt + guide fixes

With finishing-a-development-branch Skill

merge/squash → validate pre-commit required → invoke skill → all pass? → complete : retry

With requesting-code-review Skill

ready for review → validate pre-commit → pass? → create PR : request fixes

Manual Workflow

# Make changes
# ... code work ...

# Validate before commit
task lint && task test

# Or use the skill for auto-resolution
./scripts/agent.pre-commit.sh --mode full

Failure Categories & Guidance

Category Example Auto-Resolved? Guidance
Unused variables F841 in linting ✅ Yes Removed from code
Code formatting Black violations ✅ Yes Auto-formatted via task format
Test count mismatch Expected 5, got 6 ⚠️ Partial Identifies issue; user updates assertion
Import errors Missing dependency ❌ No Install via uv pip install
Logic errors Test assertion fails ❌ No User debugs test logic
Schema drift Secretfile.yml vs schema ✅ Yes Regenerated via task schema:update
Dependency CVEs pip-audit vulnerability findings ⚠️ Partial Raise floor + refresh lockfile, then re-run scan

Output Interpretation

PASSED (All green):

====================== 1180 passed, 23 warnings in 12.76s ======================
All checks passed!
✓ Secretfile is valid
[Ready for commit]

FAILED (Issues found):

Found 3 errors.
1 file would be reformatted.
FAILED tests/test_X.py::TestY::test_z - assert 6 == 5

When failures occur:

  1. Skill auto-resolves what it can (formatting, unused vars)
  2. Re-runs validation
  3. Reports remaining issues with guidance
  4. If all resolved → report success
  5. If manual fixes needed → show what user needs to fix

Exit Codes

  • 0: All checks passed ✅
  • 1: Checks failed, some auto-resolved but manual fixes needed
  • 201: Timeout or severe error (rare; usually schema or dependency issue)

Context Efficiency

This skill is designed to be lightweight for agents:

  • ✅ Handles output parsing internally (no manual log parsing)
  • ✅ Auto-resolves common issues
  • ✅ Returns structured results (JSON-friendly)
  • ✅ Works across sessions without setup
  • ✅ Integrates seamlessly with other skills

For users: Just invoke it. The skill handles the rest.

For other skills: Can call this skill to guarantee pre-commit state before proceeding (e.g., finishing-a-development-branch auto-gates on validation pass).

Related Skills

  • verification-before-completion: Calls this skill as part of completion verification
  • finishing-a-development-branch: Uses this as a hard gate before merge
  • requesting-code-review: Validates pre-commit passes before creating PR

04 同仓库更多 Skills

zloeber
zloeber/SecretZero

secretzero

Compatibility entrypoint for SecretZero skills. Enforces the absolute rule: never consume secrets in agent context — use SecretZero for all secret handling. Routes to secretzero-author, secretzero-agent, secretzero-handle, and secretzero-agent-adopt.

★ 8
zloeber
zloeber/SecretZero

secretzero-handle

Use when the task touches `.env`, dotenv/json/yaml secret files, local `file` targets, or any workflow where secret material could enter agent context. Enforces `SZ_AGENT_MODE=true` spill-safe CLI usage, ingest preseed, strict manifest validation, and safe discovery patterns alongside `secretzero-agent` / `secretzero-author`.

★ 8
zloeber
zloeber/SecretZero

secretzero-author

Use when authoring, reviewing, or walking a user through a new or existing `Secretfile.yml`. Guided session: manifest root, inventory table, optional local discovery, add/edit loop with secret-type and target menus, validate, optional `secretzero web`. Hermes + MCP notes included. Safe contextless discovery, `.szvar` lanes, policy-bound targets. Inherits absolute rule from `skills/secretzero/SKILL.md`. Co-load `skills/secretzero-handle/SKILL.md` for `.env` / spill-safe CLI.

★ 8
zloeber
zloeber/SecretZero

secretzero-agent

Use for agentic and operational SecretZero workflows including unified `agent sync`, CLI/API/MCP parity, secure human-in-the-loop vectors, and automation-safe run loops.

★ 8
zloeber
zloeber/SecretZero

secretzero-agent-adopt

Use for agent runtime integration: discover Hermes/OpenClaw installs, bootstrap SecretZero environments with `secretzero agent list` / `agent adopt`, lockfile preseed, and restore loops. Inherits absolute rule from `skills/secretzero/SKILL.md` (SecretZero only; never secrets in context).

★ 8
zloeber
zloeber/SecretZero

secretzero

Compatibility entrypoint for SecretZero skills. Enforces the absolute rule: never consume secrets in agent context — use SecretZero for all secret handling. Routes to secretzero-author, secretzero-agent, secretzero-handle, and secretzero-agent-adopt.

★ 8