Skills

Add a skill

1. Create a folder in .agents/skills/. The folder name is the skill’s name, such as api-auth.
2. Add a SKILL.md to the folder. As the Agent Skills format requires, it starts with frontmatter that repeats the name and gives a description of when to use the skill.
3. Write the procedure below the frontmatter.
4. List the skill under skills in each check that needs it.

.agents/skills/api-auth/SKILL.md

---
name: api-auth
description: How route handlers authenticate and authorize requests.
  Use when checking a route's access control.
---
# Checking a route's access control

1. Find the handler in src/routes/ and the middleware its router
   applies.
2. requireAuth() from src/auth/middleware.ts must run before the
   handler reads the request.
3. Routes under /admin also need requireRole('admin').
4. A handler that takes an :orgId parameter calls
   assertMember(user, orgId) before its first query.

Routes listed in src/routes/public.ts are public by design.

• Skill names use lowercase letters, digits, and single hyphens, up to 64 characters.
• Each skill is a folder with a SKILL.md. HeyDeer loads the whole folder the way the Agent Skills format describes, including files that SKILL.md refers to.
• HeyDeer reads skills from the pull request, so a pull request can add or change the skills its own review uses. See What a pull request can change.

List skills in a check

Add the skill names under skills in the check’s frontmatter, as one name or a list:

.agents/checks/route-auth.md

---
files: "src/routes/**"
skills: [api-auth]
---
Every new or changed route handler checks authentication and
authorization before it reads the request.

• Skills are guidance. If a listed skill is missing, HeyDeer still performs the check from its instructions.
• A matching check that lists an invalid skill name is invalid. HeyDeer skips that check, reports it under Review notes, and continues the review.

Already using .claude/skills?

Add a symlink so the same skills are also in .agents/skills. You don’t need to move them:

mkdir -p .agents
ln -s ../.claude/skills .agents/skills
git add .agents/skills