Agent Skills
The hottest new paradigm for AI agents in 2026

1. The problem Skills was born to solve: how does expertise get accumulated?

During the 2024-2025 "Agent arms race", the industry converged on one critical observation:

Agents themselves are already general-purpose; the truly scarce thing is captured, codified, repeatedly callable expertise.

We used to teach AI through prompts, but prompts have three fundamental flaws:

• One-shot: you paste it every time; it does not persist across sessions.
• Not auditable: scattered across chat history, impossible to code-review or version.
• Capability mismatch: you spend effort on "the right wording" while the real expertise is buried under phrasing.

Skills' solution is to upgrade prompts into assets: version-controlled, team-shareable, tool-callable, iteratively improved. A Skill is a folder that holds a "professional process".

1.1 A comparison: Swiss Army knife vs recipe vs role SOP

1.2 Skills vs MCP vs Plugin vs Prompt

1.3 Skills × MCP: the complete Agent architecture

Skills and MCP are complementary, not competitors:

Powerful Agent = MCP Tools (connect to the world) + Skill (codify expertise) + Memory (cross-session) + Model (reasoning)

From Claude Code 2.1.3, Anthropic further merged commands and skills into one concept — both are called Skill, just with different trigger modes (automatic vs manual /skill-name). This is a key step toward a unified Skills ecosystem.

2. Full SKILL.md spec: folder, YAML, body

A standard Skill structure:

2.1 YAML frontmatter: required and optional fields

---
# === Required fields ===
name: python-code-reviewer          # Skill name (kebab-case, ≤ 64 chars)
description: |                      # Skill description — the most important field!
  Review Python code for OWASP security, PEP 8 style and performance
  anti-patterns. Triggers on "review", "audit", "check code", "PR review".
  Use for: Python 3.10+.
  Do not use for: other languages (use a language-specific reviewer).

# === Recommended fields ===
license: Apache-2.0                 # License
compatibility: Requires python>=3.10, git  # Environment dependencies
allowed-tools: Read Bash(git:*) Grep    # Pre-authorized tools, security isolation
metadata:                           # Custom metadata
  author: devops-team
  version: "1.2.0"
  category: code-review

# === Optional advanced fields ===
when_to_use: "Reviewing a PR or auditing legacy code"  # Extra trigger hints
argument-hint: "[file-path]"                            # Slash-command argument hint
disable-model-invocation: false                         # Disallow automatic triggering
user-invocable: true                                    # Show in / menu
model: claude-sonnet-4-5                                # Pin a specific model
context: fork                                           # Execute in a sub-agent
---  # YAML frontmatter closing delimiter

2.2 Markdown body: the four required sections

# Skill Title

## Instructions                         <-- Core execution steps (required)
Execute in order:
1. Read the target file
2. Run the security scan
3. Bucket findings by severity

## Examples                             <-- Input/output examples
Input: ...
Output: ...

## Guidelines                           <-- Style / constraints / boundaries
- Skip auto-generated files
- Lower strictness for test files

## Troubleshooting                      <-- Failure handling (optional)
- If git is unavailable, prompt the user to install it

2.3 Naming rules and the gotchas (lessons learned)

2.4 The description field: the SEO of a Skill

The description drives ~90% of trigger accuracy. A bad description will be silently never-triggered (or constantly over-triggered). Three core ingredients:

1. What it does: spell out the Skill's function.
2. When to use: applicable scenario + trigger keywords.
3. When not to use: explicit exclusions to reduce over-triggering.

# ❌ Bad: too vague, no routing signal
description: code review

# ⚠️ Mediocre: action but no trigger words
description: Review code and check for issues

# ✅ Good: WHO + WHEN + keywords + boundaries
description: |
  Review Python code for OWASP Top 10 security, check for injection
  vulnerabilities, hard-coded credentials, resource leaks and
  performance anti-patterns. Triggers on "review", "audit",
  "check code", "code review". Use for: Python 3.10+.
  Do not use for: other languages (use a language-specific reviewer);
  formatting (use a formatter).

3. Progressive disclosure: the killer design

The single best idea in Skills — three-layer on-demand loading, so even 100 Skills do not blow up the context.

3.1 The three layers, visualized

3.2 Token economics: why 100 Skills do not hurt

3.3 Real-world wins

• Token savings: 14-80% (the less task-related the Skills, the bigger the savings)
• Error-rate reduction: ~35% on complex tasks with TDD constraints
• Task throughput: +40%/month in Anthropic's internal teams
• Long-document tasks: token usage drops 60-80%

3.4 SKILL.md is case-sensitive — the biggest gotcha

The most common mistake Claude Code users make. The file MUST be exactly SKILL.md (all caps). The following all silently fail to load:

• skill.md — lowercase s, invalid
• SKILL.MD — all-caps extension, invalid
• Skill.md — first letter capitalized, invalid

On case-insensitive filesystems (default macOS/Windows), you can create skill.md, push to Linux CI, and only then discover the bug. Always verify the file name with git status.

4. The full Skill creation workflow

4.1 Five-step recipe

1. Use skill-creator to auto-generate: Anthropic's official "meta-skill" — it walks you through SKILL.md generation conversationally.
2. Write SKILL.md: YAML frontmatter + Markdown body.
3. Add scripts/: wrap deterministic operations (data scraping, format conversion, API queries) in scripts.
4. Add references/: detailed docs read on demand (API references, edge cases).
5. Test → evaluate → iterate: verify trigger rate on real tasks, iterate the description.

4.2 A real, complete Skill: python-code-reviewer

This Skill demonstrates the full structure and SKILL.md content — drop it in and use it.

SKILL.md contents:

---
name: python-code-reviewer
description: |
  Review Python code for OWASP Top 10 security, PEP 8 style, and
  performance anti-patterns. Output is bucketed into CRITICAL / HIGH /
  MEDIUM / LOW. Triggers on "review", "code review", "audit", "PR review".
  Use for: Python 3.10+.
  Do not use for: other languages (use a language-specific reviewer);
  formatting (use a formatter).
license: Apache-2.0
compatibility: Requires python>=3.10, git
allowed-tools: Read Grep Glob Bash(git diff:*)
metadata:
  author: ai-kb-team
  version: "1.0.0"
  category: code-review
---  # YAML frontmatter closing delimiter

# Python Code Reviewer

## Instructions

Execute in order:

### Phase 1: gather changes
1. Run `git diff --name-only origin/main...HEAD` to find changed files
2. Filter to `*.py` files
3. Skip auto-generated files (`*_pb2.py`, `*_pb2_grpc.py`)

### Phase 2: security review
Run `python scripts/check_security.py <file>` and check:
- SQL injection (string concatenation)
- Hard-coded keys / credentials
- Unsafe deserialization (pickle / eval)
- HTTP handlers with no input validation

### Phase 3: style and performance
Cross-check `references/owasp-checklist.md`:
- Errors use specific exception types
- Resources are managed with context managers
- No N+1 query anti-pattern

### Phase 4: output the report
Emit a Markdown table:

| Severity | File:line | Issue | Suggested fix |
| --- | --- | --- | --- |

## Examples

Input: review src/api/users.py

Output:
- [CRITICAL] src/api/users.py:42 - SQL injection: query built with string concatenation
  → Fix: use parameterized queries `cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))`
- [HIGH] src/api/users.py:78 - hard-coded API key
  → Fix: read from env `os.environ["API_KEY"]`

## Guidelines

- Skip style issues in test files (only check security and correctness)
- Be lenient on `__init__.py`
- Batch output when a file has more than 20 issues

## Troubleshooting

- If git is unavailable, prompt the user to install git
- If Python < 3.10, warn about incompatibility

Companion scripts/check_security.py:

#!/usr/bin/env python3
"""Python code security static scanner - companion to the Python Code Reviewer."""
from pathlib import Path

SECRET_PATTERNS = [
    (r'(?i)(api[_-]?key|secret|password|token)\s*=\s*["\'][^"\']+["\']', 'Hardcoded credential'),
    (r'(?i)aws_[a-z]+_key\s*=\s*["\'][^"\']+["\']', 'Hardcoded AWS key'),
]

SQL_INJECTION_PATTERNS = [
    (r'execute\s*\(\s*["\'].*%s.*["\']', 'SQL string formatting'),
    (r'execute\s*\(\s*["\'].*\+.*\)', 'SQL string concatenation'),
    (r'\.raw\s*\(\s*["\'].*\+', 'Django raw SQL with concatenation'),
]

UNSAFE_PATTERNS = [
    (r'\beval\s*\(', 'Use of eval()'),
    (r'\bexec\s*\(', 'Use of exec()'),
    (r'pickle\.loads?\s*\(', 'Unsafe deserialization'),
    (r'subprocess\.[A-Za-z_]+\([^)]*shell\s*=\s*True', 'Shell injection risk'),
]

def scan_file(path: Path) -> list:
    findings = []
    content = path.read_text(encoding='utf-8', errors='ignore')
    for pattern, desc in SECRET_PATTERNS + SQL_INJECTION_PATTERNS + UNSAFE_PATTERNS:
        for match in re.finditer(pattern, content):
            line_no = content[:match.start()].count('\n') + 1
            findings.append({'line': line_no, 'issue': desc, 'snippet': match.group(0)[:80]})
    # AST: bare except clauses
    try:
        tree = ast.parse(content)
        for node in ast.walk(tree):
            if isinstance(node, ast.ExceptHandler) and node.type is None:
                line_no = getattr(node, 'lineno', 0)
                findings.append({'line': line_no, 'issue': 'Bare except clause', 'snippet': 'except:'})
    except SyntaxError:
        pass
    return findings

def main():
    if len(sys.argv) < 2:
        print('Usage: check_security.py <file_or_dir>', file=sys.stderr)
        sys.exit(1)
    target = Path(sys.argv[1])
    files = [target] if target.is_file() else list(target.rglob('*.py'))
    for f in files:
        findings = scan_file(f)
        for fnd in findings:
            print(f"[SECURITY] {f}:{fnd['line']} - {fnd['issue']}")
            print(f"    {fnd['snippet']}")
    sys.exit(0)

if __name__ == '__main__':
    main()

5. Five design patterns (drawn from real-world practice)

Five recurring Skill design patterns from Anthropic's internal playbook and community consensus.

5.1 Sequential workflow

Scenario: customer onboarding, product launch, order processing — multi-step pipelines.

Pattern: lock the fixed steps into the Skill, each step as a checkpoint.

# Customer onboarding
## Steps
1. Create account (call create_account MCP)
2. Set up payment method (call stripe MCP)
3. Send welcome email (call sendgrid MCP)
4. Sync to CRM (call salesforce MCP)
5. Create project space (call notion MCP)

## Guidelines
- Stop immediately on any failure; log to the audit log
- Wait ≤ 5 seconds between steps
- Notify the sales team when done

5.2 Multi-MCP coordination

Scenario: cross-system data flow, e.g. "design to development".

Pattern: Skill defines the transformation rules, MCP provides the connectors.

# Design to development
## Workflow
1. Read designs from Figma MCP
2. Extract design tokens (color / font / spacing)
3. Create matching tickets in Linear MCP
4. Sync to GitHub MCP issues
5. Slack MCP notifies the front-end team
6. Drive MCP stores the design assets

## Coordination
- Retries: up to 3 attempts per MCP call
- Cross-MCP data is passed as JSON

5.3 Iterative refinement

Scenario: report generation, content creation, data analysis — tasks that need multiple rounds of improvement.

Pattern: the Skill contains a "generate → check → fix" loop.

# Report generation
## Steps
1. Generate a first draft from the data
2. Run scripts/check_quality.py
3. Identify sub-standard sections
4. Re-generate (only the sub-standard parts)
5. At most 3 iterations
6. Emit the final report when it passes

## Quality Check
- Data accuracy (every claim must be traceable)
- Section completeness (must cover 5 core dimensions)
- Citation discipline (data sources must be cited)

5.4 Context-aware tool selection

Scenario: file storage, content management — pick the right storage based on context.

Pattern: the Skill encodes the "condition → tool" mapping; the Agent decides.

# Smart file storage
## Decision Tree
- File > 100MB ──→ Cloud storage (MCP: AWS S3)
- Collaborative doc ──→ Notion (MCP: Notion)
- Code snippet ──→ GitHub Gist (MCP: GitHub)
- Temporary data ──→ Local /tmp
- Sensitive data ──→ Encrypted storage (MCP: 1Password)

## Triggers
- "Save this file" ──→ Pick automatically by file type
- "Archive" ──→ Force S3
- "Share with the team" ──→ Notion

5.5 Domain-specific intelligence

Scenario: finance compliance, medical diagnosis, legal review — vertical domains.

Pattern: the Skill encodes industry knowledge + regulations + best practices, combined with domain MCPs.

# Finance compliance check
## Workflow
1. Pull transaction data (MCP: bank API)
2. Match sanctions list (MCP: OFAC database)
3. Jurisdiction check (local rule library)
4. Compute risk score
5. Trigger manual review (high risk)
6. Generate audit log

## Compliance
- Every step must be auditable
- High-risk actions need human confirmation
- Full record into the SOC 2 system

6. Anthropic's 10 golden design principles

Early 2026, Anthropic published their internal methodology in Lessons from building Claude Code: how we use Skills for the first time. The core: 10 principles.

1. Don't write the obvious. Claude already knows how to code and read code; the Skill should only include information that "moves the model off its default answer". The frontend-design Skill deliberately says "avoid Inter font and purple gradients" — forcing the model off its default taste.
2. Build a "gotchas" zone. The most important part of a Skill is not the rules — it is the "real pitfalls you have hit". Examples: "the data table is append-only — you must read the highest version row, not the latest created_at"; "the staging environment returns 200 even on webhook failures — you must infer real status from payment_events".
3. Folder hierarchy + progressive disclosure. Keep SKILL.md under 500 lines; move details to reference.md / stuck-jobs.md / assets/ / scripts/. The AI reads on demand, keeping the context lean.
4. Avoid over-constraining (no railroading). The Skill should not become a step-by-step manual. Define the goal and constraints, not every step. The Slack standup Skill only defines the "output goal" — it does not dictate the step-by-step generation flow.
5. Support private config + interactive initialization. Use config.json to manage the Slack channel, API endpoint. When config is missing, prompt the user via the AskUserQuestion tool.
6. Description is a routing signal, not documentation. The description is not a developer-facing spec — it is the routing signal Claude uses to match tasks. It must include: what it does + trigger words (babysit, standup, review, debug) + boundaries.
7. Introduce persistent memory, evolve continuously. Use ${CLAUDE_PLUGIN_DATA} as a stable storage path to record execution history. The standup-post Skill maintains standups.log — letting the model compare with the past and emit differentiated results.
8. Codify scripts, let the model focus on decisions. All deterministic operations (data scraping, format conversion, API queries) should NOT be regenerated by the model — they should be scripts. The data-science Skill ships helper functions so Claude just composes them.
9. On-demand hooks, not global hooks. Hooks should only fire while the Skill is active. Examples: /careful intercepts rm -rf, DROP TABLE, git push -f; /freeze limits the edit scope.
10. Compose skills, reuse capability. Skills can call and depend on each other. Example: a CSV generation Skill can call a file-upload Skill, completing the data-generation → distribution chain in one go.

7. The Skills ecosystem (real projects, 2025.10 - 2026.02)

7.1 Official spec & resources

7.2 Community highlights (real star counts as of early 2026)

7.3 Discovery and aggregation platforms

8. Cross-platform support (early 2026)

After Agent Skills became an open standard on 2025-12-18, every major AI coding tool scrambled to adopt it — giving rise to a "one Skill, many platforms" ecosystem.

Cross-platform test results (early-2026 community bake-off): Claude Code / Codex / Antigravity all scored perfect 100s on the 4 test scenarios (hello-skill / format-boundary-trap / strict-json-trap / file-generation-trap) — confirming production-grade compatibility.

9. Skills × MCP in synergy: 3 enterprise scenarios

Powerful Agent = MCP Tools (capability) + Skill (standard operating procedure) + Memory (cross-session)

9.1 Customer support

Skill responsibility: ticket triage SOP, auto-reply templates, escalation rules

MCP responsibility: connect Zendesk / Salesforce / Slack / Intercom

9.2 Sales

Skill responsibility: sales-process SOP, BANT qualification, follow-up cadence

MCP responsibility: Apollo / LinkedIn / HubSpot / Gmail

Key capability: from ICP definition → lead discovery → outreach → qualification → opportunity management — Skills orchestrate the whole flow, MCPs deliver real-time data.

9.3 Research

Skill responsibility: research methodology, source grading, report structure

MCP responsibility: Brave Search / Exa / ArXiv / Notion / Zotero

Key capability: Skills define "which question uses which method, produces which structure"; MCPs supply real-time data streams. The decoupling means the same Skill can be applied to different research topics.

10. Enterprise rollout: 3 scenarios + 3-step recipe

10.1 Three enterprise scenarios

10.2 The 3-step rollout

1. Discovery & selection: start with tasks you do at least 2× a week, identify the SOP worth encoding, and pick a Skill framework (Superpowers / in-house / vertical solution).
2. Environment & permissions: configure MCP integrations, set up a team Skill registry, define permission tiers (read / write / network), prepare audit logs.
3. Test, optimize, monitor: build a small evaluation set (50-100 prompts), A/B test different descriptions, monitor trigger accuracy, iterate continuously.

10.3 Hidden pitfalls at scale

UBC / Vector Institute / CIFAR research in early 2026 found that once a Skill library exceeds 50-100 entries, the Agent's selection accuracy drops in a "phase-transition" fashion — the model's working memory has a physical limit (similar to Hick's law failing + cognitive-load theory).

6 avoidance guidelines:

1. Monitor library size: 50-100 is the "warning line" for GPT-4o-class models.
2. Minimize semantic collisions: do not let two Skills have very similar descriptions (accuracy drops 17-63%).
3. Hierarchical routing at scale: group by domain; Stage 1 picks a cluster, Stage 2 picks the Skill.
4. Invest in description optimization: description is the only trigger signal; body length does not matter.
5. Match model to task: stronger models (Claude Opus 4.5, GPT-5) resist confusion better.
6. Consider alternative architectures: at very large scale, fall back to Multi-Agent + routing.

11. Risks & best practices

11.1 Security risks

Anthropic explicitly warns: malicious Skills can:

• Prompt injection: hide malicious instructions in SKILL.md.
• Data exfiltration: trick the Agent into sending sensitive data to an external server.
• Permission abuse: scripts/ executes arbitrary shell commands.
• Outbound network calls: the Skill's instructions point the Agent at untrusted addresses.

Several Skills-poisoning incidents were recorded by the community in 2025-2026, especially from unknown AI-trading-bot repos.

11.2 Defensive best practices

11.3 Complexity management

Do not build a "do-everything assistant". Split a giant Skill into multiple focused Skills, each owning one job. Example: instead of "the full code-pipeline Skill", split into code-reviewer / test-generator / refactor-helper / doc-writer.

Why: LLM "selection attention" has a physical ceiling (50-100 trigger signals). Multiple focused Skills beat one giant Skill.

11.4 Maintenance cost

Skills are "living documents", not write-once. Anthropic's internal data shows that the most successful Skills are not designed perfectly the first time — they are:

• A few lines of simple guidance at first
• Then real-world pitfalls
• Then continuous additions of new cases / rules / edge conditions
• Eventually becoming a production tool

Maintenance rhythm: review Skill usage data every 2 weeks (monthly cadence), run a systematic optimization every quarter (add / remove / merge).

12. Learning resources & paths

12.1 Must-read official material

• Equipping agents for the real world with Agent Skills — Anthropic's official engineering blog, first published 2025-10
• Lessons from building Claude Code: how we use Skills — first public release of the 10 internal principles, early 2026
• The Complete Guide to Building Skills for Claude — 32-page PDF complete developer guide
• Agent Skills open standard — Specification v1.0
• anthropics/skills — official repo, 16+ official skills to learn from

12.2 Courses and tutorials

• DeepLearning.AI: Agent Skills with Anthropic short course (with Andrew Ng)
• Datawhale: agent-skills-with-anthropic Chinese hands-on tutorial
• Awesome collections: awesome-agent-skills, awesome-claude-skills

12.3 Three-level learning path

🟢 Beginner (0-2 weeks)

1. Read the official Skills introduction — understand the 3-layer progressive disclosure.
2. In Claude Code, type /skill to see the existing Skills.
3. Use skill-creator to auto-generate your first Skill.
4. Read the source of 3 official skills (pdf, webapp-testing, brand-guidelines).

🟡 Intermediate (2-8 weeks)

1. Write 5-10 focused Skills for your project.
2. Study Superpowers' 14 core Skills (source-readable).
3. Read the design patterns in vercel-labs/agent-skills.
4. Write an enterprise-grade Skill with scripts/ + references/.
5. Plug into MCP and build a Skills × MCP project.

🔴 Advanced (8 weeks+)

1. Study the agentskills.io spec and design custom fields.
2. Build cross-platform Skills — verify them on Claude Code / Codex / Cursor.
3. Contribute to anthropics/skills or build an in-house Skill registry.
4. Investigate the phase-transition in scaling Skill libraries (50+ → 100+ → 200+) and build hierarchical routing.
5. Integrate MCP + Skills + Memory + multi-Agent into an enterprise-grade Agent platform.

13. Key data dashboard (early 2026)

14. Chapter summary

• ✅ Skills is the new Agent paradigm released 2025-10, upgraded to an open standard on 2025-12-18, sitting alongside MCP as a de-facto standard.
• ✅ A Skill = a folder + SKILL.md; required YAML (name + description); optional scripts/, references/, assets/.
• ✅ Progressive disclosure (3 layers) is the core mechanism — even 100 Skills do not blow up the context; token savings 14-80%.
• ✅ SKILL.md is case-sensitive (must be SKILL.md); description drives 90% of trigger accuracy.
• ✅ 5 design patterns: sequential workflow / multi-MCP coordination / iterative refinement / context-aware / domain-specific.
• ✅ 10 design principles: don't write the obvious, build gotchas, avoid railroading, description is a routing signal, codify scripts, on-demand hooks, etc.
• ✅ Ecosystem: official anthropics/skills (100k+) + community superpowers (208k+) + 14+ quality repos.
• ✅ Cross-platform: 27+ platforms with native support (Claude Code / Codex / Cursor / Antigravity / Trae / CodeBuddy / VS Code Copilot).
• ✅ Skills × MCP = the complete Agent architecture — 3 enterprise scenarios (customer support / sales / research).
• ✅ Scale wall: 50-100 Skills is the "phase transition" for trigger accuracy; at scale, use hierarchical routing.
• ✅ Risk: malicious Skills can inject / exfiltrate data / abuse permissions — always use trusted sources + audit SKILL.md + allowed-tools restrictions.

Selection decision tree

Hands-on: build a production-grade Skill

This section walks through the full SKILL.md spec, YAML fields, scripts/ and references/ subdirectories — from "I have an idea" to "running in the team repo". We reproduce a production-grade code-review Skill end-to-end. All files are about 250 lines; copy them in order and they will run.

1. Goal: what are we building?

For a team Git repo, on trigger the Skill automatically:

• Loads the git diff file list;
• Runs scripts/lint.py for static checks + security scanning;
• Cross-checks references/style-guide.md with the LLM for suggestions;
• Posts a Markdown report as a PR comment.

2. Step 1: chat through requirements with skill-creator

In Claude Code, just say:

skill-creator will ask a few clarifying questions (target user, model limits, side effects). After you answer, it will produce a code-review/SKILL.md draft.

3. Step 2: hand-write SKILL.md (final version)

---
name: code-review
description: Run static checks + security scan + style review on the current git diff and emit a pasteable Markdown report. Triggers on "review", "audit", "look at this change".
---

# Code Review Skill

Review every change on the current branch relative to main — run static checks + security scan + LLM style review — and produce a PR-comment-ready Markdown report.

## Workflow

1. `git diff main...HEAD --stat` → list of changed files
2. For each changed file, run `python scripts/lint.py <file>`
3. Read `references/style-guide.md` and `references/security-checklist.md`
4. Use the LLM to combine lint output + rule docs into a Markdown report
5. Write the report to `report.md` and tell the user to copy it into the PR

## When not to use

- The user only wants a single line explained → just Read, do not trigger
- Change is < 5 lines → just give a verbal review
- Non-code files (.md / .txt) → skip lint, only do style review

## Output format

The report MUST contain 3 fixed sections: **Lint results**, **Security issues**, **Improvement suggestions**. Missing any section = incomplete report.

4. Step 3: add scripts/lint.py (Python static + security scanner)

"""Static check + security scan for a single Python file.

Usage:
    python scripts/lint.py path/to/file.py

Exit code:
    0 - pass
    1 - found issues (report on stderr)
"""
from __future__ import annotations

from pathlib import Path

# Simplified security rules: common vulnerability keywords
SECURITY_PATTERNS = [
    (r"\beval\s*\(", "eval() is a code-injection risk"),
    (r"\bexec\s*\(", "exec() is a code-injection risk"),
    (r"pickle\.loads?\s*\(", "pickle deserialization of untrusted data has RCE risk"),
    (r"shell=True", "subprocess with shell=True needs care"),
    (r"password\s*=\s*['\"]", "likely hard-coded password"),
    (r"\.format\s*\(\s*\*\*", "format(**kwargs) may leak sensitive fields"),
    (r"verify\s*=\s*False", "TLS verification disabled — MITM risk"),
]


def check_security(source: str) -> list[str]:
    """Scan a source string and return a list of security issues."""
    issues = []
    for pattern, msg in SECURITY_PATTERNS:
        for m in re.finditer(pattern, source):
            line_no = source[: m.start()].count("\n") + 1
            issues.append(f"  L{line_no}: [SECURITY] {msg}")
    return issues


def check_ast(source: str) -> list[str]:
    """AST-level checks: too-long functions, too-many args, missing docstring."""
    issues = []
    try:
        tree = ast.parse(source)
    except SyntaxError as e:
        return [f"  L{e.lineno}: [SYNTAX] {e.msg}"]
    for node in ast.walk(tree):
        if isinstance(node, ast.FunctionDef):
            n_lines = (node.end_lineno or node.lineno) - node.lineno + 1
            if n_lines > 80:
                issues.append(f"  L{node.lineno}: [STYLE] function {node.name} is {n_lines} lines — consider splitting")
            if len(node.args.args) > 6:
                issues.append(f"  L{node.lineno}: [STYLE] function {node.name} has {len(node.args.args)} args — consider a dataclass")
            if not ast.get_docstring(node):
                issues.append(f"  L{node.lineno}: [STYLE] function {node.name} is missing a docstring")
    return issues


def main() -> int:
    if len(sys.argv) != 2:
        print("usage: lint.py <file>", file=sys.stderr)
        return 2
    path = Path(sys.argv[1])
    if not path.exists():
        print(f"file not found: {path}", file=sys.stderr)
        return 2
    source = path.read_text(encoding="utf-8")
    issues = check_ast(source) + check_security(source)
    if issues:
        print(f"=== {path.name}: {len(issues)} issue(s) ===", file=sys.stderr)
        for i in issues:
            print(i, file=sys.stderr)
        return 1
    print(f"=== {path.name}: OK ===")
    return 0


if __name__ == "__main__":
    sys.exit(main())

5. Step 4: add references/ (team standards docs)

Two Markdown files, 30-50 lines each, real and executable:

# references/style-guide.md

## Naming
- Variables / functions: `snake_case`; classes: `PascalCase`; constants: `UPPER_SNAKE`
- Boolean prefixes: `is_` / `has_` / `should_`
- Private methods / attributes: single underscore `_` prefix

## Functions
- A single function should be ≤ 80 lines
- ≤ 6 parameters — beyond that, use a dataclass / pydantic model
- Must have a docstring (Google style); the first line is a one-sentence summary

## Error handling
- Never use bare `except:` — always specify the exception type
- Use a custom exception class for business errors, not `raise Exception("...")`
- Catch + log + re-raise in the upper layer; do not swallow

## Type annotations
- 100% annotations on public functions
- Internal helpers: recommended, `Any` is allowed
- Use `from __future__ import annotations` for low-version compatibility

# references/security-checklist.md

## Mandatory (instant reject)
- `eval` / `exec` calls
- `pickle.loads` on untrusted data
- SQL string concatenation (must use parameterized queries)
- Hard-coded passwords / API keys / tokens
- Disabling TLS verification (`verify=False`)
- `subprocess` with `shell=True` AND concatenated user input

## Warning (require justification)
- Using `os.system` / `os.popen`
- Reflection / dynamic import of business modules
- Deserializing user-uploaded JSON / YAML
- Logging request body / tokens

## Recommended
- Read secrets from env vars / Vault
- Use the `secrets` module for randomness, not `random`
- Use an ORM or parameterized SQL

6. Step 5: local test

cd code-review
# Write an intentionally bad test file
cat > /tmp/bad.py << 'EOF'

def long_function(a, b, c, d, e, f, g, h):
    """Short docstring."""
    password = "admin123"
    eval("1+1")
    return a + b

def no_docstring():
    return 42
EOF

python scripts/lint.py /tmp/bad.py
echo "exit=$?"

Expected output (to stderr, exit=1):

=== bad.py: 4 issue(s) ===
  L3: [STYLE] function long_function has 8 args — consider a dataclass
  L9: [STYLE] function no_docstring is missing a docstring
  L5: [SECURITY] likely hard-coded password
  L6: [SECURITY] eval() is a code-injection risk

7. Step 6: publish to the team Git repo

# 1. Push to the team shared repo
git init
git add .
git commit -m "feat(skill): add code-review skill"
git remote add origin git@github.com:your-team/agent-skills.git
git push -u origin main

# 2. Register the repo as a Skill source in Claude Code / Cursor
# Claude Code: claude config set skills.sources https://github.com/your-team/agent-skills
# Cursor: Settings → Features → Add Skill Source

# 3. Teammates reload, then trigger with:
#    "use code-review to review the current branch"

8. Final directory structure

code-review/
├── SKILL.md                     # YAML frontmatter + workflow description
├── scripts/
│   └── lint.py                  # static checks + security scan (70 lines)
└── references/
    ├── style-guide.md           # team code style (40 lines)
    └── security-checklist.md    # security review checklist (35 lines)

9. Verify: use it in Claude Code

Open a new session and type:

Claude should:

1. Read SKILL.md to understand the workflow;
2. Run git diff main...HEAD --stat;
3. Run python scripts/lint.py <file> for each .py file;
4. Read both references docs;
5. Emit a Markdown report matching the "Output format" constraint (all 3 sections present).

If Claude does not auto-load the Skill, just symlink it under ~/.claude/skills/:

ln -s /path/to/agent-skills/code-review ~/.claude/skills/code-review

Screenshot: Claude's PR-comment report → copy to report.md or paste into GitHub PR's comment box and screenshot.