Clean Code

Pragmatic coding standards - concise, direct, no over-engineering, no unnecessary comments

Security Scan

This is an instruction-only coding-style skill whose requirements and instructions are consistent with its stated purpose, but it asks agents to run repository-local validation scripts and to make broad edits to dependent files — so review changes and any scripts the agent might execute before trusting it with write access.

Purpose & Capability

The name/description (pragmatic coding standards) match the SKILL.md content: naming/function rules, anti-patterns, and a pre-completion checklist. There are no unexpected environment variables, binaries, or installs requested that would be inconsistent with a style/quality guideline skill.

Instruction Scope

The instructions focus on editing code, running checks, and verifying changes, which is appropriate. However the skill mandates that agents 'Edit the file + all dependent files in the SAME task' and includes a mapping of repository-local verification scripts under .agent/skills/... — this encourages broad repository reads/writes and execution of local scripts. That is coherent for a code-editing workflow but increases the scope of changes an agent may perform and the number of files it may touch, so operators should prefer review-before-commit and limit write permissions.

Install Mechanism

No install specification or downloaded code is present; the skill is instruction-only, which is the lowest install risk.

Credentials

The skill declares no environment variables, credentials, or config paths. The SKILL.md references only repository-local paths and test/lint scripts; it does not request or reference external secret values or unrelated services.

Persistence & Privilege

The skill does not request always:true or any persistent system-level privileges. Model invocation is enabled (the platform default), which is normal for skills and not by itself a concern.

Assessment

This skill appears to be a straightforward coding-style instruction set and is internally consistent. Before installing or allowing it to run with write/execute permissions: (1) confirm you trust the agent and repository, because the skill encourages editing dependent files in the same task (which can produce wide-ranging changes), (2) review any .agent/skills/... scripts the agent will run — they execute code from the workspace and might run networked commands, and (3) prefer a workflow where the agent proposes changes as patches or a pull request for human review rather than committing automatically. If you need tighter control, restrict the agent's ability to execute repository scripts or require explicit confirmation before running verification scripts or applying edits.

Clean Code - Pragmatic AI Coding Standards

CRITICAL SKILL - Be concise, direct, and solution-focused.

---

Core Principles

Principle	Rule
SRP	Single Responsibility - each function/class does ONE thing
DRY	Don't Repeat Yourself - extract duplicates, reuse
KISS	Keep It Simple - simplest solution that works
YAGNI	You Aren't Gonna Need It - don't build unused features
Boy Scout	Leave code cleaner than you found it

---

Naming Rules

Element	Convention
Variables	Reveal intent: userCount not n
Functions	Verb + noun: getUserById() not user()
Booleans	Question form: isActive, hasPermission, canEdit
Constants	SCREAMING_SNAKE: MAX_RETRY_COUNT

Rule: If you need a comment to explain a name, rename it.

---

Function Rules

Rule	Description
Small	Max 20 lines, ideally 5-10
One Thing	Does one thing, does it well
One Level	One level of abstraction per function
Few Args	Max 3 arguments, prefer 0-2
No Side Effects	Don't mutate inputs unexpectedly

---

Code Structure

Pattern	Apply
Guard Clauses	Early returns for edge cases
Flat > Nested	Avoid deep nesting (max 2 levels)
Composition	Small functions composed together
Colocation	Keep related code close

---

AI Coding Style

Situation	Action
User asks for feature	Write it directly
User reports bug	Fix it, don't explain
No clear requirement	Ask, don't assume

---

Anti-Patterns (DON'T)

❌ Pattern	✅ Fix
Comment every line	Delete obvious comments
Helper for one-liner	Inline the code
Factory for 2 objects	Direct instantiation
utils.ts with 1 function	Put code where used
"First we import..."	Just write code
Deep nesting	Guard clauses
Magic numbers	Named constants
God functions	Split by responsibility

---

🔴 Before Editing ANY File (THINK FIRST!)

Before changing a file, ask yourself:

Question	Why
What imports this file?	They might break
What does this file import?	Interface changes
What tests cover this?	Tests might fail
Is this a shared component?	Multiple places affected

Quick Check:

File to edit: UserService.ts
└── Who imports this? → UserController.ts, AuthController.ts
└── Do they need changes too? → Check function signatures

🔴 Rule: Edit the file + all dependent files in the SAME task. 🔴 Never leave broken imports or missing updates.

---

Summary

Do	Don't
Write code directly	Write tutorials
Let code self-document	Add obvious comments
Fix bugs immediately	Explain the fix first
Inline small things	Create unnecessary files
Name things clearly	Use abbreviations
Keep functions small	Write 100+ line functions

Remember: The user wants working code, not a programming lesson.

---

🔴 Self-Check Before Completing (MANDATORY)

Before saying "task complete", verify:

Check	Question
✅ Goal met?	Did I do exactly what user asked?
✅ Files edited?	Did I modify all necessary files?
✅ Code works?	Did I test/verify the change?
✅ No errors?	Lint and TypeScript pass?
✅ Nothing forgotten?	Any edge cases missed?

🔴 Rule: If ANY check fails, fix it before completing.

---

Verification Scripts (MANDATORY)

🔴 CRITICAL: Each agent runs ONLY their own skill's scripts after completing work.

Agent → Script Mapping

Agent	Script	Command
frontend-specialist	UX Audit	python .agent/skills/frontend-design/scripts/ux_audit.py .
frontend-specialist	A11y Check	python .agent/skills/frontend-design/scripts/accessibility_checker.py .
backend-specialist	API Validator	python .agent/skills/api-patterns/scripts/api_validator.py .
mobile-developer	Mobile Audit	python .agent/skills/mobile-design/scripts/mobile_audit.py .
database-architect	Schema Validate	python .agent/skills/database-design/scripts/schema_validator.py .
security-auditor	Security Scan	python .agent/skills/vulnerability-scanner/scripts/security_scan.py .
seo-specialist	SEO Check	python .agent/skills/seo-fundamentals/scripts/seo_checker.py .
seo-specialist	GEO Check	python .agent/skills/geo-fundamentals/scripts/geo_checker.py .
performance-optimizer	Lighthouse	python .agent/skills/performance-profiling/scripts/lighthouse_audit.py <url>
test-engineer	Test Runner	python .agent/skills/testing-patterns/scripts/test_runner.py .
test-engineer	Playwright	python .agent/skills/webapp-testing/scripts/playwright_runner.py <url>
Any agent	Lint Check	python .agent/skills/lint-and-validate/scripts/lint_runner.py .
Any agent	Type Coverage	python .agent/skills/lint-and-validate/scripts/type_coverage.py .
Any agent	i18n Check	python .agent/skills/i18n-localization/scripts/i18n_checker.py .

❌ WRONG: test-engineer running ux_audit.py ✅ CORRECT: frontend-specialist running ux_audit.py

---

🔴 Script Output Handling (READ → SUMMARIZE → ASK)

When running a validation script, you MUST:

1. Run the script and capture ALL output
2. Parse the output - identify errors, warnings, and passes
3. Summarize to user in this format:

## Script Results: [script_name.py]

### ❌ Errors Found (X items)
- [File:Line] Error description 1
- [File:Line] Error description 2

### ⚠️ Warnings (Y items)
- [File:Line] Warning description

### ✅ Passed (Z items)
- Check 1 passed
- Check 2 passed

**Should I fix the X errors?**

4. Wait for user confirmation before fixing
5. After fixing → Re-run script to confirm

🔴 VIOLATION: Running script and ignoring output = FAILED task. 🔴 VIOLATION: Auto-fixing without asking = Not allowed. 🔴 Rule: Always READ output → SUMMARIZE → ASK → then fix.