android / android/skills

[Bug] Skills fail validation against agentskills.io Validators

Open
#23 0 comments 2 reactions 0 assignees View on GitHub
bug
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.