Agent Skills Concept Analysis and Usage

Decision Criteria:

• If it's "pure instructions" and less than 100 lines → System Prompt
• If it's "instructions + large reference materials" → Skill (Level 2 + Level 3)
• If it requires "deterministic execution" (e.g., data validation, format conversion) → Skill (Level 3 script)

2. Core Mechanism: Three-Level Loading (Progressive Disclosure)

The engineering design of Skills is ingenious: it acknowledges that the Context Window is still a scarce resource, so it adopts a "tiered loading" strategy.

Key Understanding: Level 1/2/3 do not refer to "content types," but rather "loading timing."

Level 1: Metadata (Always Loaded, Loaded at Startup)

Loading Timing: When the Agent starts. Token Cost: ~100 tokens/skill

yaml
---
name: postgres-schema-review
description: Review PostgreSQL schema designs for performance and best practices. Trigger when user asks about table design, indexing, normalization, or database optimization.
---

• Only name and description enter the System Prompt.
• Even with 100 Skills installed, it only consumes a few thousand tokens.
• Claude only knows "this Skill exists, and when to use it."

Level 2: SKILL.md Body (Loaded When Triggered)

Loading Timing: When a user request matches the description. Token Cost: Usually < 5000 tokens (recommended < 500 lines).

Key Mechanism: When a user request matches the description, Claude reads the SKILL.md file:

bash
# Automatically executed by Claude
cat /path/to/skills/postgres-schema-review/SKILL.md

At this point, the main content of the SKILL.md file (everything outside Level 1) enters the Context Window.

Example Content:

markdown
# PostgreSQL Schema Review

## Quick Start

For most OLTP scenarios, default to Third Normal Form (3NF):

```sql
-- ✅ Correct: Split into related tables
CREATE TABLE orders (id BIGSERIAL PRIMARY KEY, user_id BIGINT);
CREATE TABLE order_items (id BIGSERIAL, order_id BIGINT, product_id BIGINT);
```

For frequently JOINED queries, refer to [references/denormalization.md](references/denormalization.md).

Level 3: Bundled Resources (Loaded As Needed)

Loading Timing: When Claude deems it necessary. Token Cost: Theoretically unlimited (Scripts might be executed without reading).

A Skill can include additional resource files, recommended to be categorized by purpose:

postgres-schema-review/
├── SKILL.md              # Level 2: Main instructions
├── references/           # Documents and reference materials, will be read into Context
│   ├── denormalization.md
│   └── indexing_guide.md
├── scripts/              # Executable scripts, might be executed without reading into Context
│   ├── validate_schema.py
│   └── suggest_indexes.py
└── assets/               # Files for output, usually not read into Context
    └── schema_template.sql

Three Resource Types and Loading Methods:

1. References (Reference Documents, read into Context):

   bash
   # Executed by Claude when mentioned in SKILL.md
   cat references/denormalization.md
   

   → File content fully enters Context.

2. Scripts (Executable Scripts, possibly read into Context):

   bash
   # Executed by Claude
   python scripts/validate_schema.py schema.sql
   

   → Usually only the output enters Context:

   ❌ Table 'users': Missing index on 'email' column
   ❌ Table 'orders': Foreign key 'user_id' has no index
   ✅ All primary keys are BIGSERIAL
   

   Note: Scripts do not entirely avoid entering Context. Claude might need to read the script content when patching or adjusting the environment.

3. Assets (Output Resources, usually not read into Context):

   bash
   # Copied by Claude when a template is needed
   cp assets/schema_template.sql user_schema.sql
   

   → Files are used but do not necessarily occupy Context.

Key Insight of this Design:

• References are suitable for "flexible guidance" (requiring LLM understanding and reasoning).
• Scripts are suitable for "deterministic operations" (token-efficient, reliable execution, reproducible results).
• Assets are suitable for "templates/resources" (copied/modified, do not consume Context).

3. Benchmarks: How Much Do Skills Save?

Test Scenario: PostgreSQL Schema Review Agent

Plan A: Everything in System Prompt

System Prompt (8,500 tokens):
- PostgreSQL Best Practices Document (3,000 tokens)
- Common Anti-Patterns List (1,500 tokens)
- Schema Validation Rules (2,000 tokens)
- Example Schema (2,000 tokens)

Issues:

• 8,500 tokens loaded for every conversation, even if the user just asks "How to create a table."
• Schema validation logic described in natural language, LLM execution is unstable.
• Cost: $3/1M tokens × 8.5k = $0.0255/call.

Plan B: Using Agent Skill

Level 1 (Always): 100 tokens
Level 2 (Triggered): SKILL.md (2,000 tokens)
Level 3 (As Needed):
  - references/denormalization.md (1,500 tokens) - read only when needed
  - validate_schema.py - usually only output enters context (~50 tokens)
  - assets/*.sql - read only when needed

Scenario 1: Simple Query (70% of conversations)

• User: "How to create an index?"
• Loaded: Level 1 (100) + Level 2 (2,000) = 2,100 tokens.
• Cost: $0.0063/call.

Scenario 2: Complex Review (30% of conversations)

• User: "Review this Schema for me."
• Loaded: Level 1 + Level 2 + validate_schema.py output = 2,150 tokens.
• Script execution: Schema validation logic is deterministic Python code, reliable results.
• Cost: $0.00645/call.

Average Cost Comparison:

• Plan A: $0.0255/call.
• Plan B: $0.0063 × 0.7 + $0.00645 × 0.3 = $0.0063/call.
• 75% Savings.

More Important Benefits:

• TTFT decreased from 2.3s to 0.9s (less Context).
• Schema validation accuracy increased from 85% to 99% (deterministic script).

4. Technology Selection: Skill vs Prompt vs MCP

Decision Tree

Need to execute code?
├─ No → Is it simple rule (< 100 lines)?
│       ├─ Yes → System Prompt
│       └─ No → Agent Skill (Level 2 Instructions)
└─ Yes → Need to access external systems (DB/API)?
        ├─ Yes → MCP Server
        └─ No → Agent Skill (Level 3 Code)

Examples:

5. Anti-Patterns: Do Not Misuse Skills

❌ Error 1: Turning Everything into a Skill

Bad Example:

yaml
---
name: encoding-rule
description: Enforce UTF-8 encoding
---
# Encoding Rule

All code must use UTF-8 encoding.

Problem: This 3-line rule should just be in the System Prompt. Creating a Skill is over-engineering.

Decision Criteria: If the rule is < 50 lines and used every time, skip the Skill overhead.

❌ Error 2: High-Frequency Triggered Skills

If a Skill is triggered in 80% of conversations, it should probably be moved to the System Prompt.

The value of Skills lies in "low-frequency but important" knowledge.

❌ Error 3: Storing Dynamic Data in Skills

Bad Example:

markdown
# User Database Skill

Current user's API key: sk-1234567890
Database connection: postgres://prod-db:5432

Problem: Skills are static files, not suitable for storing "current user state" or "real-time data."

Correct Solution: Use an MCP Server to provide real-time data access.

❌ Error 4: The All-in-One Skill

Don't create an ultimate-backend-skill containing everything from database to API to deployment.

Correct Approach:

✅ postgres-schema-review-skill  (Only handles database design)
✅ api-design-principles-skill    (Only handles API standards)
✅ docker-deployment-skill        (Only handles container deployment)

Let Claude decide which Skills to combine and use.

6. Existing Tools: How to Use These Skill Libraries

6.1 Anthropic Official Skills (anthropics/skills)

Repo Address: https://github.com/anthropics/skills Stars: 58.6k Positioning: Official examples + Production-grade document processing Skills.

Contents:

1. Document Processing Skills (Production-grade, closed-source but code is public):

   • docx - Word document creation and editing
   • pptx - PowerPoint slide generation
   • xlsx - Excel spreadsheet handling
   • pdf - PDF document generation

2. Example Skills (Open source, Apache 2.0):

   • Creative: Art, music, design
   • Technical: Testing web apps, MCP Server generation
   • Enterprise: Communication, brand standards

Installation Method:

bash
# Claude Code
/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills

# Claude.ai
Available by default for paid users, no installation needed.

# Claude API
Upload via Skills API (requires beta headers)

Core Value: These implement the underlying logic for Claude.ai's documentation features, representing best practices for production-grade Skills. Document processing Skills contain complex Python scripts (Level 3 Code) for deterministic generation of Office documents, which is far more reliable than asking the LLM to generate XML directly.

6.2 Vercel (vercel-labs/agent-skills)

Repo Address: https://github.com/vercel-labs/agent-skills Stars: 18k Positioning: Frontend engineering expert.

Included Skills:

1. react-best-practices:

   • React and Next.js performance optimization guides (from Vercel Engineering)
   • 40+ rules, 8 categories, prioritized by impact.
   • Covers: Eliminating Waterfall, Bundle optimization, SSR performance, Client-side Fetching, Re-render optimization.

2. web-design-guidelines:

   • UI code review tool, 100+ rules.
   • Covers: Accessibility, Focus States, Forms, Animation, Typography, Images, Performance.

3. react-native-guidelines:

   • React Native / Expo best practices.
   • 16 rules, 7 categories.
   • Covers: FlashList, Reanimated, Zustand, Platform API.

4. composition-patterns:

   • React component composition patterns.
   • Avoiding Boolean Prop bloat.
   • Compound Components, State Lifting.

5. vercel-deploy-claimable:

   • One-click deployment to Vercel.
   • Auto-detects 40+ frameworks (Next.js, Vite, Astro, etc.).
   • Returns preview URL and claim URL.

Installation Method:

bash
npx skills add vercel-labs/agent-skills

Core Value: These are not "React beginner tutorials" but hundreds of production-grade specifications from Vercel Engineering. Because AI understands semantics better than ESLint, it can catch architectural Smell, like "abusing Client Components" or "Waterfall Fetching." Ideal for automatically reviewing performance issues when writing React/Next.js code.

6.3 Supabase (supabase/agent-skills)

Repo Address: https://github.com/supabase/agent-skills Stars: 931 Positioning: PostgreSQL Architect.

Included Skills:

1. supabase-postgres-best-practices:
   • PostgreSQL performance optimization guide (from Supabase).
   • 8 categories, prioritized by impact.
   • Covers: Query Performance, Connection Management, Schema Design, Concurrency, RLS, Monitoring.

Installation Method:

bash
# npm
npx skills add supabase/agent-skills

# Claude Code Plugin
/plugin marketplace add supabase/agent-skills
/plugin install postgres-best-practices@supabase-agent-skills

Core Value: This is not SQL syntax correction, but advanced DBA knowledge. It includes best practices for Schema design, indexing strategies, Row-Level Security, connection pool configuration, etc. It can directly point out: "You should split this JSONB field into a related table because you frequently need to Update it." Suitable for designing database schemas or optimizing SQL queries.

Usage Recommendations

Security Reminder: These three libraries are maintained by official or reputable organizations and are relatively safe. However, before using any third-party Skill, always review the code (see Section 8).

7. Skill Template: Standard Structure

Minimum Viable Skill

postgres-schema-review/
└── SKILL.md

SKILL.md:

yaml
---
name: postgres-schema-review
description: Review PostgreSQL schema designs for performance and best practices. Trigger when user asks about table design, indexing, normalization, or database optimization.
---

# PostgreSQL Schema Review

You are an expert PostgreSQL architecture reviewer. When users design table structures, review against the following standards.

## Core Principles

1. **All tables must have a PRIMARY KEY**.
2. **All Foreign Keys must have an index** (PostgreSQL does not create these automatically).
3. **Use BIGSERIAL for ID fields by default** (unless the table will forever be < 10K rows).

## Common Anti-Patterns

### ❌ VARCHAR without length limit

```sql
CREATE TABLE users (email VARCHAR);  -- Incorrect
```

**Problem**: Storage bloat, potential index inefficiency.

**Fix**:

```sql
CREATE TABLE users (email VARCHAR(255));
```

### ❌ JSONB for frequently updated fields

```sql
CREATE TABLE orders (items JSONB);  -- Incorrect if 'items' is frequently updated
```

**Problem**: Updating JSONB rewrites the entire field, leading to inefficiency.

**Fix**: Split into a related table.

## Output Format

When issues are found, output in this format:

```
❌ [TableName].[FieldName]: [Issue]
Suggestion: [Modification plan]
Reason: [Justification]
```

Complete Skill (with Scripts and Resources)

postgres-schema-review/
├── SKILL.md                      # Level 2: Main instructions
├── references/                   # Reference documents
│   ├── denormalization.md       # Guide to denormalization
│   └── indexing_guide.md        # Indexing strategy guide
├── scripts/                      # Executable scripts
│   ├── validate_schema.py       # Schema validation
│   └── suggest_indexes.py       # Index suggestion
└── assets/                       # Output resources
    ├── ecommerce.sql            # E-commerce Schema example
    └── saas_multi_tenant.sql    # SaaS multi-tenant example

validate_schema.py Example:

py
#!/usr/bin/env python3
import sys
import re

def validate_schema(sql_file):
    with open(sql_file) as f:
        content = f.read()

    issues = []

    # Check: VARCHAR without length limit
    if re.search(r'VARCHAR\s*\)', content, re.IGNORECASE):
        issues.append("❌ Found VARCHAR without length limit")

    # Check: If all tables have a PRIMARY KEY
    tables = re.findall(r'CREATE TABLE (\w+)', content, re.IGNORECASE)
    for table in tables:
        if not re.search(rf'{table}.*PRIMARY KEY', content, re.IGNORECASE):
            issues.append(f"❌ Table '{table}' missing PRIMARY KEY")

    if issues:
        for issue in issues:
            print(issue)
        sys.exit(1)
    else:
        print("✅ Schema validation passed")

if __name__ == '__main__':
    validate_schema(sys.argv[1])

Referencing the Script in SKILL.md:

Automatic Validation

To automatically check common issues, execute:

bash
python scripts/validate_schema.py schema.sql

Claude will automatically execute the script; only the output enters Context, not the code itself.

Field Requirements

name:

• Max 64 characters.
• Must contain only lowercase letters, numbers, and hyphens.
• Cannot contain reserved words (anthropic, claude).

description:

• Max 1024 characters.
• Must state "what it does" and "when to trigger."

7.1 Skill Packaging: From Directory to .skill File

After creating a Skill, it needs to be packaged into a .skill file for distribution and installation. A .skill file is essentially a zip archive with the extension changed to .skill.

Official Packaging Script: package_skill.py

Anthropic provides an official packaging script package_skill.py (located in the scripts/ directory of the anthropics/skills repository), which automatically validates and packages your Skill.

Basic Usage:

bash
# Package the Skill (output to current directory)
python scripts/package_skill.py path/to/skill-folder

# Specify output directory
python scripts/package_skill.py path/to/skill-folder ./dist

Packaging Process:

1. Validation Phase (automatic execution):

   • Checks YAML frontmatter format and required fields (name, description).
   • Validates Skill naming conventions (lowercase letters, numbers, hyphens).
   • Checks completeness and quality of the description.
   • Validates file organization and resource references.

2. Packaging Phase (after validation passes):

   • Creates the .skill file (e.g., my-skill.skill).
   • Includes all files while maintaining the directory structure.
   • Outputs to the specified directory.

If validation fails, the script reports errors and exits (no package created). Rerun after fixing the errors.

Manual Packaging (No Script Needed)

If you don't have package_skill.py locally (e.g., missing Python dependencies), you can package manually:

bash
# Navigate to the Skill directory
cd path/to/skill-folder

# Use zip to create the .skill file
zip -r ../my-skill.skill .

# Output: ../my-skill.skill

Key Points:

• The .skill file is a zip archive, just with a .skill extension.
• You must execute zip inside the Skill directory to ensure correct path structures.
• Must include all files: SKILL.md, scripts/, references/, assets/, etc.

Verifying the Package

Unzip the .skill file to check the structure:

bash
# Unzip to view
unzip -l my-skill.skill

# Expected output:
# SKILL.md
# scripts/validate.py
# references/guide.md
# assets/template.sql

Common Errors

Distribution and Installation

The packaged .skill file can be:

1. Shared with other users:

   bash
   # User installs
   /plugin install path/to/my-skill.skill
   

2. Published to GitHub:

   bash
   # User installs from GitHub
   /plugin marketplace add your-org/skills-repo
   /plugin install my-skill@your-org-skills-repo
   

3. Uploaded to Anthropic Skills API (requires beta headers):

   python
   # Upload via API
   client.beta.skills.upload("my-skill.skill")
   

8. Security Advice: Only Use Trusted Sources for Skills

Critical Warning: Skills can execute code. A malicious Skill could:

• Steal data (read filesystem, send to external servers).
• Abuse tools (execute dangerous bash commands).
• Misrepresent functionality (claim to be "code review" while secretly planting backdoors).

Checklist Before Using Third-Party Skills:

1. ✅ Review all files: Including SKILL.md, scripts, images.
2. ✅ Check for network calls: Search for fetch, requests, curl, wget.
3. ✅ Check file operations: Search for open(), write(), rm, chmod.
4. ✅ Verify external URLs: Skills pulling content from external URLs pose high risk.
5. ✅ Validate the author: Only use Anthropic official or organization-reviewed Skills.

Only use Skills from these sources:

• ✅ Anthropic official pre-installed Skills
• ✅ Skills you created yourself
• ✅ Skills reviewed internally by your company/team
• ❌ Skills downloaded randomly from the internet

9. Migrating from Prompt to Skill: A 3-Step Action Plan

Step 1: Identify Candidate Content (30 minutes)

Review your System Prompt and find sections matching these characteristics:

Step 2: Split into Atomic Skills (1-2 hours)

Anti-pattern (Bad):

full-stack-best-practices/ # Too big, handles everything

Pattern (Good):

postgres-schema-review/ # Only handles database design
react-component-style/ # Only handles React components
api-design-principles/ # Only handles API standards

Migration Checklist:

1. ✅ Create SKILL.md, move documentation content into it.
2. ✅ Identify "deterministic logic," rewrite as Python/JS scripts (put in scripts/).
3. ✅ Place large reference materials into references/ or assets/.
4. ✅ Clearly state trigger conditions in the description.
5. ✅ Use package_skill.py to package (see Section 7.1).

Step 3: Validate Results (1 Week)

If results are insignificant: Your System Prompt was likely already concise, so no optimization was needed.

10. Summary

Core Points

1. Agent Skills are not "splitting a Prompt into files", but rather "capability packages running in a VM."
2. The Killer Feature of Skills is Scripts: Deterministic scripts usually only load output (not the code itself) into Context, ensuring reliable execution and token efficiency.
3. Progressive Disclosure is the correct engineering tradeoff: The three-level loading mechanism (Metadata → SKILL.md → Bundled Resources) consumes tokens on demand.

Use Cases