Vibe Coding Insider

AI coding assistants are useful for one-off questions, but many development tasks are not one-off tasks. A team may follow the same testing procedure before every release, use a specific format for code reviews, or require certain checks whenever a database migration is created.

Repeating those requirements in every prompt is inefficient. Putting all of them into a permanent instruction file is not always ideal either, because the assistant may receive irrelevant information for tasks that do not need it.

This is the problem that Agent Skills are designed to solve.

A skill packages reusable instructions, supporting files, examples, and optional scripts into a folder. Claude Code or GitHub Copilot in Visual Studio Code can discover that folder and load its contents when the current task matches the skill’s purpose. Both environments support the open Agent Skills format, which makes it possible to share some skills across tools.

This guide explains what skills are, how they differ from ordinary project instructions, how to configure them in Claude Code and Visual Studio Code, what benefits they provide, and what security issues require attention.

What Is an Agent Skill?

An Agent Skill is a directory that contains a required file named SKILL.md. That file describes:

what the skill does,
when the agent should use it,
what steps the agent should follow,
and which supporting resources are available.

A simple skill might contain only one file:

review-changes/
└── SKILL.md

A more advanced skill can include templates, examples, reference documents, or executable scripts:

review-changes/
├── SKILL.md
├── checklist.md
├── examples/
│   └── sample-review.md
└── scripts/
    └── collect-diff.sh

The SKILL.md file normally begins with YAML frontmatter followed by Markdown instructions:

---
name: review-changes
description: Reviews modified source files for bugs, missing tests, and risky changes. Use when checking a diff or preparing a pull request.
---

# Review changed files

Inspect the current changes.

Check for:

1. Incorrect behavior
2. Missing error handling
3. Security-sensitive changes
4. Missing or outdated tests
5. Unnecessary complexity

Report findings by severity and include file references.

The description is especially important. The agent uses it to decide whether the skill is relevant to the user’s request. A vague description such as “helps with code” gives the agent little information. A description that explains both the capability and its triggering situations is more reliable. Anthropic’s authoring guidance specifically recommends describing what the skill does and when it should be used.

Skills, Project Instructions, Prompts, and Custom Agents Are Not the Same

Several AI customization features may appear similar, but they solve different problems.

Project instructions define rules

Files such as CLAUDE.md, .github/copilot-instructions.md, or other custom instruction files usually contain standards that should affect many or all requests.

Examples include:

Use TypeScript strict mode.
Do not edit generated files.
Run the formatter before finishing.
Prefer the project logger over console.log.

These are persistent project rules.

Skills define reusable procedures

A skill is better suited to a task-specific workflow:

prepare a release,
review an API migration,
diagnose a failed integration test,
generate a project-specific component,
or verify documentation before publishing.

Unlike always-on instructions, a skill’s full body is generally loaded only when it is needed. This reduces unnecessary context usage and keeps unrelated instructions out of ordinary conversations.

Prompt files are manually selected starting points

A reusable prompt usually helps initiate a known task, but it may not include an entire folder of scripts, examples, and references. Skills can provide a more complete operational package and may be selected automatically when their descriptions match the request.

Custom agents define broader roles

A custom agent can have a specialized identity, tool configuration, or responsibility, such as a planning agent or security-review agent. A skill is usually narrower. It teaches an agent how to perform one repeatable capability.

A useful rule is:

Put permanent rules in instructions, repeatable procedures in skills, and broader responsibilities in custom agents.

How Skills Work in Claude Code

Claude Code supports skills stored at personal, project, nested-project, and plugin-related locations. A project skill can be placed under:

.claude/skills/<skill-name>/SKILL.md

A personal skill that should be available across projects can be stored under:

~/.claude/skills/<skill-name>/SKILL.md

Claude Code reads skill names and descriptions so that Claude knows which capabilities are available. When a request matches a description, Claude may load the skill automatically. A user can also invoke a skill directly by typing its slash-command name, such as:

/review-changes

Claude Code also supports features beyond the basic open format, including direct invocation controls, dynamic context injection, argument passing, tool permissions, and execution in a separate subagent context.

Creating a Claude Code skill manually

Create a project-level directory:

mkdir -p .claude/skills/review-changes

Then create:

.claude/skills/review-changes/SKILL.md

Add the frontmatter and instructions:

---
name: review-changes
description: Reviews current repository changes for bugs, regressions, missing tests, and unsafe assumptions. Use before committing or opening a pull request.
---

# Change review procedure

1. Inspect the repository status.
2. Read the complete diff.
3. Identify behavior changes.
4. Check whether tests cover those changes.
5. Look for hardcoded secrets, unsafe input handling, and accidental debug code.
6. Report only actionable findings.

For each finding, include:

- severity,
- file and location,
- explanation,
- recommended correction.

If no meaningful issue is found, say so clearly.

Start Claude Code from the repository:

claude

You can allow Claude to select the skill automatically:

Review my current changes before I commit them.

Or invoke it directly:

/review-changes

Claude Code watches existing skill directories for changes to SKILL.md, so edits can normally take effect during the current session. If the top-level skills directory did not exist when the session started, restarting Claude Code may be necessary for discovery.

How Skills Work in Visual Studio Code

In Visual Studio Code, Agent Skills are used by GitHub Copilot’s agent features. VS Code supports skills in several repository locations:

.github/skills/
.claude/skills/
.agents/skills/

It also supports personal skills in locations including:

~/.copilot/skills/
~/.claude/skills/
~/.agents/skills/

This overlap is useful. A repository skill stored in .claude/skills/ can be discovered by both Claude Code and current VS Code Agent Skills support, provided the skill stays within the features understood by both tools.

Visual Studio Code also provides an Agent Customizations editor. Open the Command Palette and run:

Chat: Open Customizations

Alternatively, enter the following in Copilot Chat:

/skills

From the Skills section, you can create either a workspace skill or a user-level skill. VS Code creates the directory and opens its SKILL.md file for editing. The editor can also generate a skill through /create-skill, although the generated instructions should still be reviewed carefully before use.

Creating a skill through the VS Code interface

Open the project in Visual Studio Code.
Open the Chat view.
Select the customization or gear control.
Open the Skills section.
Select New Skill (Workspace).
Choose a supported location.
Enter the skill name.
Complete the SKILL.md frontmatter and instructions.
Add supporting files when necessary.
Test the skill in an agent-mode conversation.

A basic VS Code-compatible skill looks like this:

---
name: review-changes
description: Reviews repository changes for bugs, missing tests, and risky implementation choices. Use before a commit or pull request.
---

# Instructions

Review the modified files and identify actionable issues.

Prioritize:

1. Functional defects
2. Security problems
3. Data-loss risks
4. Missing tests
5. Maintainability problems

Include file references and practical corrections.

You can then ask:

Use the review-changes skill to inspect my work.

Depending on the available interface and configuration, the skill may also be exposed as a slash command.

Step-by-Step Example: Build One Skill for Both Tools

The following example creates a reusable documentation-checking skill. It will check whether code changes require updates to project documentation.

Because both Claude Code and VS Code recognize .claude/skills/, that directory is a practical choice for a shared repository skill.

Step 1: Create the directory

From the project root, run:

mkdir -p .claude/skills/check-docs/examples

The structure will become:

.claude/
└── skills/
    └── check-docs/
        ├── SKILL.md
        └── examples/
            └── report-example.md

Step 2: Write a clear description

Create .claude/skills/check-docs/SKILL.md:

---
name: check-docs
description: Checks whether source-code changes require README, API documentation, configuration examples, or migration notes to be updated. Use during code review, before a release, or when preparing a pull request.
---

# Documentation impact review

Review the current code changes and determine whether they affect documented behavior.

## Procedure

1. Identify public behavior changed by the implementation.
2. Check the README and documentation directories for related explanations.
3. Check configuration examples and environment-variable samples.
4. Check whether an API, command, option, or file format changed.
5. Check whether users need migration instructions.
6. Compare the result with [the example report](./examples/report-example.md).

## Output

Produce the following sections:

- Summary
- Documentation updates required
- Files that should be reviewed
- Suggested wording
- No-update justification

Do not edit documentation automatically unless the user explicitly requests edits.

When no update is needed, explain why.

This description contains both the capability and its intended trigger situations. It is more discoverable than a description such as “checks documentation.”

Step 3: Add an output example

Create .claude/skills/check-docs/examples/report-example.md:

# Example documentation impact report

## Summary

The new timeout option changes user-configurable behavior.

## Documentation updates required

Yes.

## Files that should be reviewed

- README.md
- docs/configuration.md
- .env.example

## Suggested wording

Document the default timeout, accepted values, and behavior when the limit is reached.

## No-update justification

Not applicable.

Supporting files are not automatically useful merely because they exist. The main SKILL.md should reference them explicitly with a relative link so the agent knows when to read them. VS Code’s documentation calls out this requirement for additional resources.

Step 4: Test automatic selection in Claude Code

Start Claude Code in the repository:

claude

Make a small change to a public configuration option, then ask:

Do my current changes require any documentation updates?

The request closely matches the skill description, so Claude may select check-docs automatically.

Test direct invocation as well:

/check-docs

Check whether the result follows the requested report structure and consults the example file.

Step 5: Test the same skill in VS Code

Open the same repository in Visual Studio Code.

Open Copilot Chat in an agent-capable mode and enter:

Check whether these changes require documentation updates.

You can also be explicit during initial testing:

Use the check-docs skill and review the current changes.

Confirm that the skill appears in the Skills configuration interface and that the output follows the defined sections.

Step 6: Test negative cases

A skill should not activate for every vaguely related request. Try prompts that should not require it:

Explain how this private helper function works.

Rename this local variable.

If the documentation skill activates too frequently, narrow its description. For example, emphasize public behavior, release preparation, configuration changes, and pull-request review.

Step 7: Put the skill under version control

Commit the skill with the repository:

git add .claude/skills/check-docs
git commit -m "Add documentation impact review skill"

Team members can now use the same procedure instead of recreating it in personal prompts. Changes to the review process can be reviewed through ordinary pull requests.

Benefits of Using Skills

Less repetitive prompting

A carefully written skill replaces long instructions that developers would otherwise paste into multiple conversations. The user can ask for the task by intent rather than restating the entire procedure.

More consistent results

A skill can define required checks, ordering, output structure, and verification steps. This does not guarantee identical answers, but it gives the agent a stable procedure to follow.

More efficient context use

Always-on instructions consume attention even when they are unrelated to the current task. Skill content loads on demand, allowing detailed procedures and references to remain outside the active context until needed.

Easier team sharing

Repository skills can be reviewed, versioned, tested, and improved like source code. This makes workflow knowledge less dependent on one developer’s private prompt collection.

Portability between compatible agents

The core Agent Skills structure is an open standard. A well-designed skill that uses basic frontmatter, Markdown instructions, and referenced resources can work across compatible environments. However, tool-specific extensions may reduce portability.

Support for deterministic helper scripts

Natural-language instructions are flexible, but some tasks are better handled by code. A skill may include a validation script, parser, or formatting utility and instruct the agent when to run it.

For example:

api-contract-check/
├── SKILL.md
└── scripts/
    └── validate-schema.py

A script can make repeatable checks more reliable, provided its dependencies, permissions, inputs, and expected output are clearly documented.

Important Limitations and Security Risks

Skills should be treated as executable workflow packages, not harmless text snippets.

Review third-party skills before installation

A downloaded skill may instruct the agent to run commands, read files, connect to services, or modify a project. Examine the entire directory, including scripts and linked resources, before enabling it.

VS Code’s documentation specifically recommends reviewing shared skills and applying strict controls to terminal command approval.

Be cautious with command execution

Avoid scripts that:

delete files broadly,
upload repository contents,
print environment secrets,
modify global system settings,
install unverified packages,
or bypass normal review steps.

Prefer read-only inspection first. Require explicit confirmation for destructive or externally visible actions.

Never store secrets in a skill

Do not place API keys, access tokens, passwords, private certificates, or production credentials inside SKILL.md, scripts, examples, or templates.

Use the project’s approved secret-management method and refer to environment-variable names rather than including secret values.

Keep instructions focused

An oversized skill can become difficult for both humans and agents to navigate. Anthropic recommends keeping the main SKILL.md body below roughly 500 lines and moving longer details into referenced files through progressive disclosure.

Avoid fragile environment assumptions

A script may work on one developer’s computer but fail elsewhere because a package, shell, runtime, or command is missing.

Document:

required runtimes,
supported operating systems,
package dependencies,
expected working directory,
input files,
output files,
and failure behavior.

Do not confuse automatic selection with guaranteed execution

A matching description improves the likelihood that an agent will select a skill, but natural-language matching is not perfectly deterministic. Critical workflows should be invoked explicitly and verified.

Tool-specific features may break portability

Claude Code supports extensions such as dynamic command output, invocation controls, arguments, and subagent execution. A skill that depends heavily on those features may not behave identically in VS Code.

For a cross-tool skill, keep the shared core simple:

standard YAML frontmatter,
clear Markdown procedures,
relative links,
portable scripts,
and explicit verification steps.

Add platform-specific variants only when the additional capability is truly necessary.

Skills do not replace human review

A skill can make an agent more consistent, but it cannot guarantee that code is correct, secure, compliant, or production-ready. Review diffs, test outputs, commands, and generated files before accepting changes.

Practical Skill-Writing Guidelines

A useful skill usually has five qualities.

First, it solves one recognizable problem. “Prepare a Node.js package release” is clearer than “help with development.”

Second, its description includes trigger language that a user is likely to use. Terms such as “before release,” “review migration,” or “debug integration tests” improve automatic matching.

Third, the procedure has an observable completion condition. The skill should explain how the agent knows that the task is finished.

Fourth, risky actions are separated from safe analysis. A skill may inspect a deployment configuration automatically but should not deploy to production without explicit authorization.

Finally, the output is easy to review. File references, severity labels, checklists, and validation summaries help users judge whether the agent followed the procedure.

Conclusion

Agent Skills turn repeated prompting into reusable, version-controlled workflows. In Claude Code, they can be loaded automatically or invoked as slash commands, with additional options for dynamic context and subagent execution. In Visual Studio Code, GitHub Copilot can discover compatible skills from supported project or user directories and apply them during agent tasks.

The most practical cross-tool approach is to begin with a small repository skill under .claude/skills/. Give it a precise description, keep its main instructions focused, link supporting resources explicitly, and test both matching and non-matching prompts.

The greatest benefit is not simply that an agent can perform more tasks. It is that a team can define how a recurring task should be performed, inspect that procedure, improve it over time, and reuse it without rebuilding the prompt from the beginning.

FAQ

Can the same skill work in Claude Code and Visual Studio Code?

Yes. Both currently support the Agent Skills format and recognize skills stored under .claude/skills/. Basic skills made from standard frontmatter, Markdown instructions, and relative resources are the most portable. Claude Code-specific extensions may not behave the same way in VS Code.

Should every project rule become a skill?

No. Rules that should apply broadly belong in project instructions. Skills are better for detailed procedures that are needed only for certain tasks.

Should skills include scripts?

Only when a script makes the workflow more reliable or verifiable. Keep scripts narrow, document their dependencies, handle errors clearly, and review their security implications before allowing an agent to execute them.

Why is my skill not activating automatically?

The description may be too vague, may lack terms used in the request, or may compete with similar skills. Confirm that the directory and SKILL.md name are valid, make the description more specific, and test direct invocation before testing automatic selection.

Are skills safe to download from another repository?

Not automatically. A skill may contain scripts or instructions that access files and execute commands. Review every file and use restrictive command-approval settings before running an unfamiliar skill.

Agent Skills in Claude Code and Visual Studio Code: Setup, Benefits, Risks, and a Step-by-Step Example