agents-guru

Tools used: Read / Grep / Glob to inspect existing skills, Write / Edit to author them, Bash(node:*) for the check in scripts/, which runs Vale with the prose rules in assets/, npm for the one-time install of what the check needs and for its suite and lint, skills for install and updates, and claude plugin validate for a plugin's sweep, all left out of allowed-tools so that each command prompts, Bash(gh:*) for repository visibility during export and, with git, for reading findings and fix commits when a phrase list grows.

This skill was invoked with the argument: $ARGUMENTS

This is a routing skill. Read $ARGUMENTS and the conversation context, pick exactly one workflow, read that workflow file, and follow its instructions inline.

All paths below are relative to this skill's own directory. Resolve them against wherever this skill is installed rather than assuming a location. A fenced command is different, because whoever pastes it stands in their own working directory rather than in the skill: there the skill's own files are named through <skill-dir>, the placeholder workflows/new.md defines for the directory this skill is installed to, and every workflow here uses that one placeholder rather than a bare scripts/... that runs only from inside the skill.

Where skills live

Keep one canonical copy in an agent-neutral location such as <home-dir>/.agents/skills/<name>/, and symlink each agent's skills directory to it as needed: one file then serves every agent, and no copy drifts. Each agent reads its own directory; Claude Code, for example, reads <home-dir>/.claude/skills/<name>/SKILL.md. When a workflow of this skill says "the skills directory", resolve it for the agent in use.

The facts every workflow here depends on

The description is the whole trigger surface

Only the frontmatter is read before a skill loads. As far as discovery is concerned the body does not exist, so every phrase that should cause the skill to fire has to appear in description:. A trigger documented only in the body will never fire, because nothing reads the body until something has already decided to load it.

The corollary matters when refactoring: moving a rule out of a global instructions file and into a skill only works if whatever made an agent reach for it survives in the description. Otherwise the rule is unreachable rather than relocated.

YAML eats the description at #

In an unquoted YAML scalar, a space followed by # starts a comment. Everything after it is discarded with no parse error, no warning, and a skill that still loads and still works. The only symptom is triggers that never fire.

description: Use when asked to review PR #N, or check what needs review.

Everything from the space before #N onward is gone. Backticks do not protect against it: a description containing `#123` survives only because the character before the # is a backtick rather than a space, which is luck, not correctness.

Write the description as a block scalar. It has no comment, anchor, tag or escape processing, so a trap that needs a plain or quoted value cannot reach it:

description: |
    Use when asked to review PR #N, or check what needs review.

Quoting also survives a space followed by #, but every quote style carries its own trap: inside "..." a backslash or an unescaped inner " is a parse error, inside '...' an apostrophe must be doubled, and curly “smart” quotes are not quotes at all, so a description that merely looks quoted still truncates. The family goes further, all verified against a real parser: a leading & or ! silently eats the first word, a duplicate description: key silently discards the first value, a bare yes becomes a boolean in some parsers, and a stray : or a leading *, [, {, % or @ is a parse error. A parse error is not loud in practice: the harness swallows it and the skill simply vanishes from the listing. workflows/check.md tests for all of these.

Then avoid a space followed by # in the prose anyway. Write "a numbered PR" rather than "PR #N", so the text stays safe under any later edit that changes the form.

Routing

Where $ARGUMENTS arrives unexpanded, read the argument from the conversation instead: whoever invoked the skill, the owner or an agent, named it last before this skill loaded. workflows/new.md owns the account of why a router owes that fallback.

Based on $ARGUMENTS, do exactly one of the following. Test the manage bullet before the others, so an install request is caught before an empty argument reaches check and before any verb its sentence opens with:

• If it starts with manage, or the request that invoked this skill is about installing, updating or removing a skill someone else wrote → read references/managing.md, but only when the owner typed /agents-guru manage. Any other way in stops here, an agent's own invocation and a request phrased as a sentence alike, and says that the owner types /agents-guru manage for that: that file installs software whose instructions then run with the agent's permissions.
• If it starts with new → read workflows/new.md and follow it.
• If it starts with review → read workflows/review.md and follow it. It owns how a path covering more than one skill is read.
• If it starts with check, or is empty → read workflows/check.md and follow it, passing every --skip <rule> the argument carries through to the command unchanged.
• If it starts with export → read workflows/export.md and follow it.
• If it matches no verb in this list → say so and name the verbs, rather than guessing which was meant. A mistyped verb and a verb this skill does not have look identical from here, and both are answered by printing the list.

Supporting files