mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-21 08:36:33 +03:00
3eb7bd4096
* 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>
Agent Skills — The Standard Itself
This skill is the meta-skill: it documents the Agent Skills open format itself. Every other skill in this repository follows the conventions defined here.
Why Install This Skill
When your agent loads this skill, it gains the ability to create, review, and edit valid Agent Skills-format skills. That means:
- Your agent can build new skills on demand. Describe a workflow you want encoded, and your agent can scaffold a valid SKILL.md with correct frontmatter, progressive disclosure structure, and agent-friendly descriptions.
- Existing skills stay valid. When your agent edits a skill, it checks against the format standard — no broken frontmatter, no missing required fields.
- Consistency across your skill library. Every skill in your repository follows the same conventions, making them loadable by any Agent Skills-compatible harness.
What You Get
| Directory | Purpose |
|---|---|
SKILL.md |
A create-and-review workflow, the core format rules, and a completion checklist |
references/specification.md |
A bundled snapshot of the official format specification |
references/best-practices.md |
Guidance for useful, well-scoped instructions |
references/optimizing-descriptions.md |
How to design and test reliable automatic triggers |
references/using-scripts.md |
How to bundle safe, agent-friendly executable helpers |
references/evaluating-skills.md |
A practical evaluation loop for testing skill quality |
references/client-implementation.md |
Guidance for products that discover and load skills |
Quick Start
Ask your agent to create or review a skill, then load this skill first. For a structural check, run:
skills-ref validate path/to/skill
If the reference validator is not installed, your agent should report that clearly and complete the equivalent manual checks.
Triggers
- You're creating a new skill and need to know the correct format
- You're reviewing an existing skill for format compliance
- You want your agent to generate a valid SKILL.md scaffold
- You're setting up conventions for a shared skill repository
Requirements
The documentation itself has no runtime dependencies. Optional validation uses the skills-ref reference library; install it in an isolated environment when you want to run its CLI.