Agents Skills

Agent Skills - Meta Reference

This skill provides the definitive reference for creating, organizing, and maintaining agent skills. Use this when building new skills or improving existing skill architecture.

Quick Reference

Cross-Platform: Agent Skills are designed to be portable across runtimes (Claude Code, Codex CLI, Gemini CLI, VS Code Copilot).

Skill Structure

skills/
	└── skill-name/
	    ├── SKILL.md           # Main reference (required)
	    ├── scripts/           # Executable code (Python/Bash) - prefer running; read only to patch/review
	    │   └── validate.py
	    ├── references/        # Documentation loaded into context on-demand
	    │   ├── patterns.md
	    │   └── examples.md
    ├── assets/            # Files for OUTPUT (templates, icons, fonts)
    │   └── template.html
    └── data/
        └── sources.json   # External references

Directory purposes:

• scripts/ - Executable code; prefer running scripts and consuming output (read only when you need to modify/review)
• references/ - Documentation loaded into context when the agent needs it
• assets/ - Files used in generated output (not loaded into context)

Notes:

• Prefer executing scripts instead of pasting large code into context; read scripts only when you need to modify or review them.

SKILL.md Template

---
name: skill-name
description: One-line description of what this skill provides and when to use it (include trigger keywords here)
---

# Skill Name - Quick Reference

Brief overview of the skill's purpose and value.

## Quick Reference

| Task | Tool/Method | When to Use |
|------|-------------|-------------|
| Task 1 | Tool A | Context for usage |

## Scope (Optional)

Keep this brief; the primary trigger mechanism is the frontmatter `description`.

## Core Concepts

### Concept 1

Explanation with code example:

\`\`\`language
code example
\`\`\`

### Concept 2

Additional patterns...

## Navigation

**Resources**
- [references/skill-patterns.md](references/skill-patterns.md) - Common patterns
- [references/skill-validation.md](references/skill-validation.md) - Validation criteria

**Related Skills**
- [../agents-subagents/SKILL.md](../agents-subagents/SKILL.md) - Agent creation

Progressive Disclosure

Skills use progressive disclosure to optimize token usage:

Pattern: SKILL.md provides overview -> Resources load only when needed

Limits: Keep SKILL.md under 500 lines (<5K tokens)

When to Split Content

Frontmatter Specification

See references/frontmatter-reference.md for full specification, examples, and string substitutions.

Name rules:

• Use kebab-case: ai-llm, not AI_LLM_Engineering
• Match folder name exactly
• Be specific: software-backend not backend
• No claude or anthropic in names (reserved words)
• No XML angle brackets (< >) in any frontmatter value

Description rules (PRIMARY TRIGGER):

• The runtime uses descriptions to decide which skills to auto-invoke
• Format: [What it does]. Use when [trigger phrases].
• Target ~150 chars when library has 50+ skills (budget: 2% of context window, ~16K chars shared across ALL skill descriptions)
• Include key technologies/concepts as trigger keywords
• Single-line YAML only — no multiline >-

String substitutions (usable in skill body):

• $ARGUMENTS / $ARGUMENTS[N] / $N — user-provided arguments from /skill-name arg1 arg2
• ${CLAUDE_SESSION_ID} — current session identifier
• ${CLAUDE_SKILL_DIR} — absolute path to this skill's directory

Dynamic context injection: Use ` !command ` in the skill body to inject command output at load time.

Skill Categories

sources.json Schema

{
  "metadata": {
    "title": "Skill Name - Sources",
    "description": "Brief description",
    "last_updated": "YYYY-MM-DD",
    "skill": "skill-name"
  },
  "category_name": [
    {
      "name": "Resource Name",
      "url": "https://example.com/docs",
      "description": "What this covers",
      "add_as_web_search": true
    }
  ]
}

Categories should group logically:

• official_documentation
• tutorials
• community_resources
• tools_and_libraries

Quality Checklist

SKILL VALIDATION CHECKLIST

Frontmatter:
[ ] name matches folder name (kebab-case)
[ ] description is concise and actionable

Structure:
[ ] SKILL.md under 500 lines (split into references/ if needed)
[ ] references/ for detailed content
[ ] data/sources.json with curated links

Content:
[ ] Quick reference table at top
[ ] Frontmatter `description` includes trigger keywords
[ ] Code examples are copy-paste ready
[ ] Related skills linked at bottom

Quality:
[ ] >40% operational content (code, tables, checklists)
[ ] <50% prose paragraphs
[ ] All URLs are live (no 404s)
[ ] Sources updated within 6 months

Multi-Tech vs Single-Tech Skills

Single-Tech Skill

software-backend/
├── SKILL.md              # Node.js focus
└── references/
    └── nodejs-patterns.md

Multi-Tech Skill

software-backend/
├── SKILL.md              # Overview + decision tree
├── references/
│   ├── nodejs-patterns.md
│   ├── go-patterns.md
│   ├── rust-patterns.md
│   └── python-patterns.md
└── assets/
    ├── nodejs/
    ├── go/
    ├── rust/
    └── python/

Navigation

Resources

• references/anthropic-skills-guide.md - Anthropic's official skill-building guide (distilled)
• references/frontmatter-reference.md - Complete frontmatter field specification
• references/skill-patterns.md - Common skill patterns
• references/skill-validation.md - Validation criteria
• data/sources.json - Official documentation links

Related Skills

• ../agents-subagents/SKILL.md - Agent creation
• ../agents-hooks/SKILL.md - Hook automation
• ../agents-mcp/SKILL.md - MCP server integration

Fact-Checking

• Use web search/web fetch to verify current external facts, versions, pricing, deadlines, regulations, or platform behavior before final answers.
• Prefer primary sources; report source links and dates for volatile information.
• If web access is unavailable, state the limitation and mark guidance as unverified.

The Complete Guide to Building Skills for Claude — Reference

Distilled from Anthropic's official 30-page PDF guide (2026). Source: frameworks/shared-skills/The-Complete-Guide-to-Building-Skill-for-Claude.pdf

What Is a Skill

A folder containing SKILL.md (required) plus optional scripts/, references/, assets/ directories. Skills teach Claude how to do things — workflows, best practices, domain expertise. They complement MCP servers, which provide what Claude can access (tools, data).

MCP = connectivity (kitchen), Skills = knowledge (recipes).

Progressive Disclosure (3 Levels)

Key: Description budget = 2% of context window (~16K chars fallback) shared across ALL enabled skills. If total descriptions exceed budget, skills are silently excluded.

Three Skill Categories

1. Document & Asset Creation

Creating consistent output (documents, presentations, code, designs). Key techniques: embedded style guides, template structures, quality checklists, uses Claude's built-in capabilities.

2. Workflow Automation

Multi-step processes benefiting from consistent methodology. Key techniques: step-by-step workflow with validation gates, templates, built-in review suggestions, iterative refinement loops.

3. MCP Enhancement

Workflow guidance layered on top of MCP tool access. Key techniques: coordinates multiple MCP calls in sequence, embeds domain expertise, provides context users would otherwise specify, error handling for common MCP issues.

Technical Requirements

File Structure

your-skill-name/
├── SKILL.md              # Required - main skill file
├── scripts/              # Optional - executable code
├── references/           # Optional - documentation
├── assets/               # Optional - templates, etc.
└── data/
    └── sources.json      # Recommended - external references

Critical Rules

• SKILL.md must be exactly that name (case-sensitive, no variations)
• Folder name: kebab-case only, no spaces, capitals, or underscores
• No README.md inside skill folders (use SKILL.md or references/)
• No XML angle brackets (< >) in frontmatter (security: frontmatter appears in system prompt)
• No claude or anthropic in skill name (reserved)

Frontmatter (Required Fields)

---
name: your-skill-name
description: What it does. Use when user asks to [specific phrases].
---

• name: kebab-case, must match folder name
• description: MUST include WHAT + WHEN, under 1024 chars, no XML tags
• See frontmatter-reference.md for all optional fields

Description: The Most Important Part

The description is how Claude decides whether to load a skill. Structure:

[What it does] + [When to use it] + [Key capabilities]

Good examples:

# Specific and actionable
description: Analyzes Figma design files and generates developer handoff documentation. Use when user uploads .fig files, asks for "design specs", "component documentation", or "design-to-code handoff".

# Includes trigger phrases
description: Manages Linear project workflows including sprint planning, task creation, and status tracking. Use when user mentions "sprint", "Linear tasks", "project planning", or asks to "create tickets".

# Clear value proposition
description: End-to-end customer onboarding workflow for PayFlow. Handles account creation, payment setup, and subscription management. Use when user says "onboard new customer", "set up subscription", or "create PayFlow account".

Bad examples:

# Too vague
description: Helps with projects.

# Missing triggers
description: Creates sophisticated multi-page documentation systems.

# Too technical, no user triggers
description: Implements the Project entity model with hierarchical relationships.

For large libraries (50+ skills): Target ~150 chars per description to stay within the 16K shared budget.

Writing Effective Instructions

Be Specific and Actionable

# Good
Run `python scripts/validate.py --input {filename}` to check data format.
If validation fails, common issues include:
- Missing required fields (add them to the CSV)
- Invalid date formats (use YYYY-MM-DD)

# Bad
Validate the data before proceeding.

Reference Bundled Resources Clearly

Before writing queries, consult `references/api-patterns.md` for:
- Rate limiting guidance
- Pagination patterns
- Error codes and handling

Keep SKILL.md Focused

Move detailed documentation to references/ and link to it. Keep SKILL.md under 5,000 words.

Include Error Handling

## Common Issues

### MCP Connection Failed
If you see "Connection refused":
1. Verify MCP server is running
2. Confirm API key is valid
3. Try reconnecting

Success Metrics

Quantitative

• Skill triggers on 90% of relevant queries (test with 10-20 queries)
• Completes workflow in X tool calls (compare with/without skill)
• 0 failed API calls per workflow

Qualitative

• Users don't need to prompt Claude about next steps
• Workflows complete without user correction (test same request 3-5 times)
• Consistent results across sessions
• New users accomplish task on first try with minimal guidance

Testing Approach

1. Triggering Tests

Does the skill load when it should?

• Triggers on obvious tasks
• Triggers on paraphrased requests
• Does NOT trigger on unrelated topics

2. Functional Tests

Does it produce correct output?

• Valid outputs generated
• API calls succeed
• Error handling works
• Edge cases covered

3. Performance Comparison

Is it better than no skill? Compare same task with and without skill — count tool calls, tokens consumed, user corrections needed.

Pro tip: Iterate on a single task before expanding. Extract the winning approach into a skill.

Iteration Signals

Undertriggering (skill doesn't load when it should)

• Users manually enabling it
• Support questions about when to use it
• Fix: Add more detail and trigger phrases to description

Overtriggering (skill loads for irrelevant queries)

• Skill loads for unrelated queries
• Users disabling it
• Fix: Add negative triggers ("Do NOT use for..."), be more specific, clarify scope

Instructions Not Followed

• Too verbose: Keep concise, use bullet points
• Buried: Put critical instructions at top, use ## Important / ## Critical headers
• Ambiguous: Be specific (e.g., "CRITICAL: Before calling create_project, verify: - Project name is non-empty")
• Model laziness: Add explicit encouragement ("Take your time", "Do not skip validation steps")

Large Context Issues

• Optimize SKILL.md size: Move to references/, link instead of inline, keep under 5,000 words
• Reduce enabled skills: Evaluate if you have 20-50+ enabled simultaneously; consider selective enablement or skill packs

Patterns (from Early Adopters)

Problem-First vs Tool-First

• Problem-first: "I need to set up a project workspace" — skill orchestrates the right tools
• Tool-first: "I have Notion MCP connected" — skill teaches optimal workflows and best practices

Pattern 1: Sequential Workflow Orchestration

Multi-step processes in specific order. Key: explicit step ordering, dependencies between steps, validation at each stage, rollback instructions.

Pattern 2: Multi-MCP Coordination

Workflows spanning multiple services. Key: clear phase separation, data passing between MCPs, validation before next phase, centralized error handling.

Pattern 3: Iterative Refinement

Output improves with iteration. Key: explicit quality criteria, validation scripts, know when to stop.

Pattern 4: Context-Aware Tool Selection

Same outcome, different tools depending on context. Key: clear decision criteria, fallback options, transparency about choices.

Pattern 5: Domain-Specific Intelligence

Specialized knowledge beyond tool access. Key: domain expertise embedded in logic, compliance before action, comprehensive documentation, clear governance.

Distribution

Current Model (January 2026)

1. Download skill folder 2. Zip if needed 3. Upload via Claude.ai Settings > Capabilities > Skills, or place in Claude Code skills directory

Organization-Level

Admins deploy skills workspace-wide with automatic updates and centralized management.

Skills API

• /v1/skills endpoint for listing and managing
• container.skills parameter in Messages API
• Version control through Claude Console
• Works with Agent SDK

Open Standard

Skills are designed as a portable, open standard across platforms (Claude.ai, Claude Code, API). Use the compatibility field to note platform requirements.

Quick Checklist (Reference A)

Before You Start

• [ ] Identified 2-3 concrete use cases
• [ ] Tools identified (built-in or MCP)
• [ ] Reviewed guide and example skills
• [ ] Planned folder structure

During Development

• [ ] Folder named in kebab-case
• [ ] SKILL.md file exists (exact spelling)
• [ ] YAML frontmatter has --- delimiters
• [ ] name field: kebab-case, no spaces, no capitals
• [ ] description includes WHAT and WHEN
• [ ] No XML tags (< >) in frontmatter
• [ ] Instructions are clear and actionable
• [ ] Error handling included
• [ ] Examples provided
• [ ] References clearly linked

Before Upload

• [ ] Tested triggering on obvious tasks
• [ ] Tested triggering on paraphrased requests
• [ ] Verified doesn't trigger on unrelated topics
• [ ] Functional tests pass
• [ ] Tool integration works (if applicable)
• [ ] Compressed as .zip file

After Upload

• [ ] Test in real conversations
• [ ] Monitor for under/over-triggering
• [ ] Collect user feedback
• [ ] Iterate on description and instructions
• [ ] Update version in metadata

Official Resources

• Best Practices Guide (Anthropic docs)
• Skills Documentation (Anthropic docs)
• API Reference (Anthropic docs)
• MCP Documentation (Anthropic docs)
• Example skills: anthropic/skills on GitHub
• Bug reports: anthropic/skills/issues on GitHub
• Community: Claude Developers Discord
• Built-in tool: skill-creator in Claude.ai and Claude Code

Frontmatter Reference

Complete specification for SKILL.md YAML frontmatter fields. For an overview, see the main SKILL.md.

Required Fields

name

Unique identifier matching the skill's folder name.

name: software-backend

• Kebab-case only: a-z, 0-9, -
• Must exactly match the containing directory name
• Forbidden words: claude, anthropic (reserved)

description

The primary trigger mechanism. The runtime reads all descriptions to decide which skills to auto-invoke.

description: Production backend APIs for Node.js, Python, Go, and Rust. Use when building REST/GraphQL services or auth.

• Format: [What it does]. Use when [trigger phrases].
• Target ~150 chars per skill when library exceeds 50 skills
• Budget: 2% of context window (~16,000 chars fallback) is shared across ALL skill descriptions; exceeding it causes silent skill exclusion
• Single-line YAML — avoid multiline >- for descriptions
• Include technology names and action verbs as trigger keywords
• Override budget via env var SLASH_COMMAND_TOOL_CHAR_BUDGET (not recommended)

Invocation Control Fields

argument-hint

Autocomplete hint displayed in the / slash-command menu.

argument-hint: "[issue-number]"

Shown as: /skill-name [issue-number]

disable-model-invocation

Prevents the model from auto-triggering this skill. User must explicitly invoke via /skill-name.

disable-model-invocation: true

Use for: project-specific skills, meta-orchestration, skills the user always invokes explicitly.

user-invocable

Controls visibility in the / slash-command menu.

user-invocable: false

• true (default): appears in menu and can be invoked with /skill-name
• false: hidden from menu; used as background context or auto-triggered only

allowed-tools

Restricts which tools the skill can use. Comma-separated list.

allowed-tools: Read, Grep, Glob, Bash(python *)

• Omit to allow all tools (default)
• Supports glob patterns for Bash: Bash(python *) allows only python commands
• Use for read-only analysis skills or skills that need specific tool subsets

Execution Context Fields

context

Controls execution context for the skill.

context: fork

• fork: runs the skill body in a subagent (separate context window)
• Omit for normal inline execution (default)

agent

Specifies which subagent type to use when context: fork.

context: fork
agent: Explore

Options: Explore, Plan, general-purpose, or custom agent names defined in .claude/agents/.

model

Overrides the model used when executing this skill.

model: sonnet

Options: opus, sonnet, haiku. Useful for cost control or when a skill needs maximum capability.

hooks

Lifecycle hooks scoped to this skill. Same format as settings hooks but only active when this skill is loaded.

hooks:
  PreToolUse:
    - matcher: Write
      command: "echo 'File write detected'"

Metadata Fields

license

License identifier for the skill.

license: MIT

compatibility

Platform or version compatibility notes (1-500 chars).

compatibility: Claude Code 1.0+, Codex CLI 0.5+

metadata

Additional metadata as key-value pairs.

metadata:
  author: team-name
  version: "2.1"
  mcp-server: github

String Substitutions

Available in the skill body (content after frontmatter):

Example:

---
name: review-issue
description: Reviews a GitHub issue. Use when asked to review or triage an issue by number.
argument-hint: "[issue-number]"
---

Fetch and review GitHub issue #$1 for the current repository.
Use `gh issue view $1` to get the details.
Load additional context from `${CLAUDE_SKILL_DIR}/references/review-checklist.md`.

Dynamic Context Injection

Use ` !command ` syntax in the skill body to inject command output at skill load time:

Current git status:
!`git status --short`

Recent commits:
!`git log --oneline -5`

The command runs when the skill activates and its stdout replaces the ` !command ` line.

Security Restrictions

1. No XML angle brackets (<, >) in frontmatter values — they conflict with system prompt parsing 2. No reserved words in name: claude, anthropic 3. No secrets in frontmatter or skill body — use environment variables 4. `allowed-tools` should follow least-privilege: only grant tools the skill actually needs

Complete Example

---
name: dev-review-pr
description: Reviews pull requests for code quality and security. Use when reviewing PRs, diffs, or merge requests.
argument-hint: "[PR-number]"
allowed-tools: Read, Grep, Glob, Bash(gh *)
model: sonnet
metadata:
  author: engineering
  version: "1.0"
---

Related

• skill-patterns.md - Common skill organizational patterns
• skill-validation.md - Validation criteria and scripts
• ../SKILL.md - Main agents-skills reference

Skill Patterns

Common patterns for organizing and structuring agent skills.

Pattern 1: Single-Domain Skill

For skills focused on one technology or concept.

skill-name/
├── SKILL.md           # Core patterns + quick reference
├── data/
│   └── sources.json   # Official docs, tutorials
└── references/
    └── advanced.md    # Edge cases, deep dives

When to use: Technology-specific skills (e.g., testing-playwright, document-pdf)

Pattern 2: Multi-Tech Skill

For skills covering multiple implementations of same concept.

software-backend/
├── SKILL.md              # Decision tree + common patterns
├── data/
│   └── sources.json
├── references/
│   ├── nodejs-patterns.md
│   ├── python-patterns.md
│   ├── go-patterns.md
│   └── rust-patterns.md
└── assets/
    ├── nodejs/
    ├── python/
    ├── go/
    └── rust/

When to use: Skills with framework/language variants

Pattern 3: Workflow Skill

For skills that guide multi-step processes.

dev-workflow-planning/
├── SKILL.md              # Workflow overview + decision points
├── references/
│   ├── phase-1-discovery.md
│   ├── phase-2-design.md
│   ├── phase-3-implementation.md
│   └── phase-4-review.md
└── assets/
    ├── planning-checklist.md
    └── review-template.md

When to use: Process-oriented skills (planning, review, deployment)

Pattern 4: Reference Skill

For skills that primarily provide lookup information.

data-sql-optimization/
├── SKILL.md              # Quick syntax reference
├── data/
│   └── sources.json
└── references/
    ├── postgres-specifics.md
    ├── mysql-specifics.md
    ├── optimization-patterns.md
    └── common-queries.md

When to use: Reference materials, syntax guides, cheat sheets

Pattern 5: Script Execution

Skills can bundle executable scripts that the assistant can run instead of generating large code blocks.

When to Execute vs Read

Script Execution Pattern

skill-name/
├── SKILL.md
└── scripts/
    ├── validate.py      # Assistant runs this
    ├── generate.sh      # Assistant runs this
    └── complex_algo.py  # Assistant reads this when needed

In SKILL.md:

## Validation
Run `scripts/validate.py <input>` to check format.

## Algorithm Reference
See `scripts/complex_algo.py` for the scoring algorithm logic.

Key benefit: Script output consumes tokens, but script code does NOT load into context. More efficient than generating equivalent code.

File Naming Best Practices

SKILL.md Content Patterns

Quick Reference Table

Always include at top for fast lookup:

| Task | Command/Pattern | Notes |
|------|-----------------|-------|
| Create X | `code example` | When to use |
| Debug Y | `another example` | Common pitfall |

Decision Tree

For multi-option skills:

## Choosing the Right Approach

**Need real-time updates?**
-> Yes: Use WebSockets (`references/websockets.md`)
-> No: Use REST (`references/rest-patterns.md`)

**High throughput required?**
-> Yes: Consider Go or Rust
-> No: Node.js or Python sufficient

Trigger Keywords

Include in description for better discovery:

description: Backend API development with Node.js, Express, Fastify, REST, GraphQL, authentication, database integration, and microservices patterns.

Anti-Patterns

Too Broad

# BAD: Too vague, triggers on everything
name: programming
description: Help with programming tasks

Too Narrow

# BAD: Too specific, rarely triggers
name: express-middleware-error-handling-async
description: Handle async errors in Express middleware

Missing Context

# BAD: No trigger words, poor discovery
name: backend
description: Backend development

Good Balance

# GOOD: Specific domain with clear triggers
name: software-backend
description: Backend API development with Node.js, Python, Go, or Rust including REST/GraphQL APIs, authentication, database integration, and deployment patterns.

Related

• skill-validation.md - Validation criteria
• ../SKILL.md - Main skill reference

Skill Validation Criteria

Comprehensive checklist for validating agent skills.

Validation Levels

1. Frontmatter Validation (Critical)

# Check first 5 lines
head -5 SKILL.md

Requirements:

Validation regex:

# Name format
grep -E "^name: [a-z0-9-]+$" SKILL.md

# Description length
desc=$(grep "^description:" SKILL.md | cut -d: -f2-)
echo ${#desc}  # Should be 50-300

2. Directory Structure

Required:

skill-name/
└── SKILL.md           # Must exist

Recommended:

skill-name/
├── SKILL.md
├── data/
│   └── sources.json   # Curated external links
└── references/         # If referenced in SKILL.md

Validation:

# Check required file
[ -f "SKILL.md" ] && echo "PASS" || echo "FAIL: Missing SKILL.md"

# Check for orphan references
grep -oE '\[.*\]\(references/[^)]+\)' SKILL.md | while read link; do
  path=$(echo "$link" | grep -oE 'references/[^)]+')
  [ -f "$path" ] || echo "DEAD LINK: $path"
done

3. Reference Link Validation (Critical)

All markdown links must resolve:

# Extract and validate all relative links
grep -oE '\]\([^http][^)]+\)' SKILL.md | tr -d '()' | cut -d']' -f2 | while read path; do
  [ -e "$path" ] || echo "DEAD: $path"
done

Common issues:

4. sources.json Validation

Schema check:

# Valid JSON
python3 -m json.tool data/sources.json > /dev/null && echo "PASS"

# Required fields
jq '.metadata.last_updated' data/sources.json  # Must exist
jq '.metadata.skill' data/sources.json         # Must match folder

URL validation:

# All URLs must be HTTPS
jq -r '.. | .url? // empty' data/sources.json | grep -v "^https://" && echo "FAIL: Non-HTTPS URL"

# Check for redirects (warning)
jq -r '.. | .url? // empty' data/sources.json | while read url; do
  status=$(curl -sI "$url" | head -1 | cut -d' ' -f2)
  [ "$status" = "301" ] && echo "REDIRECT: $url"
done

Freshness:

# Last updated within 6 months
last=$(jq -r '.metadata.last_updated' data/sources.json)
# Compare with current date

5. Content Quality

Required Sections

Operational Content Ratio

Target: >40% operational (code, tables, checklists)

# Count operational lines
total=$(wc -l < SKILL.md)
code=$(grep -c '```' SKILL.md)
tables=$(grep -c '^|' SKILL.md)
lists=$(grep -c '^- \[' SKILL.md)

operational=$((code + tables + lists))
ratio=$((operational * 100 / total))
echo "Operational: ${ratio}%"

Anti-Fluff Check

Flag excessive prose:

# Paragraphs without code/lists
awk '/^[A-Z].*\.$/ && !/```/ && !/^|/ && !/^-/' SKILL.md | wc -l

6. Best Practices Alignment (Web Search)

Automated checks:

1. Search: "[skill topic] best practices 2025 2026" 2. Compare skill content with top 3 results 3. Flag deprecated tools/patterns

Manual review:

7. Security Validation

# No shell injection patterns
grep -E '\$\(|`.*`|\beval\b' SKILL.md && echo "WARN: Potential injection"

# No credential patterns
grep -Ei 'password|secret|api.?key|token' SKILL.md && echo "WARN: Credential reference"

# No file access outside workspace
grep -E '\.\./\.\./|/etc/|/usr/' SKILL.md && echo "WARN: External path"

Validation Output Format

## Validation Summary

- **Status**: [PASS | FAIL | WARNING]
- **Skill**: `skill-name`
- **Issues**: X critical, Y warnings

## Critical Issues
[List or "None"]

## Warnings
[List or "None"]

## Recommendations
[List or "None"]

Quick Validation Script

#!/bin/bash
SKILL_DIR="$1"

echo "Validating: $SKILL_DIR"

# 1. SKILL.md exists
[ -f "$SKILL_DIR/SKILL.md" ] || { echo "FAIL: Missing SKILL.md"; exit 1; }

# 2. Frontmatter valid
head -1 "$SKILL_DIR/SKILL.md" | grep -q "^---$" || echo "WARN: Missing frontmatter"

# 3. Name matches folder
name=$(grep "^name:" "$SKILL_DIR/SKILL.md" | cut -d: -f2 | tr -d ' ')
folder=$(basename "$SKILL_DIR")
[ "$name" = "$folder" ] || echo "FAIL: Name mismatch ($name != $folder)"

# 4. sources.json valid
if [ -f "$SKILL_DIR/data/sources.json" ]; then
  python3 -m json.tool "$SKILL_DIR/data/sources.json" > /dev/null || echo "FAIL: Invalid JSON"
fi

# 5. Dead links
grep -oE '\]\(references/[^)]+\)' "$SKILL_DIR/SKILL.md" | while read link; do
  path=$(echo "$link" | grep -oE 'references/[^)]+')
  [ -f "$SKILL_DIR/$path" ] || echo "DEAD LINK: $path"
done

echo "Validation complete"

Related

• skill-patterns.md - Common skill patterns
• ../SKILL.md - Main skill reference