Agent Skills are most useful when a task has a repeatable definition of done that is too detailed for a repository-wide instruction file. For a SaaS codebase, that usually means high-consequence work such as authentication, billing, or release verification. A good Skill tells an agent what to inspect, which boundaries it must preserve, which checks to run, and when to stop and ask for review.
This article gives you three small, copyable templates. They are deliberately narrow: they do not try to make an agent autonomous, and they do not replace code review or product-specific engineering. They make recurring work more consistent.
What a Skill adds beyond an agent contract
Use an AGENTS.md or equivalent repository contract for rules that apply to nearly every change: architecture, TypeScript conventions, protected areas, testing commands, and secret handling. Use a Skill for an infrequent but consequential workflow that needs deeper instructions only when it is relevant.
The Agent Skills specification defines a Skill as a directory with a SKILL.md file, with optional scripts, references, and assets. GitHub’s current documentation makes the same distinction: custom instructions suit broad, always-relevant guidance, while Skills package detailed instructions and resources for specialized tasks. See the Agent Skills specification and GitHub’s guidance on adding Skills.
A simple decision rule
- Put it in the agent contract when the rule applies to most work: feature boundaries, strict typing, default Server Components, or where secrets may live.
- Put it in a Skill when the task has a distinct input, review sequence, and verification command: changing sign-in behavior, touching payment-state code, or preparing a release.
- Keep it in human review when the decision needs product judgment, security sign-off, production access, or an irreversible action.
The goal is not a bigger prompt. It is a small operational interface: a name, an activation condition, a short procedure, concrete evidence to collect, and a safe failure path.
The reusable Skill shape
Each template below follows the same structure. The frontmatter lets an agent identify the workflow; the body says what success requires; and a small script gathers evidence without making a production change. Treat the paths and commands as placeholders: adapt them to the architecture and package scripts your repository actually has.
skill-name/
SKILL.md
scripts/
inspect-change.mjs
references/
review-checklist.md
Keep the entry point short. The Agent Skills specification recommends moving detailed material into referenced files so the agent can load it only when needed. That keeps normal tasks from carrying release or payment instructions they do not need.
Skill 1: review an authentication change
Use when: a change affects login, callbacks, session creation, account recovery, protected routes, or role checks. The immediate problem is that a visually correct sign-in change can still weaken a server-side access decision. The outcome is a reviewable change with explicit authentication and authorization checks.
SKILL.md
---
name: auth-change-review
description: Review authentication and authorization changes before merge.
---
# Authentication change review
Use this Skill only when a task changes sign-in, sessions, protected routes,
account recovery, or authorization.
1. Inspect the changed route, action, and nearest existing auth pattern.
2. List the authenticated actor, required role, and server-side enforcement point.
3. Confirm client components do not import server-only auth or database code.
4. Add or update a focused failure-path test.
5. Run the repository’s relevant lint and test commands.
6. Stop for human review if the change alters provider configuration,
session lifetime, recovery policy, or production secrets.
Run scripts/inspect-change.mjs before reporting completion.
scripts/inspect-change.mjs
import { execFileSync } from "node:child_process";
const files = execFileSync("git", ["diff", "--name-only", "HEAD"], {
encoding: "utf8",
}).trim().split("\n").filter(Boolean);
const sensitive = files.filter((file) =>
/(auth|session|callback|middleware|protected|role)/i.test(file),
);
console.log(JSON.stringify({ changedFiles: files, authRelatedFiles: sensitive }, null, 2));
if (sensitive.length === 0) process.exitCode = 2;
This script does not validate security. It only makes the scope visible, so the agent cannot quietly claim it reviewed an authentication change without naming the relevant files. A nonzero exit is a prompt to inspect the task, not a license to bypass the check.
Skill 2: protect payment boundaries
Use when: a change touches checkout, webhooks, entitlements, refunds, subscription state, or a payment provider adapter. The problem is not merely calling a provider API; it is preserving the relationship between a verified event, a durable internal state, and the user-facing result.
SKILL.md
---
name: billing-boundary-review
description: Review SaaS billing changes for provider boundaries and event state.
---
# Billing boundary review
Use this Skill for checkout, webhook, refund, entitlement, or subscription work.
1. Identify the external event, the internal state transition, and the actor
allowed to initiate the change.
2. Keep provider SDK calls behind the existing payment adapter.
3. Document duplicate-event behavior and the expected retry result.
4. Add a focused test for one valid transition and one rejected or duplicate path.
5. Run scripts/list-billing-files.mjs and the project’s relevant checks.
6. Stop if the change requires a live payment action, real customer data, or
a policy decision about refunds or access.
scripts/list-billing-files.mjs
import { execFileSync } from "node:child_process";
const output = execFileSync("git", ["diff", "--name-only", "HEAD"], {
encoding: "utf8",
});
const files = output.split("\n").filter((file) =>
/(billing|payment|checkout|webhook|subscription|entitlement)/i.test(file),
);
console.log(files.length ? files.join("\n") : "No billing-related files found.");
if (!files.length) process.exitCode = 2;
For example, Frontend Accelerator’s verified architecture keeps payment behavior behind a PaymentAdapter, while its canonical agent contract says features should not import payment-provider SDKs directly. That is the kind of local rule a billing Skill should reinforce, not replace.
Skill 3: verify a release candidate
Use when: a feature or bug fix is ready for a release-candidate review. The reader problem is a familiar one: a passing implementation check does not prove that documentation, environment configuration, routes, and the release artifact still line up. The outcome is a concise evidence bundle a human can review.
SKILL.md
---
name: release-candidate-check
description: Gather release evidence without publishing or changing production.
---
# Release candidate check
Use only for a proposed release. Do not publish, deploy, or modify production.
1. Read the release scope and identify affected user flows.
2. Run the documented lint, test, and build checks that apply to the change.
3. Inspect environment-variable documentation for any new server-side setting.
4. Record the exact commands, result, and any skipped check with a reason.
5. Run scripts/release-evidence.mjs.
6. Stop for a human if a check fails, production credentials are required, or
the release includes a migration, payment policy, or security-sensitive change.
scripts/release-evidence.mjs
import { execFileSync } from "node:child_process";
const status = execFileSync("git", ["status", "--short"], {
encoding: "utf8",
}).trim();
const head = execFileSync("git", ["rev-parse", "--short", "HEAD"], {
encoding: "utf8",
}).trim();
console.log(JSON.stringify({ head, workingTree: status || "clean" }, null, 2));
if (status) process.exitCode = 2;
That final guard matters. An agent should report a dirty working tree or a failed verification step as evidence, not tidy it by resetting, stashing, or changing unrelated files.
How to introduce Skills without instruction sprawl
- Start with one failure mode. Choose a workflow where repeated context loss is already costly, such as duplicate webhook handling or inconsistent authorization review.
- Write the stop conditions first. Name the actions the Skill must not take: deploy, change production data, use real customer records, expose secrets, or decide policy alone.
- Point to repository evidence. Link the Skill to existing adapters, test commands, and architecture documents. Do not copy a generic checklist that contradicts local conventions.
- Make the evidence machine-readable where practical. A small script that lists changed sensitive files is safer and more useful than a vague instruction to “check everything.”
- Review the Skill like code. Test its activation description against realistic prompts, inspect any script, and keep versioned dependencies or references explicit.
Where Frontend Accelerator fits
Frontend Accelerator includes a canonical AGENTS.md contract, tool-specific agent entry points, and curated project Skills under .agents/skills/, tracked by skills-lock.json. Its architecture rules are intentionally broad: feature modules own business behavior, the app directory focuses on routing and composition, and provider SDKs stay behind adapters. That makes Skills useful as a focused second layer for tasks such as testing, Stripe work, caching, or framework upgrades.
Recommendation: start from a codebase whose boundaries you can explain, then add Skills only where a repeatable workflow needs more operational detail. A Skill can improve consistency; it cannot make an unreviewed change safe by itself.
Get the sample Skills pack
The sample pack is the three copyable templates in this article. Put each in its own directory, replace the placeholder commands and paths with repository evidence, and test the stop conditions with a non-production task before relying on it for auth, billing, or release work.
A practical first rollout: choose one skill, run it on a small pull request, and compare its evidence with a normal review. Keep it only if it catches a missed boundary, speeds a justified check, or makes the handoff clearer. If it merely repeats generic advice, remove it and keep the repository contract concise.
