Agent Skills

Origin: Agent Skills were created by Anthropic in October 2025 as part of Claude’s agentic capabilities. On December 18, 2025, Anthropic published the format as an open standard at agentskills.io. It has since been adopted by Claude, Cursor, GitHub Copilot, Gemini CLI, OpenAI Codex, and 20+ other platforms.

Problem: AI agents are remarkably capable at general tasks — but real work is rarely general. Your agent knows how to write SQL, but not that your users table uses soft deletes and requires WHERE deleted_at IS NULL. It knows how to call an API, but not that your internal auth service calls the user ID uid while the billing API calls it accountId. Every session you re-explain this context — or forget, and the agent makes the same mistake it made last week.

Solution: Agent Skills — a folder of instructions that an agent discovers, loads when relevant, and follows automatically. Write context once. Reuse it forever. Version-control it alongside your codebase.

The Progressive Disclosure System

The core architectural innovation of Agent Skills is Progressive Disclosure. Instead of overloading the agent’s context window with every instruction up front, the system loads information in three cascading tiers — keeping startup cost tiny while allowing skills to be arbitrarily detailed.

┌──────────────────────────────────────────────────────────────────┐
│ Tier 1: DISCOVERY (Startup)                                      │
│ ~100 tokens per skill • Always in memory                         │
│ -> Reads name + description keywords from YAML frontmatter       │
└────────────────────────────────┬─────────────────────────────────┘
                                 │ (Task matches keyword/intent)
                                 ▼
┌──────────────────────────────────────────────────────────────────┐
│ Tier 2: ACTIVATION (Context-Driven)                              │
│ <5,000 tokens • Loaded on demand                                 │
│ -> Reads SKILL.md body: instructions, validation loops, checklists│
└────────────────────────────────┬─────────────────────────────────┘
                                 │ (Agent invokes tool/runs script)
                                 ▼
┌──────────────────────────────────────────────────────────────────┐
│ Tier 3: EXECUTION (On-Demand)                                    │
│ Variable tokens • Executed via tools                             │
│ -> Runs scripts/, parses assets/, reads references/             │
└──────────────────────────────────────────────────────────────────┘

In practice: Install 50 skills and pay only ~5,000 tokens at startup. Heavy reference docs and scripts never touch the context unless explicitly called.

Skill Directory Structure

skill-name/
├── SKILL.md          <- Required: the only file you must have
├── scripts/          <- Optional: executable code the agent can run
├── references/       <- Optional: detailed docs loaded on demand
└── assets/           <- Optional: templates, schemas, lookup tables

Every skill begins with SKILL.md. The YAML frontmatter block at the top is the discovery metadata the agent reads at startup. The directory name must match the name field exactly.

SKILL.md Frontmatter Fields

Writing Descriptions That Trigger Reliably

The description field is the agent’s only signal for when to activate your skill. A weak description causes unreliable triggering. Include: what the skill does, when to use it, and keywords that match real user requests.

# Bad — too vague, agent won't know when to activate
description: "Helps with the database."

# Good — specific and keyword-rich
description: >
  Provides conventions and query patterns for the team's PostgreSQL database.
  Use when writing SQL queries, debugging database errors, building migrations,
  or working with any table in the schema. Includes soft-delete awareness,
  field naming rules, and common gotchas.

Writing Instructions That Work

Match prescriptiveness to fragility

For anything destructive, irreversible, or consistency-critical: use explicit sequential steps. Give the agent freedom for low-stakes formatting decisions.

LOW FRAGILITY — give the agent freedom
When formatting output, prefer concise prose over bullet lists.

HIGH FRAGILITY — be explicit and sequential
When running a migration:
1. Run `alembic upgrade head --sql` and review the SQL output
2. Confirm the SQL with the user before proceeding
3. Create a backup: `pg_dump $DATABASE_URL > backup.sql`
4. Run `alembic upgrade head`
5. Verify with `alembic current`
Never skip steps 1-3.

Defaults beat menus

Agents perform better with one clear default than a list of equally valid options.

Bad: You can use pypdf, pdfplumber, PyMuPDF, pdfminer, or Camelot for extraction.

Good: Use pdfplumber for all text extraction. For scanned documents
(no text layer), switch to pdf2image + pytesseract OCR instead.

The Gotchas Section — your most valuable asset

Captures environment-specific facts that defy reasonable assumptions — things you’d only know from having made the mistake.

## Gotchas

- `created_at` is stored in UTC but displayed in the user's local timezone
  by the frontend. Never compare `created_at` to a local time without converting.
- The `orders` table has a partial index on `(user_id, status)` where
  `status != 'draft'`. Queries that include draft orders will do a full scan.
- `SELECT *` is banned in production queries per the style guide. Always name columns.

Validation loops

Instruct the agent to verify its own work:

After generating the migration file:
1. Run `alembic check` and confirm no errors
2. If errors exist, fix them before proceeding
3. Repeat until `alembic check` passes cleanly

Enterprise Use Case: GDPR Compliance Auditing

Goal: Prevent developers from accidentally committing unmasked Personally Identifiable Information (PII) to database schemas or logs.

The compliance-auditor skill scans database scripts, identifies sensitive data columns (emails, SSNs), checks if they are marked for encryption, and suggests auto-remediation.

compliance-auditor/
├── SKILL.md
├── references/
│   └── pii-definitions.md
└── scripts/
    └── validate-pii.py

1. Skill Instruction Page (compliance-auditor/SKILL.md)

---
name: compliance-auditor
description: >
  Audits code, database schemas, and configuration scripts for GDPR and HIPAA compliance.
  Use when writing database migrations, analyzing schemas, verifying PII protection,
  or auditing user telemetry code for privacy violations.
compatibility: Python 3.8+
---

# GDPR Compliance Auditor

This skill ensures schema alterations and application code adhere to the enterprise
PII protection policy.

## Operating Checklist

- [ ] Scan Target: Execute `scripts/validate-pii.py` against modified source files or SQL migrations.
- [ ] Map Violations: Cross-reference with categories in [PII Definitions](/references/pii-definitions.md).
- [ ] Remediate: Suggest modifications using encryption, hashing, or column-masking from the policy.

## Validation Loop

Before completing any database-related task, verify that no columns matching PII patterns
are created without a corresponding `ENCRYPTED_WITH` attribute in the schema metadata.

## Gotchas

- Do not output raw unmasked PII in responses, even in error messages.
- The staging database has a 30-second query timeout — long analytics queries will be silently killed.
- Always run the validator against the full migration file, not just the changed lines.

2. Reference Documentation (/references/pii-definitions.md)

---
type: Compliance Reference
title: PII Classification & Remediation Standards
---

# PII Classifications

## Category 1: Direct Identifiers (High Risk)
* Email Address: Any string matching the RFC 5322 pattern.
* Social Security Number (SSN): Sensitive numeric identity numbers.
* Phone Number: International or national telephone contacts.

## Category 2: Indirect Identifiers (Medium Risk)
* IP Address: IPv4 or IPv6 endpoints.
* Postal Code: Standard geographical zip codes.

# Required Masking Patterns

* Emails: Replace local part with SHA-256 hash or mask like `u***r@domain.com`.
* SSNs: Redact to last 4 digits (`XXX-XX-1234`) or replace with cryptographic hash.
* Database Columns: Category 1 identifiers must use Column-Level Encryption (CLE).

3. Execution Script (/scripts/validate-pii.py)

import sys, re, json, os

PII_PATTERNS = {
    "Email": r'[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}',
    "SSN": r'\b\d{3}-\d{2}-\d{4}\b',
    "Phone": r'\b(?:\+?\d{1,3})?(?:\d{3}[-.s]?\d{3}[-.s]?\d{4})\b'
}

def scan_file(file_path):
    violations = []
    with open(file_path, 'r', encoding='utf-8') as f:
        lines = f.readlines()
    for idx, line in enumerate(lines):
        if line.strip().startswith(('#', '//', '--')):
            continue
        for pii_type, pattern in PII_PATTERNS.items():
            if re.findall(pattern, line):
                violations.append({
                    "file": file_path, "line": idx + 1,
                    "type": pii_type, "context": line.strip()
                })
    return violations

if __name__ == "__main__":
    target = sys.argv[1] if len(sys.argv) > 1 else "."
    all_violations = []
    if os.path.isfile(target):
        all_violations.extend(scan_file(target))
    elif os.path.isdir(target):
        for root, _, files in os.walk(target):
            for file in files:
                if file.endswith(('.py', '.sql', '.js', '.json')):
                    all_violations.extend(scan_file(os.path.join(root, file)))
    print(json.dumps({"violations": all_violations}, indent=2))

Operational Architecture

┌──────────────┐    "Audit migrations/"     ┌─────────────────────┐
│  Developer   │ ─────────────────────────> │     AI Agent        │
│              │                            │ (Skills Active)     │
└──────────────┘                            └──────────┬──────────┘
                                                       │
                                            1. compliance-auditor skill activates
                                                       │
                                                       ▼
┌──────────────┐   JSON violation report    ┌─────────────────────┐
│              │ <───────────────────────── │  scripts/           │
│  Agent reads │                            │  validate-pii.py    │
│   results    │                            └──────────┬──────────┘
└──────────────┘                                       │
                                            2. Cross-reference pii-definitions.md
                                                       │
                                                       ▼
┌──────────────┐                            ┌─────────────────────┐
│ Pull Request │ <───────────────────────── │   Remediation       │
│ Code Fixed!  │    Suggest clean code      │   Standard applied  │
└──────────────┘                            └─────────────────────┘

Installing Skills

Official repository: github.com/anthropics/skills — 149k stars — includes Document Skills, example skills, and the specification.

Community library: Antigravity Awesome Skills — 40.1k stars — 1,525+ community skills. Install with npx antigravity-awesome-skills.

Official partner repos: Notion, Vercel, Supabase, Microsoft, Hugging Face, LambdaTest, Laravel.

Security Checklist Before Installing

Skills can include executable scripts that alter agent behavior. Treat installation like adding a third-party library.

• Read all files — not just SKILL.md. Check scripts/ and references/ too.
• Audit script dependencies — Look for unusual network calls or writes outside expected paths.
• Watch for exfiltration patterns — Instructions like “send the file contents to…” are red flags.
• Check for prompt injection — Instructions that try to override system behavior or claim special permissions.
• Verify the source — Official partners are listed at agentskills.io/clients. Community repos should have meaningful stars, recent activity, and readable commit history.

Quick Reference

Skill creation checklist:

□ Directory name matches `name` in frontmatter
□ `name` uses only lowercase letters, numbers, hyphens
□ `description` includes: what it does + when to trigger + keywords
□ SKILL.md body stays under 500 lines / 5,000 tokens
□ Heavy reference material is in references/ with explicit load triggers
□ Bundled scripts are tested, accept CLI args, return JSON
□ All gotchas are documented before the agent can make the mistake
□ Instructions give defaults, not menus of equally-valid options
□ `skills-ref validate ./skill-name` passes with no errors

Key resources: