candid-validate-standards
Validate Technical.md for vague rules, linter overlaps, and effectiveness issues
How do I install this agent skill?
npx skills add https://github.com/ron-myers/candid --skill candid-validate-standardsIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill is designed to audit documentation files and check them against a local codebase. It uses shell commands to verify file existence and search for code patterns. The primary risk is indirect prompt injection, as the skill processes external documentation that could contain malicious instructions meant to influence the agent's behavior during the validation process.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerpass
1 file scanned · No issues
What does this agent skill do?
Technical.md Validator
Analyze a Technical.md file and identify rules that may be ineffective, vague, or redundant with existing tooling.
Workflow
Step 1: Locate Technical.md
Find the Technical.md file to validate:
- If path argument provided → use that path
- Check
./Technical.md - Check
./.candid/Technical.md
If no file found:
❌ No Technical.md found.
Looked in:
- ./Technical.md
- ./.candid/Technical.md
Create one with: /candid-init
Step 2: Detect Linter Configs
Check for existing linter configurations:
# JavaScript/TypeScript
ls .eslintrc* eslint.config.* .prettierrc* biome.json 2>/dev/null
# Python
ls .flake8 pyproject.toml setup.cfg .ruff.toml ruff.toml 2>/dev/null
# Go
ls .golangci.yml .golangci.yaml 2>/dev/null
# Ruby
ls .rubocop.yml 2>/dev/null
Store detected linters for Step 4.
Step 3: Parse Technical.md
Read the Technical.md file and extract rules.
Rule detection:
- Lines starting with
-or*(list items) - Lines starting with numbers (numbered lists)
- Lines following a
##heading
Skip:
- Code blocks (between ```)
- Empty lines
- Comments (HTML or markdown)
- Heading lines themselves
Store each rule with:
- Line number
- Section heading it belongs to
- Full rule text
Step 4: Validate Each Rule
Check each rule against these issue categories:
4.1 Vague Language (🌫️)
Flag rules containing vague terms without specifics:
| Vague Term | Why It's Vague |
|---|---|
| "clean" | Subjective, no definition |
| "good" | Subjective |
| "proper" / "appropriate" | Undefined standard |
| "well-designed" / "well-structured" | No criteria |
| "readable" / "maintainable" | Without metrics |
| "best practices" | Circular reference |
| "when necessary" / "when appropriate" | Undefined trigger |
| "avoid" (alone) | No guidance on alternatives |
| "consider" | Not a requirement |
Also flag: suitable, adequate, well-organized, well-written, scalable, flexible, robust, simple, straightforward, intuitive, obvious, sensible, meaningful, significant, as needed, prefer, try to, minimal, few, some, many, several, various.
Exception: Terms are OK if followed by specific criteria:
- "readable (functions under 50 lines)" ✓
- "maintainable" ✗
4.2 Missing Thresholds (📏)
Flag rules that imply quantity without numbers:
| Pattern | Issue |
|---|---|
| "small functions" | How small? |
| "short methods" | How short? |
| "limit parameters" | To how many? |
| "minimal dependencies" | What's minimal? |
| "few levels of nesting" | How few? |
| "reasonable timeout" | What's reasonable? |
Also flag: maximum/minimum, too many/too few, keep under/below, no more than — when no number follows.
Fix pattern: Add specific numbers (e.g., "functions under 50 lines")
4.3 Linter Overlap (🔧)
Flag rules that linters typically handle (based on Step 2):
If ESLint/Prettier detected:
- Semicolon usage
- Quote style (single vs double)
- Indentation rules
- Trailing commas
- Import ordering
- Unused variables
- No console.log
If Flake8/Ruff detected:
- Line length
- Import sorting
- Whitespace rules
- Naming conventions (snake_case)
If any linter detected:
- Formatting rules in general
- Basic syntax style
4.4 Multiple Concerns (🎯)
Flag rules that try to do too much:
- Rules with "and" connecting unrelated concerns
- Rules over 2 lines long
- Rules with multiple "must" statements
Example:
❌ "Functions should be small, well-documented, and handle errors properly"
✓ Split into three rules
4.5 Unverifiable Rules (❓)
Flag rules that can't be checked by reading code:
- "Think about edge cases"
- "Be consistent"
- "Follow team conventions"
- "Use common sense"
- References to external documents without specifics
4.6 Codebase Spot-Check (🔬)
For up to 10 rules that cite a path, glob, or naming pattern:
- Verify every cited file/directory exists (
lsit). Missing → flag stale. - Sample 3 files the rule applies to (find/grep by the rule's stated scope) and check whether the rule actually holds in each.
- 0/3 hold → flag untrue ("rule contradicts this codebase — remove or move to Gaps").
1-2/3 hold → flag contested ("add known exceptions or relax the rule").
Report in a
🔬 Spot-Checksection listing the sampled files per rule.
Step 5: Generate Report
Present findings organized by severity:
# Technical.md Validation Report
**File:** ./Technical.md
**Rules analyzed:** [N]
**Issues found:** [M]
---
## 🔴 Critical Issues
Rules that won't be effective in reviews.
### 🌫️ Vague Language
| Line | Rule | Issue |
|------|------|-------|
| 12 | "Write clean code" | "clean" is subjective |
| 24 | "Use appropriate error handling" | "appropriate" undefined |
### 📏 Missing Thresholds
| Line | Rule | Issue |
|------|------|-------|
| 18 | "Keep functions small" | No size specified |
| 31 | "Limit nesting depth" | No depth specified |
---
## 🟡 Warnings
Rules that may have issues.
### 🔧 Linter Overlap
| Line | Rule | Linter |
|------|------|--------|
| 8 | "Use semicolons" | ESLint handles this |
| 15 | "Sort imports alphabetically" | Prettier/ESLint handles this |
### 🎯 Multiple Concerns
| Line | Rule | Suggestion |
|------|------|------------|
| 22 | "Functions should be pure, small, and documented" | Split into 3 rules |
---
## 🔬 Spot-Check
[Per rule checked: verdict (stale/untrue/contested) with the 3 sampled files]
---
## ✅ Good Rules
[List of rules that passed validation]
If zero issues: output a short pass message with file path and rule count instead of the full report.
Step 6: Suggest Fixes (if --fix flag)
If --fix argument provided, include specific rewrites:
## 💡 Suggested Rewrites
### Line 24: "Use appropriate error handling"
**Original:** Use appropriate error handling
**Suggested:**
- All async functions must have try/catch or .catch()
- Errors must be logged with context before re-throwing
- User-facing errors must not expose stack traces
Step 7: Summary
End with actionable summary:
---
## Summary
- **[X] rules** are effective and specific ✅
- **[Y] rules** need thresholds or specifics 📏
- **[Z] rules** overlap with linters 🔧
- **[W] rules** are too vague to enforce 🌫️
### Recommended Actions
1. Remove [Z] linter-overlap rules (your linter handles these)
2. Add numbers to [Y] threshold rules
3. Rewrite [W] vague rules with specific criteria
Run `/candid-validate-standards --fix` for suggested rewrites.
Remember
The goal is to help users write Technical.md files that:
- Candid can actually enforce
- Don't duplicate existing tooling
- Focus on what matters (architecture, security, patterns)
- Are specific enough to be useful
A validated Technical.md leads to better code reviews.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/ron-myers/candid/candid-validate-standards">View candid-validate-standards on skillZs</a>