Golden Principles

Scan repository for golden principle violations with agent-readable remediation. Enforces GP-001 through GP-008 from .agents/governance/golden-principles.md. Use when auditing compliance, preparing PRs, or running garbage collection scans.

rjmurillo Updated Sep 10, 2026

Install

Press C to copy

$ npx skillmds@latest add rjmurillo/golden-principles

Installs into ~/.claude/skills (or .claude/skills inside a project). Restart Claude Code to pick it up.

＋ Add to plugin

README badge

[![SkillMD](https://skillmd.com/badge/rjmurillo/golden-principles.svg)](https://skillmd.com/skills/rjmurillo/golden-principles)

Trust & safety

Audits pending

Not yet audited · commit f58ae1a

Permissions this skill uses

Executes scripts
The instructions run shell commands or bundled script files.
Makes network calls
The instructions fetch remote URLs or call external services.

License: MIT
Works with: Claude Code Claude.ai OpenAI Codex +

File contents

Golden Principles

Scan the repository for violations of mechanically enforced golden principles. Produces remediation instructions that agents can act on directly.

Inspired by OpenAI Harness Engineering:

"We started encoding what we call 'golden principles' directly into the repository and built a recurring cleanup process."

Triggers

Trigger Phrase	Operation
`scan golden principles`	Full principle compliance scan
`check principle compliance`	Scan with summary report
`golden principle violations`	Scan and list violations
`run garbage collection`	Deep scan with fix-up recommendations
`audit principles`	Scan specific rules only

When to Use

Use this skill when:

Preparing a PR for submission (catch violations early)
Running periodic garbage collection scans
Auditing a domain or directory for compliance
Adding new files to the repository

Use taste-lints instead when:

Checking code-level invariants only (file size, naming, complexity)
Running pre-commit checks on staged files

Use quality-grades instead when:

Grading domains across architectural layers
Producing quality trend reports

Process

Run python3 .claude/skills/golden-principles/scripts/scan_principles.py with target
Review AGENT_REMEDIATION blocks in output
Apply suggested fixes
Re-run to confirm compliance

Usage

# Scan entire repository
python3 .claude/skills/golden-principles/scripts/scan_principles.py

# Scan specific directory
python3 .claude/skills/golden-principles/scripts/scan_principles.py --directory .claude/skills/

# Scope to a pull request diff (only files changed vs the base branch)
python3 .claude/skills/golden-principles/scripts/scan_principles.py --diff-scope "origin/$BASE_BRANCH"

# Run specific rules only
python3 .claude/skills/golden-principles/scripts/scan_principles.py --rules script-language,skill-frontmatter

# JSON output for tooling
python3 .claude/skills/golden-principles/scripts/scan_principles.py --format json

# Write results to file
python3 .claude/skills/golden-principles/scripts/scan_principles.py --output scan-results.json --format json

Rules

Rule	Principle	What it checks
`script-language`	GP-001	No new .sh/.bash files
`skill-frontmatter`	GP-003	SKILL.md has required frontmatter fields
`agent-definition`	GP-004	Agent .md files have required sections
`yaml-logic`	GP-005	No inline logic in workflow YAML
`actions-pinned`	GP-006	GitHub Actions pinned to SHA

GP-002, GP-007, GP-008 are enforced by existing tools (git hooks, taste-lints).

Exit Codes

Code	Meaning
0	No violations found
1	Script error (bad arguments, file not found)
10	Violations detected

Scripts

Script	Purpose	Exit codes
`scripts/scan_principles.py`	Scan a path (repo, directory, or diff scope) for GP-001..GP-006 violations and emit AGENT_REMEDIATION blocks. Supports `--directory`, `--diff-scope`, `--rules`, `--format`, `--output`.	`0` no violations; `10` violations detected; `1` tool error (bad arguments, file not found).

Suppression

Add a comment in the file header to suppress a specific rule:

# golden-principle: ignore script-language

Valid rules: script-language, skill-frontmatter, agent-definition, yaml-logic, actions-pinned

Verification

After execution, run the bundled validator and require exit 0:

python3 .claude/skills/golden-principles/scripts/scan_principles.py <path>
echo "exit=$?"   # 0 = clean, 10 = violations found, 1 = tool error

Exit 0 to pass; exit 10 means violations exist and must be reported with principle ID and remediation
Exit 1 (tool error) is a BLOCKED result, not a pass
Report lists scanned file count
Output format matches --format flag

References

Code Qualities - Five foundational qualities: cohesion, coupling, non-redundancy, encapsulation, testability
SOLID Principles - SRP, OCP, LSP, ISP, DIP with violation signs and code examples
Programming by Intention - Sergeant pattern for expressing intent over implementation
Separation of Concerns - Decomposition at method, class, layer, and service levels
DRY Principle - Single authoritative representation with scope, violations, and when NOT to DRY

Cross-References

Golden Principles Document: .agents/governance/golden-principles.md
Taste Lints for GP-007, GP-008
Quality Grades for domain-level grading

---name: golden-principlesdescription: Scan repository for golden principle violations with agent-readable remediation. Enforces GP-001 through GP-008 from .agents/governance/golden-principles.md. Use when auditing compliance, preparing PRs, or running garbage collection scans.license: MIT---# Golden PrinciplesScan the repository for violations of mechanically enforced golden principles.Produces remediation instructions that agents can act on directly.Inspired by [OpenAI Harness Engineering](https://openai.com/index/harness-engineering/):> "We started encoding what we call 'golden principles' directly into the repository> and built a recurring cleanup process."## Triggers| Trigger Phrase | Operation ||----------------|-----------|| `scan golden principles` | Full principle compliance scan || `check principle compliance` | Scan with summary report || `golden principle violations` | Scan and list violations || `run garbage collection` | Deep scan with fix-up recommendations || `audit principles` | Scan specific rules only |## When to UseUse this skill when:- Preparing a PR for submission (catch violations early)- Running periodic garbage collection scans- Auditing a domain or directory for compliance- Adding new files to the repositoryUse `taste-lints` instead when:- Checking code-level invariants only (file size, naming, complexity)- Running pre-commit checks on staged filesUse `quality-grades` instead when:- Grading domains across architectural layers- Producing quality trend reports## Process1. Run `python3 .claude/skills/golden-principles/scripts/scan_principles.py` with target2. Review AGENT_REMEDIATION blocks in output3. Apply suggested fixes4. Re-run to confirm compliance## Usage```bash# Scan entire repositorypython3 .claude/skills/golden-principles/scripts/scan_principles.py# Scan specific directorypython3 .claude/skills/golden-principles/scripts/scan_principles.py --directory .claude/skills/# Scope to a pull request diff (only files changed vs the base branch)python3 .claude/skills/golden-principles/scripts/scan_principles.py --diff-scope "origin/$BASE_BRANCH"# Run specific rules onlypython3 .claude/skills/golden-principles/scripts/scan_principles.py --rules script-language,skill-frontmatter# JSON output for toolingpython3 .claude/skills/golden-principles/scripts/scan_principles.py --format json# Write results to filepython3 .claude/skills/golden-principles/scripts/scan_principles.py --output scan-results.json --format json```## Rules| Rule | Principle | What it checks ||------|-----------|----------------|| `script-language` | GP-001 | No new .sh/.bash files || `skill-frontmatter` | GP-003 | SKILL.md has required frontmatter fields || `agent-definition` | GP-004 | Agent .md files have required sections || `yaml-logic` | GP-005 | No inline logic in workflow YAML || `actions-pinned` | GP-006 | GitHub Actions pinned to SHA |GP-002, GP-007, GP-008 are enforced by existing tools (git hooks, taste-lints).## Exit Codes| Code | Meaning ||------|---------|| 0 | No violations found || 1 | Script error (bad arguments, file not found) || 10 | Violations detected |## Scripts| Script | Purpose | Exit codes ||---|---|---|| `scripts/scan_principles.py` | Scan a path (repo, directory, or diff scope) for GP-001..GP-006 violations and emit AGENT_REMEDIATION blocks. Supports `--directory`, `--diff-scope`, `--rules`, `--format`, `--output`. | `0` no violations; `10` violations detected; `1` tool error (bad arguments, file not found). |## SuppressionAdd a comment in the file header to suppress a specific rule:```python# golden-principle: ignore script-language```Valid rules: `script-language`, `skill-frontmatter`, `agent-definition`, `yaml-logic`, `actions-pinned`## VerificationAfter execution, run the bundled validator and require exit 0:```bashpython3 .claude/skills/golden-principles/scripts/scan_principles.py <path>echo "exit=$?" # 0 = clean, 10 = violations found, 1 = tool error```- [ ] Exit 0 to pass; exit 10 means violations exist and must be reported with principle ID and remediation- [ ] Exit 1 (tool error) is a BLOCKED result, not a pass- [ ] Report lists scanned file count- [ ] Output format matches --format flag## References- [Code Qualities](references/design-code-qualities.md) - Five foundational qualities: cohesion, coupling, non-redundancy, encapsulation, testability- [SOLID Principles](references/design-solid-principles.md) - SRP, OCP, LSP, ISP, DIP with violation signs and code examples- [Programming by Intention](references/design-programming-by-intention.md) - Sergeant pattern for expressing intent over implementation- [Separation of Concerns](references/design-separation-of-concerns.md) - Decomposition at method, class, layer, and service levels- [DRY Principle](references/design-dry-principle.md) - Single authoritative representation with scope, violations, and when NOT to DRY## Cross-References- Golden Principles Document: `.agents/governance/golden-principles.md`- [Taste Lints](../taste-lints/SKILL.md) for GP-007, GP-008- [Quality Grades](../quality-grades/SKILL.md) for domain-level grading

rjmurillo/ai-agents/tree/main/.claude/skills/golden-principles commit f58ae1af93

Frequently asked questions

npx skillmds@latest add rjmurillo/golden-principles