* feat(validation): enforce 60K-char cap on skill reference files Implements issue #277: - validate-references.rb: new oversized_reference_errors check — every references/*.md must be <= 60,000 characters; error reports path, size, and the split-and-reindex remediation; wired into validate-skills.rb - test-validate-skills.rb: 5 fixture tests (under-limit passes, over-limit fails with path+size, exactly-at-limit passes, remediation message, non-.md ignored); the suite now runs in validate.yml after the format check (it was previously untested in CI) - Docs: agent-skills/SKILL.md, agent-skills/references/best-practices.md, and the AGENTS.md Format Compliance table document the cap and the split-and-reindex procedure - Compliance: split remote-systems-administration/references/ansible.md and programming-principles/references/refactoring-guru.full.md into an index + focused parts (content moved verbatim); SKILL.md routing, README, and source-index references updated; pre-existing stale refactoring-guru-smells.md reference repointed to the index - Fix pre-existing quality-gate violations in the programming-principles and remote-systems-administration descriptions (imperative verb + negative boundary) so this PR's CI quality step passes; regenerated llms.txt and marketplace artifacts Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> * test(evals): add eval manifests to modified skills for ratchet The eval-coverage ratchet requires schema-valid eval manifests for any skill modified once coverage is past 50%. This PR modifies programming-principles and remote-systems-administration (splitting their oversized references), so add evals/evals.json to both: - programming-principles: 6 output-quality cases (task-to-book mapping, principled code review, refactor-vs-rewrite, no-op detection, rule distillation, principle conflicts) - remote-systems-administration: 6 output-quality cases (discovery before change, smallest control plane, rollback planning, platform identification, verification evidence, escalation on missing authority) Coverage: 87/145 (60.0%) schema-valid; ratchet clean. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com> --------- Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
Programming Principles — 14 Classic Software Books
Distilled coding principles from 14 classic software engineering books, organized for agent consumption. Cross-cutting principles by concern, task-to-book mapping, per-book rule sets at two depths, and a structured code-assessment workflow.
Why Install This Skill
When your agent loads this skill, it gains a shared vocabulary for code quality grounded in established literature rather than vibes. That means:
- Principled code review — findings cite specific books and principles, not just "this looks wrong"
- Task-aware loading — a task-to-book mapping table tells the agent which principles matter for the current work (refactoring? load Refactoring + WELC. architecture? load APoSD + Clean Architecture)
- Progressive depth — SKILL.md has enough to change decisions; reference files provide per-book depth on demand
- Structured assessment — a reproducible workflow for combining all 14 books against a real repo
What You Get
| Directory | Purpose |
|---|---|
SKILL.md |
Cross-cutting principles by concern, task-to-book mapping, per-book compressed rule cards, compatibility guide |
references/*.mini.md |
14 per-book mini rule sets with triggers, decision rules, and checklists |
references/*.full.md |
14 complete rule catalogs (11–63 KB each) for deep reference or audits |
references/code-assessment-workflow.md |
Structured workflow for combining all books against a real repo |
Triggers
Load this skill for code review, refactoring, implementation quality assessment, architecture decisions, or any coding task where you want principled guidance rather than ad-hoc judgment. Also load when performing a structured code assessment against a repository.
Requirements
Platform-agnostic. Works with any agent that supports the Agent Skills directory format. No external dependencies.
Quick Start
Load SKILL.md for the core principles and task-to-book mapping. When a specific book's guidance is needed, load the corresponding references/<book>.mini.md. For deep audits, load the .full.md variant.