[Bug] Skills fail validation against agentskills.io Validators
- Dominant language
- Python
- Stars
- 7.3k
- Forks
- 476
- Avg merge
- 8h 59m
- Merged PRs (30d)
- 7
Description
### Affected Skill
jetpack-compose/migration/migrate-xml-views-to-jetpack-compose
navigation/navigation-3
performance/r8-analyzer
play/play-billing-library-version-upgrade
system/edge-to-edge
### Description
Running the skills against a Skill that validates Skills against the agentskills.io specification, there are several potential violations of the specification. Particularly with the nested levels of the documents in the references folder. The specification it self says, "Keep files one level deep".
https://agentskills.io/specification#file-references
Also there is inconsistent uses of the `./references` or `references/` directory structures.
The `system/edge-to-edge` could be broken up into a references file for the examples, so that it saves on token usage, and the examples are only loaded when needed instead of loading when the body is read.
### Expected Behavior
The skills to validate and pass the skill validation python script, or a Skill validator like: https://gist.github.com/kingargyle/37e279f27880e7a92253e5f7e7686720
### Actual Behavior
Several violations of the report.
### Steps to Reproduce
Run the skill validator from agentskills.io or create your own validator to validate the skills being contributed to the repository.
### Suggested Fix
See above. Keep in mind one of the advantages to skills is token optimization. Try to follow expected best practices, like Skill bodies are 500 lines, anything else goes to a references file.
The skills as they stand currently are heavy token users and violoate several industry best practices and specification guidelines.
See:
https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#progressive-disclosure-patterns
https://agentskills.io/specification#progressive-disclosure
Contributor guide
Research direction
Start by running the agentskills.io validator, or the validator linked in the issue, against the five affected skill paths. Compare reported violations with the file-references and progressive-disclosure specifications, including nested references and inconsistent directory forms. Done means the affected skills validate successfully and large examples are moved to references where appropriate.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- tooling
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 52/100