Module 02 / Lesson 02
Audit Vercel Agent Skills and Write Your Own SKILL.md
Treat your AI coding agent like an engineer who needs a clear handbook, an organized desk, and a safe sandbox.
You wouldn’t dump a 500-page operational manual into every short conversation with a teammate, nor would you let an intern run experimental tests directly on your production branch. When you connect too many tools or paste huge documents into an AI session, its memory context fills up, causing it to ignore earlier rules and make random mistakes.
Read the narration transcript
Find out why the incident form waits twice
I open the Publish form and watch the request timeline. The incident loads first.
Only then does the request for available services begin. I want a reviewer to tell me whether that second request actually depends on the first.
Both reads depend on the verified organization. If neither needs the other result, we can consider starting them together, after we know the organization.
Inspect the skill you want to add
The Vercel React skill gives us a good term for this, a request waterfall. We can read the relevant check in the official repository.
Before installing a skill, open its instructions, references, and scripts. Ask which files it can read and which commands it might run. If I only need the guidance, I can apply it directly.
Give the database change its own skill
I use Vercel’s React skill when the incident form fetches data twice in a row. Before adding it, I read its license, instructions, and any scripts. The project can keep that guidance available without pasting it into every chat.
The app’s own skill handles a different job. If we add scheduled maintenance, it asks for a versioned SQL migration, a review of who can read or change the new rows, and regenerated TypeScript types.
I open a fresh session and ask for a plan for that table. It should choose the migration skill and name its checks. I review the files and results before trusting any write.
Run the review before changing the code
In a fresh session, ask the agent to review the service picker. Verify that it identifies the right procedure and file.
Then compare the actual start times. Try a rejected save and check the draft still exists. Dismiss the form by keyboard and check where focus goes. Those results are what I want in the review.
The everyday problem
The incident form pauses while opening. The service picker waits for an incident request before it starts. A Vercel React skill can help you investigate, but downloading the entire skill collection before reading it adds scripts and advice you haven’t reviewed.
We’ll use third-party React guidance for this performance question, then author a different skill for a recurring database task. The two examples show when to apply a published recipe and when to write one for the repo.
Why the agent got it wrong
A request waterfall happens when one request begins only after another ends. Some waterfalls are required. A request may need the first request’s result or its authorization decision. A generic prompt to make the page faster gives the model room to optimize the wrong request or accidentally remove that dependency.
A skill narrows the task by describing when advice applies and what success looks like. The skill file can also refer to executable scripts. Check what the agent could run before giving the skill permission to do more than read.
The tool and technique
Open the Vercel Agent Skills repo before you install. Read the license, the relevant SKILL.md, its scripts/ and references/ if present, and the permissions or dependencies it expects. If you need one principle, you can use the documented principle without installing a pack.
After review, the project-scoped npx skills add vercel-labs/agent-skills workflow lets you select guidance for your client. Apply the request-waterfall check by reading the Network panel. Compare request start times and find the actual dependency before asking the agent to move a fetch.
Give the reviewer one repeatable procedure
Use the Vercel React skill to investigate dependent requests in the form. For another repeatable task, write a project skill that plans new database tables. Review the license, instructions, references, scripts, and permissions before enabling a third-party skill. Treat a bundled script like code you are about to run under your own environment’s permissions.
# After reviewing the source, choose only the React guidance you need. npx skills add vercel-labs/agent-skills Use the React skill to review the incident form’s network timeline. Cite the dependent calls and propose a check before editing. Use status-app-migration to plan a scheduled_maintenance table. Show the migration path, Row-Level Security policy review, and type generation. Wait for approval before applying anything to the disposable local stack.
Ask for the maintenance change in a fresh session and check which skill is selected. Review the SQL, organization access, and generated types separately. For the React review, check the network timeline before changing fetch order.
On screen in the status app
For the custom skill, the before example asks for scheduled maintenance and leaves schema decisions to the agent. The after example gives the plan a home at .agents/skills/status-app-migration/SKILL.md. Its name and description say when to load it. The body records the decisions and checks the plan should include.
Tell the agent to propose the table name, owning organization, related service, and what existing records need. Ask for the SQL migration path, access policy review, and generated TypeScript types. In this walkthrough the reviewer approves the plan before it runs against a disposable local database. Keep production credentials out of the example.
.agents/skills/status-app-migration/SKILL.md
Before
Add scheduled maintenance. Use whatever tables and app logic you think we need.
After
--- name: status-app-migration description: Plan new or changed status-app tables, organization access, and generated types. --- 1. Name the data owner, relationships, and existing-record behavior. 2. Propose a tracked SQL migration and list the access rules to review. 3. Stop for review before applying the migration to a disposable local database. 4. Regenerate local TypeScript types and report the actual checks and results.
What to watch for
A downloaded skill may have changed since a teammate last used it. Read the version you plan to add and inspect the scripts it asks the agent to run. Where permissions support it, keep write and network access limited to what the task requires.
Treat a new SKILL.md as instructions you can test, with no promise that every client selects it automatically. A broad description like “writes good code” is hard for the client to match. A clear description like “plan database tables and check row access” gives it a testable purpose.
How you know it worked
Open a fresh session and ask for a plan for scheduled_maintenance. Look for the specific skill, a reviewed migration path, a membership decision, and the type generation command. If it begins changing files without presenting a plan, tighten the stop point and check the client’s permission settings.
For the separate React example, open the form again and compare request start times on the same test path. Check that moving an independent read preserved permission and error behavior. The evidence belongs next to the suggested improvement.