Skill Packaging Lint

• npm run lint:skills
• npm run lint:skills -- .agents/skills/pi-sdk-docs
• npm run lint:skills -- --json

The implementation lives at:

• scripts/lint-skills.ts
• src/skill-lint.ts
• test/skill-lint.test.ts

What to check

Required structure

• SKILL.md exists
• if the skill references packaged resources, those paths exist
• if sources.md exists, its referenced packaged paths exist

Frontmatter

Check for:

• name
• description
• license if the repo expects it
• consistency between frontmatter name and directory name

Reference integrity

Check for:

• broken local markdown links
• stale packaged paths in backticks such as reference/..., references/..., scripts/..., assets/..., or sources.md
• wildcard references that no longer match any packaged files

Stale metadata

Look for signs that the skill was moved or refreshed incompletely, for example:

• references to old directories
• stale provisional/version-pin notes
• stale repository-context claims that no longer match the repo

Output format

Keep the report concise and structured:

• overall result
• per-skill status
• findings grouped by category
• explicit file paths
• whether the pass was read-only

If there are no issues, say so clearly.

Fix pass guidance

Only move from linting to edits if the user asks.

When fixing:

1. repair broken packaged paths and local links
2. refresh stale repo-context or version-drift language
3. rerun the same read-only lint pass
4. report what changed and whether the skill is now clean

Notes

• Prefer deterministic script results over ad-hoc manual inspection when a repo script exists.
• If the script and your manual inspection disagree, report the discrepancy explicitly.
• Treat lint output as evidence, then add concise judgment rather than restating raw output verbatim.