* 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>
4.6 KiB
Ansible: Safe Fleet Administration
Applicability: Load this reference for any Ansible task beyond a one-host ad hoc read. It governs inventory design, content structure, execution, review, testing, troubleshooting, and operational rollout.
This is a control-plane guide, not a bag of YAML. Ansible can apply a bad decision efficiently to every host in scope. Treat inventory, limits, credentials, concurrency, and verification as part of the change, not boilerplate around it.
The full reference is split into two parts so each file stays within the reference size cap. The table below routes you to the part that covers the section you need.
Parts of this reference
| Part | Scope |
|---|---|
| ansible-administration-and-safety.md | Sections 1-13: tool choice, installation, inventory, connection and privilege, content architecture, collections, secrets, execution model, failure and rollback, testing and CI, troubleshooting, platform boundaries, and performance |
| ansible-runbooks-and-advanced-operations.md | Sections 14-21: operational runbook, minimal production-shaped baseline, common state patterns, vault operations, operator command cookbook, quality gates, platform and execution-environment routes, and source-to-task routing |
Source index and freshness
This reference was refreshed from primary documentation on 2026-07-13. It deliberately avoids frozen support windows and release-specific defaults. Before acting on a version-sensitive detail, confirm it against the exact installed ansible-core, collection, connection plugin, and target platform documentation.
Primary sources consulted:
- Ansible installation
- Ansible configuration
- Inventory
- Dynamic inventory
- Connection details
- Variables
- Facts and magic variables
- General precedence
- Roles
- Handlers
- Strategies
- Check and diff mode
- Error handling
- Privilege escalation
- Vault
- Installing collections
- Verifying collections
- Windows management
- Network best practices
- Ansible configuration settings
- ansible-config
- Ansible FAQ
- Asynchronous actions and polling
- General tips
- ansible-lint usage
- ansible-lint rules
- Molecule playbook testing
- Molecule CI