Skip to content

feat(skills): bundle the llm-skills skill with validation, project-check and scan scripts - #90

Merged
roxblnfk merged 2 commits into
masterfrom
feat/llm-skills-skill
Nov 20, 2026
Merged

roxblnfk merged 2 commits into
masterfrom
feat/llm-skills-skill

Conversation

@roxblnfk

@roxblnfk roxblnfk commented Nov 20, 2026 •

Copy link
Copy Markdown
Owner

🔍 What was changed

  • llm/skills now ships its own skill, llm-skills (resources/skills/llm-skills/, declared via extra.skills.source). Consumers receive it like any other donor skill; it is user-invoked only (disable-model-invocation: true).
  • The built-in trust entry llm/* is narrowed to llm/skills: the plugin only needs to trust itself, not every future package under the llm vendor.
  • SKILL.md is a table of contents; references cover setup and skills.local.json, commands beyond --help, remote/dir sources and the skill lifecycle, publishing and internal skills, trust and how to widen or lock it, auditing third-party skills (manual checklist, Cisco skill-scanner, NVIDIA SkillSpector, Snyk agent-scan), finding skills, writing skills (with a pointer to mattpocock/skills → writing-for-agents), and troubleshooting.
  • Three dependency-free PHP scripts in the skill: validate-skill.php (Agent Skills spec + the plugin's own name/frontmatter rules), check-project.php (config validity, git hygiene of target/aliases/skills.local.json, a package's shipped skills), scan-skill.php (deterministic security pre-screen: invisible Unicode, pipe-to-shell, secret reads, injection phrasing, binaries).
  • CLAUDE.md → AGENTS.md, with a rule that the bundled skill is updated together with any behaviour change.

Why?

Consumers only get src/, resources/ and bin/ in the dist archive, so the README never reaches them or their agents. The skill gives an agent in a consumer project an accurate manual of the installed version plus checks it can run.

Review notes

  • The skill describes the code's actual behaviour where README/schema/messages disagree: bare * is rejected as a pattern (README and the untrusted-skip hint suggest --trust=* and extra.skills.trusted), the schema says --no-scripts suppresses auto-sync (it does not), the discovery-off hint names extra.skills.discovery, a local trusted-replace: false / vendor-sources: true re-opens trust, and declared source subfolders without SKILL.md are still installed. Worth fixing in the plugin separately; troubleshooting.md then needs the matching edit.
  • The sandbox now receives llm-skills from the path-installed plugin, so three trust tests list it in their expected sets.

Checklist

  • How was this tested:
    • Full testo run locally (Unit, Feature, Acceptance) green
    • Feature tests for all three scripts added; a guard test keeps the bundled skill valid
    • Acceptance test that the plugin installs its own skill with scripts
    • Scripts run manually against this repo, the sandbox and a real skills directory

…eck and scan scripts

test(skills): cover the bundled skill scripts end to end
docs: move the agent guide to AGENTS.md

Consumers get a user-invoked manual for everything around skills (setup, publishing, trust, audit, discovery, authoring) plus deterministic PHP checks, since the README does not ship in the dist archive. The package now declares `extra.skills.source`, so the skill arrives through the usual built-in `llm/*` trust.

Assisted-By: Claude Opus 5.5
The plugin only needs to trust itself; a vendor-wide pattern would also trust any future package published under `llm/`.

Assisted-By: Claude Opus 5.5
@roxblnfk
roxblnfk merged commit 857d808 into master Nov 20, 2026
16 checks passed
@roxblnfk
roxblnfk deleted the feat/llm-skills-skill branch November 20, 2026 11:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant