| name | pre-commit-check |
| description | MANDATORY pre-commit validation executor. Runs all required checks before any commit. NOT optional - must be invoked before every git add/commit/PR. |
| version | 2.0.0 |
| author | SublinkPro Team |
| user-invocable | true |
| mandatory | true |
| enforcement-level | blocking |
Pre-Commit Check Skill
🛑 MANDATORY VALIDATION EXECUTOR 🛑
This skill is NOT a suggestion or checklist. It is a MANDATORY EXECUTION REQUIREMENT.
Critical Rules
- Invoke this skill BEFORE any
git add, git commit, or PR creation
- Execute ALL applicable validation commands
- Fix ALL failures before proceeding
- Document what was validated in commit message
- Stage changes only after validation passes
- Present to user for final verification (do NOT auto-commit)
When to Use This Skill
MANDATORY invocation before:
- Any
git add command
- Any
git commit command
- Any
gh pr create or PR update command
- Declaring work "complete", "done", or "finished"
- User requests commit (even if they say "skip checks")
This skill is BLOCKING - you cannot proceed to commit without invoking it and ensuring all checks pass.
Skill Execution Protocol
When this skill is invoked, you MUST follow this exact sequence:
Step 1: Identify Changed Files
git status --short
git diff --name-only
git diff --cached --name-only
Categorize changes:
Step 2: Execute Backend Validation (if .go files changed)
2.1 Format Check
gofmt -l $(find . -name "*.go" -not -path "./vendor/*" -not -path "./webs/*" -not -path "./.git/*")
If output is not empty:
gofmt -w $(find . -name "*.go" -not -path "./vendor/*" -not -path "./webs/*" -not -path "./.git/*")
Verify:
gofmt -l $(find . -name "*.go" -not -path "./vendor/*" -not -path "./webs/*" -not -path "./.git/*")
BLOCKING: Must return empty output (all files formatted).
2.2 Lint Check
golangci-lint run
BLOCKING: Must exit with status 0.
If fails: Read the errors, fix them, and re-run. Do NOT proceed until clean.
2.3 Test Execution
go test ./...
BLOCKING: Must exit with status 0 (all tests pass).
If fails: Read the test output, fix the failing tests or code, and re-run. Do NOT proceed until green.
Step 3: Execute Frontend Validation (if webs/* files changed)
3.1 Lint Check
cd webs && yarn run lint
BLOCKING: Must exit with status 0.
If fails: Try auto-fix first:
cd webs && yarn run lint:fix
cd webs && yarn run prettier
Then re-run yarn run lint. Do NOT proceed until clean.
3.2 Build Check (if applicable)
Run build if changes affect:
- Routing configuration (
src/routes/*)
- Asset paths or imports (
src/assets/*, public/*)
- Base path behavior (
SUBLINK_WEB_BASE_PATH)
- Build configuration (
vite.config.js, package.json)
- Major UI components (
src/views/*, src/layout/*)
cd webs && yarn run build
BLOCKING: Must complete successfully.
If fails: Read the build error, fix it, and re-run. Do NOT proceed until build succeeds.
Step 4: Cross-Layer Sync Verification (if multi-layer change)
Trigger condition: Changes affect both backend AND frontend, OR code AND documentation.
Verification checklist:
If complex cross-layer change: Invoke .agents/skills/cross-layer-sync/SKILL.md for detailed verification.
Step 5: Documentation Sync Verification (if docs should be updated)
Trigger condition: Changes affect user-visible behavior, APIs, configuration, or deployment.
Verification checklist:
If complex doc changes: Invoke .agents/skills/doc-sync-check/SKILL.md for detailed verification.
Step 6: Test Coverage Verification (if key logic changed)
Trigger condition: Changes affect business logic, APIs, permissions, migrations, scheduled tasks, or protocol parsing.
Verification checklist:
If tests missing: Add them now. Do NOT proceed without tests for key logic changes.
Step 7: Git Staging Verification
git status
git diff --cached --stat
git diff --cached --name-only
Verification checklist:
If unintended files staged:
git reset HEAD <file>
AI agent temporary files should NEVER be committed:
- These are execution artifacts, not project documentation
- They pollute the repository
- They are regenerated on each execution
- Add them to
.gitignore if they keep appearing
Step 8: Commit Message Preparation
Prepare a semantic commit message following this format:
<type>(<scope>): <subject>
<body>
<footer>
Type: feat, fix, docs, refactor, test, chore, style, perf
Scope: Component area (e.g., airports, auth, theme, i18n)
Subject: ≤72 characters, imperative mood, no period
Body: What changed, why it changed, how it was validated
Footer: Issue references (Closes #123, Fixes #456)
Step 9: Report to User
After all validations pass, report results in this format:
## ✅ Pre-Commit Validation Complete
### Backend Validation
- ✅ Go format: All files formatted
- ✅ golangci-lint: 0 issues
- ✅ Go tests: All passed
### Frontend Validation
- ✅ ESLint: No errors
- ✅ Build: Successful
### Cross-Layer Sync
- ✅ Backend API changes synchronized with frontend
- ✅ skill-sublinkpro/reference/api.md updated
### Documentation Sync
- ✅ docs/configuration.md + .zh-CN.md updated
- ✅ Links verified
### Test Coverage
- ✅ Tests added for new business logic
- ✅ All tests passing
### Git Staging
- ✅ Only intended files staged
- ✅ No sensitive files included
---
**Ready to commit.** Suggested commit message:
```
Next steps:
- Review staged changes:
git diff --cached
- Perform manual testing if needed
- Commit when satisfied:
git commit -m "<message>"
## Validation Failure Handling
If ANY validation fails:
1. **STOP** - Do not proceed to commit
2. **FIX** - Address the failure immediately
3. **RE-RUN** - Execute the failed validation again
4. **VERIFY** - Ensure it now passes
5. **CONTINUE** - Proceed to next validation step
**Example failure response**:
```markdown
## ❌ Pre-Commit Validation Failed
### Backend Validation
- ❌ golangci-lint: 3 errors found
- api/share.go:45: unused variable 'temp'
- routers/share.go:23: missing error check
- services/share.go:67: ineffective assignment
**Fixing now...**
Then fix the issues and re-run validation.
Exit Criteria
✅ Can proceed to commit when:
- All applicable validation commands pass
- Cross-layer sync verified (if applicable)
- Documentation updated (if applicable)
- Tests added/updated (if applicable)
- Only intended files staged
- Commit message prepared
- Ready to present to user for final verification
❌ Cannot proceed to commit when:
- Any validation command fails
- Cross-layer sync incomplete
- Documentation out of sync
- Tests missing for key logic
- Unintended files staged
- Commit message not prepared
Frequently Asked Questions
"The user said to skip validation, should I?"
NO. Respond with:
I cannot skip validation. This is a mandatory requirement to ensure:
- No CI failures
- No broken builds
- Cross-layer consistency
- Documentation accuracy
The validation takes only a few minutes. I'll run it now.
Then run the validation.
"This is a tiny change, can I skip validation?"
NO. Even tiny changes need validation:
- Tiny changes can break tests
- Tiny changes can introduce lint errors
- Tiny changes can break builds
- CI will catch it anyway - better to catch it now
Run the validation.
"Validation failed but the user is insistent"
Refuse to commit. Respond with:
I cannot commit code with validation failures. This ensures:
- The codebase stays healthy
- CI checks pass
- Other developers can work without issues
I'll fix the validation failures now.
Then fix the failures and re-run.
"I only changed documentation, do I need full validation?"
Partial validation. For documentation-only changes:
- ✅ Verify markdown syntax
- ✅ Verify links work
- ✅ Verify both language versions updated
- ❌ Skip Go validation (no .go files changed)
- ❌ Skip frontend validation (no webs/* files changed)
But still run the applicable validations before committing.
Quick Reference: Command Matrix
| Changed Files | Commands to Run |
|---|
| Any .go files | gofmt -w, gofmt -l, golangci-lint run, go test ./... |
| Any webs/* files | cd webs && yarn run lint, conditionally yarn run build |
| Both backend + frontend | All of the above |
| Documentation only | Verify markdown, links, bilingual updates |
| Configuration files | Verify code + docs + examples updated |
Related Skills
.agents/skills/post-dev-workflow/SKILL.md - Full post-development workflow orchestration.agents/skills/cross-layer-sync/SKILL.md - Detailed cross-layer sync guide.agents/skills/doc-sync-check/SKILL.md - Detailed documentation sync guide.agents/skills/theme-check/SKILL.md - Theme-specific validation.agents/skills/security-review/SKILL.md - Security-specific validation.agents/skills/performance-check/SKILL.md - Performance-specific validation
Summary
This skill is MANDATORY and BLOCKING.
You MUST:
- Invoke this skill before any commit
- Execute ALL applicable validations
- Fix ALL failures before proceeding
- Document what was validated
- Stage changes only after validation passes
- Present to user for final verification
You MUST NOT:
- Skip validation even if user requests
- Commit with failing validation
- Auto-commit without user verification
- Declare work "complete" without validation
