Skip to main content

Agent Skill Practical Guide: Write Once, Reuse Across Platforms (Google Agent × Claude Code)

AI Development Guide1/15/25...About 5 minAI TechnologyAI AgentSkill DevelopmentGoogle AgentClaude CodeAutomationEngineering

Agent Skill Practical Guide: Write Once, Reuse Across Platforms (Google Agent × Claude Code)

If we say an Agent is a "thinking scheduler", then Skill is the real "working" capability unit of the Agent.

Although Google Agent (Antigravity) and Claude Code come from different vendors, they are highly consistent in Skill design philosophy:
Use structured instruction documents to solidify repeatable workflows into AI capability modules.

This article combines two official documentations to extract a set of universal, migratable, and practical Skill creation methodologies.

I. Unified Understanding: What is Agent Skill (Engineering Definition)

Throwing away platform differences, the essence of Skill is only one sentence:

Skill = Standardized operation procedure manual oriented towards Agent

It's not code function, nor Prompt, but:

  • Clearly describe when to use it
  • Regulate how to step by step
  • Constrain the form and quality of output

Google and Claude are almost completely consistent in implementation:

DimensionGoogle AgentClaude Code
Skill CarrierSKILL.mdSKILL.md
Activation MethodAutonomous matching descriptionAutonomous matching description
Execution ModelRead → Follow → ExecuteRead → Follow → Execute
Whether Explicit CallNoNo

Conclusion:

Skill is "engineering documentation for AI to read", not a manual for humans to read.

II. Minimum Structure of Skill (Cross-platform Universal)

A workable Skill only needs one file:

my-skill/
└── SKILL.md

Fixed Structure of SKILL.md

---
name: skill-name
description: Clearly describe when to use this skill
---

# Skill Title

## When to use this skill
## Instructions
## Examples (Strongly Recommended)
## Best Practices (Optional)

This structure simultaneously applies to:

  • Google Agent (Antigravity)
  • Claude Code
  • Most future Agent frameworks

III. Key to Skill Success: description

description determines whether Skill will be activated

This is the core point that both Google and Claude repeatedly emphasize.

Standards for a "Good description"

description: Analyze git diffs and generate conventional commit messages.
Use when the user mentions git, commit messages, version control,
or asks for help writing commit logs.

It must answer 3 things:

  1. What to do (Analyze / Generate / Review)
  2. What is the input (git diffs / files / logs)
  3. When to use (keywords + scenarios)

❌ Wrong example:

description: Help with git

✅ Correct example:

description: Generate conventional commit messages from git diffs.
Use when user asks for commit messages or mentions git commits.

IV. Correct Responsibility Boundary of Skill

Combining the two documentations, we can summarize a very important principle:

Skill is not responsible for "thinking", only for "executing according to steps"

Division of Labor Between Agent vs Skill

ModuleResponsibility
AgentUnderstand user intent, choose Skill
SkillProvide stable, reusable execution processes
LLMNatural language understanding and execution

Don't let AI play freely in Skill
Don't write "please judge by yourself" in Skill

V. A Cross-platform Universal Skill Instance

Example: Code Review Skill (Google / Claude Universal)

---
name: code-review
description: Review source code for bugs, style issues, and best practices.
Use when user asks for code review or quality check.
---

# Code Review Skill

## When to use this skill
- User asks to review code
- User wants to check quality, bugs, or best practices

## Instructions

Follow these steps strictly:

1. Read the target source file(s)
2. Check correctness and logic errors
3. Identify potential edge cases
4. Review coding style and conventions
5. Flag performance or security risks

## Output format

- Summary
- Critical issues (if any)
- Improvement suggestions

## Example

Input:
"Review UserService.java"

Output:
- 2 potential null pointer risks
- 1 performance issue in loop
- Naming convention mismatch in method getuser()

This Skill does not contain any platform-specific capabilities, yet can be correctly understood and used by both Agents simultaneously.

VI. 4-Step Method for Skill Creation (Practical Template)

Step 1: Select a "High-frequency Repeated Task"

Qualified Skill's typical sources:

  • Done in every project
  • Steps almost consistent every time
  • Very annoying for people to do, but rules are clear

For example:

  • Commit message generation
  • Code review
  • Log analysis
  • Documentation structuring

Step 2: Write Your "Brain Process" into Steps

Don't write principles, write operation sequences:

❌

Please carefully analyze code quality

✅

  1. Read file
  2. Check null pointers
  3. Check naming conventions
  4. Output problem list

Step 3: Add 1 Real Example

Google and Claude both explicitly point out:

Example is the part with lowest learning cost and strongest effect in Skill

Example can significantly reduce misuse probability.

Step 4: Reverse Verification of description

Ask yourself one sentence:

If I were AI, only looking at description, could I judge "whether to use this Skill"?

If not, rewrite.

VII. 5 Golden Practices for Skill Design (Fusion of Official Suggestions)

  1. One Skill does one thing
  2. description is written for AI, not for humans
  3. Steps must be executable
  4. Example > Abstract rules
  5. Skill can have no script, but cannot have no SOP

VIII. Why Skill is the Watershed of Agent Engineering

Agents that don't know Skill:

  • Pile up with Prompt
  • Unstable
  • Non-reusable
  • Difficult to collaborate
  • Hard to maintain

Agents that know how to design Skill:

  • Behavior stable
  • Reusable by team
  • Version manageable
  • Migratable across platforms

Skill is the key step for Agent to evolve from "chat tool" to "engineering system"

IX. What You Can Do Immediately Next

  1. Pick one from your most familiar workflows

  2. Write a SKILL.md

  3. Put it in both places at the same time:

    • .agent/skills/ (Google)
    • .claude/skills/ (Claude)

  4. Compare activation effects on both sides

  5. Iterate description and Examples

Conclusion

The upper limit of Agent is not the model, but the Skill design capability.
When you start to define AI's "working methods" in an engineering way, you have entered the level of Agent Skill creator.

Example

---
name: changelog-generator
description: Automatically creates user-facing changelogs from git commits by analyzing commit history, categorizing changes, and transforming technical commits into clear, customer-friendly release notes. Turns hours of manual changelog writing into minutes of automated generation.
---

# Changelog Generator

This skill transforms technical git commits into polished, user-friendly changelogs that your customers and users will actually understand and appreciate.

## When to Use This Skill

- Preparing release notes for a new version
- Creating weekly or monthly product update summaries
- Documenting changes for customers
- Writing changelog entries for app store submissions
- Generating update notifications
- Creating internal release documentation
- Maintaining a public changelog/product updates page

## What This Skill Does

1. **Scans Git History**: Analyzes commits from a specific time period or between versions
2. **Categorizes Changes**: Groups commits into logical categories (features, improvements, bug fixes, breaking changes, security)
3. **Translates Technical → User-Friendly**: Converts developer commits into customer language
4. **Formats Professionally**: Creates clean, structured changelog entries
5. **Filters Noise**: Excludes internal commits (refactoring, tests, etc.)
6. **Follows Best Practices**: Applies changelog guidelines and your brand voice

## How to Use

### Basic Usage

From your project repository:

Create a changelog from commits since last release

Generate changelog for all commits from the past week

Create release notes for version 2.5.0


### With Specific Date Range

Create a changelog for all commits between March 1 and March 15


### With Custom Guidelines

Create a changelog for commits since v2.4.0, using my changelog
guidelines from CHANGELOG_STYLE.md


## Example

**User**: "Create a changelog for commits from the past 7 days"

**Output**:
```markdown
# Updates - Week of March 10, 2024

## ✨ New Features

- **Team Workspaces**: Create separate workspaces for different
  projects. Invite team members and keep everything organized.

- **Keyboard Shortcuts**: Press ? to see all available shortcuts.
  Navigate faster without touching your mouse.

## 🔧 Improvements

- **Faster Sync**: Files now sync 2x faster across devices
- **Better Search**: Search now includes file contents, not just titles

## 🐛 Fixes

- Fixed issue where large images wouldn't upload
- Resolved timezone confusion in scheduled posts
- Corrected notification badge count

Inspired by: Manik Aggarwal's use case from Lenny's Newsletter

Tips

  • Run from your git repository root
  • Specify date ranges for focused changelogs
  • Use your CHANGELOG_STYLE.md for consistent formatting
  • Review and adjust the generated changelog before publishing
  • Save output directly to CHANGELOG.md
  • Creating GitHub release notes
  • Writing app store update descriptions
  • Generating email updates for users
  • Creating social media announcement posts