# https://github.com/heilcheng/awesome-agent-skills 项目说明书 生成时间：2026-05-15 16:29:49 UTC ## 目录 - [Project Introduction](#project-introduction) - [Quick Start Guide](#quick-start-guide) - [Compatible Agents](#compatible-agents) - [Next.js Website Structure](#nextjs-structure) - [Component Architecture](#component-architecture) - [Skill Directories](#skill-directories) - [Skill Quality Standards](#skill-quality-standards) - [Using and Creating Skills](#using-creating-skills) - [Internationalization (i18n)](#internationalization) - [Deployment Configuration](#deployment-config) ## Project Introduction ### 相关页面 相关主题：[Quick Start Guide](#quick-start-guide), [Compatible Agents](#compatible-agents)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.md) - [CONTRIBUTING.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/CONTRIBUTING.md) - [website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html) - [website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx) - [website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx) - [README.ko.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.ko.md)
# Project Introduction ## Overview **awesome-agent-skills** is a curated, community-maintained collection of AI agent skills designed to extend the capabilities of AI assistants across multiple platforms. The repository serves as a central directory where developers and users can discover, share, and deploy reusable skill packages for various AI agent implementations. 资料来源：[website/index.html]() ### What Are Agent Skills? Agent Skills are portable instruction files that teach AI assistants how to perform specific tasks. Think of them as **loadable expertise**: domain knowledge, team conventions, and repeatable workflows that your agent can access exactly when needed. The skill format was originally developed by Anthropic and released as an open standard. It has since been adopted by over 30 agent products, making skills a truly cross-platform solution for extending AI capabilities. 资料来源：[website/index.html]() --- ## Project Purpose and Scope ### Primary Objectives | Objective | Description | |-----------|-------------| | **Discovery** | Provide a searchable directory of high-quality agent skills | | **Sharing** | Enable easy distribution of skills via GitHub repositories | | **Compatibility** | Support 30+ agent platforms without modification | | **Quality** | Establish standards for skill authorship and documentation | 资料来源：[README.ko.md]() 资料来源：[website/src/components/sections/QualityStandards.tsx]() ### Target Audiences The project serves three distinct user groups: 1. **Complete Newcomers** — Users who simply want to add capabilities to their AI assistant by copying a GitHub URL 2. **Teams and Enterprises** — Organizations capturing institutional knowledge in version-controlled, portable packages 3. **Skill Authors** — Developers building reusable capabilities to deploy across multiple agents 资料来源：[website/index.html]() --- ## Architecture Overview ### Skill Package Structure Each skill is a folder containing a `SKILL.md` file with YAML frontmatter metadata and Markdown body instructions. ``` my-skill/ ├── SKILL.md # Required: metadata + instructions └── scripts/ # Optional: executable helper scripts └── run.sh ``` 资料来源：[website/index.html]() ### Progressive Disclosure Model Agent Skills utilize a two-stage loading mechanism to maintain performance: ```mermaid graph TD A[Agent Startup] --> B[Discovery Phase] B --> C[Load name + description
~50-100 tokens per skill] C --> D[Lightweight scan complete
No instructions loaded] D --> E[User Task Request] E --> F{Task matches
skill description?} F -->|Yes| G[Activation Phase] F -->|No| H[Standard Response] G --> I[Load full SKILL.md
+ scripts into context] I --> J[Execute Skill Instructions] ``` This design ensures agents remain fast while having access to extensive knowledge on demand. 资料来源：[website/index.html]() --- ## Core Components ### 1. The SKILL.md Format The `SKILL.md` file is the fundamental building block of the agent skills ecosystem. It combines metadata (in YAML frontmatter) with instructional content (in Markdown body). #### Frontmatter Fields | Field | Required | Description | |-------|----------|-------------| | `name` | Yes | Lowercase alphanumeric + hyphens, 1-64 characters | | `description` | Yes | 1-1024 characters; triggers skill activation | | `license` | No | License name or reference to bundled file | | `compatibility` | No | 1-500 characters describing requirements | | `allowed-tools` | No | Space-delimited list of pre-approved tools | | `metadata` | No | Arbitrary key-value pairs for additional info | 资料来源：[website/index.html]() #### Minimal SKILL.md Example ```yaml --- name: roll-dice description: Roll dice using a random number generator. Use when asked to roll a die (d6, d20, etc.). --- To roll a die, run: ```bash echo $((RANDOM % + 1)) ``` ``` 资料来源：[website/index.html]() ### 2. Complete SKILL.md Example ```yaml --- name: pdf-processing description: > Extract text and tables from PDF files, fill PDF forms, and merge multiple PDFs. Use when working with PDF documents, forms, or when the user mentions PDFs, document extraction, or form filling. license: Apache-2.0 compatibility: Requires Python 3.11+ and uv metadata: author: example-org version: "1.0" allowed-tools: Bash(uv:*) Read Write --- ## When to use this skill Activate when the user needs to extract text, fill forms, or merge PDFs. ## Instructions 1. Verify the input is a valid PDF. 2. Run the appropriate script from scripts/. 3. Validate output before returning. ## Gotchas - Scanned PDFs require OCR (scripts/ocr.py) - Password-protected files need scripts/unlock.py ``` 资料来源：[website/index.html]() ### 3. Website Directory The [website/](https://github.com/heilcheng/awesome-agent-skills/tree/main/website) directory contains a Next.js application that provides: - Interactive skill directory with search functionality - SKILL.md format reference documentation - Quality standards guidelines - "How to use skills" tutorials - Compatible agents listing The website dynamically renders skills from the repository into searchable cards for easy discovery. 资料来源：[website/src/components/sections/UsingSkills.tsx]() ### 4. CLI Tool Integration The project supports the `npx skills` CLI tool (from [vercel-labs/skills](https://github.com/vercel-labs/skills)) for managing skills locally: | Command | Description | |---------|-------------| | `npx skills find [query]` | Search for relevant skills | | `npx skills add ` | Add a skill from GitHub | | `npx skills list` | List installed skills | | `npx skills check` | Check for updates | | `npx skills update` | Upgrade all skills | | `npx skills remove [name]` | Remove a skill | 资料来源：[README.ko.md]() --- ## Compatible Agent Platforms Agent Skills is an open standard adopted by leading AI development tools. Skills created for this ecosystem work across all supported platforms without modification. | Platform | Status | |----------|--------| | Claude Code | Fully supported | | Claude.ai | Fully supported | | OpenAI Codex | Fully supported | | GitHub Copilot | Fully supported | | Cursor | Fully supported | | Gemini CLI | Fully supported | 资料来源：[website/index.html]() 资料来源：[README.ko.md]() --- ## Skill Storage Locations Skills can be placed in multiple directories depending on your agent platform: ```mermaid graph LR A[User Home] --> B[~/.claude/skills/] A --> C[~/.agents/skills/] D[Project Root] --> E[.github/skills/] D --> F[.agents/skills/] B --> G[Claude-specific] C --> H[Generic agents] E --> I[GitHub-integrated] F --> H ``` | Location | Typical Use | |----------|-------------| | `~/.claude/skills/` | Claude Code/Claude.ai skills | | `~/.agents/skills/` | Generic agent tools | | `.github/skills/` | Repository-specific skills (Cursor, Claude Code) | | `.agents/skills/` | Project-local skills | 资料来源：[website/index.html]() 资料来源：[website/src/components/sections/UsingSkills.tsx]() --- ## Quality Standards The project maintains quality standards for contributed skills: ### Recommended Skill Structure | Section | Purpose | |---------|---------| | **When to use this skill** | Trigger conditions, scope, and limitations | | **Instructions** | Step-by-step procedure; be explicit | | **Gotchas** | Environment-specific facts that defy expectations | | **Examples** | Concrete input → output pairs | | **Validation** | How to verify the output is correct | ### Best Practices | # | Guideline | Description | |---|-----------|-------------| | 01 | Be concrete, not conceptual | Use specific names, paths, and commands | | 02 | Design coherent scope | Aim for under 500 lines, under 5,000 tokens | | 03 | Add what agents lack | Focus on project conventions and edge cases | | 04 | Be prescriptive when needed | Strict for fragile or irreversible operations | | 05 | Make scripts agent-friendly | Non-interactive, structured output, meaningful exit codes | | 06 | Build validation loops | Have the agent verify its own work before returning | 资料来源：[website/src/components/sections/QualityStandards.tsx]() 资料来源：[website/index.html]() --- ## Workflow: Using a Skill ```mermaid sequenceDiagram participant U as User participant A as AI Agent participant G as GitHub participant S as Skill Directory U->>A: Find desired skill in directory U->>G: Copy skill GitHub URL U->>A: Paste URL or use /skills add command A->>G: Fetch SKILL.md content G-->>A: Return skill file A->>S: Store skill in local skills directory U->>A: Request task matching skill A->>S: Load skill (activation) A->>U: Execute skill instructions ``` 资料来源：[website/src/components/sections/UsingSkills.tsx]() --- ## Contributing The project welcomes contributions from the community. Contributors should: 1. Follow the SKILL.md format specification 2. Ensure skills work across multiple agent platforms 3. Include clear instructions and validation steps 4. Test skills before submitting 资料来源：[CONTRIBUTING.md]() 资料来源：[website/src/components/sections/QualityStandards.tsx]() --- ## Summary **awesome-agent-skills** is more than just a list — it's a gateway to extending AI agent capabilities through a standardized, portable, and community-driven approach. By understanding the core concepts of: - **SKILL.md format** with its YAML frontmatter and Markdown body - **Progressive disclosure** for performance optimization - **Multi-platform compatibility** across 30+ agents - **Quality standards** for reliable skill authorship ...you can effectively leverage and contribute to this growing ecosystem of AI agent capabilities. 资料来源：[website/index.html]() 资料来源：[README.ko.md]() --- ## Quick Start Guide ### 相关页面 相关主题：[Project Introduction](#project-introduction), [Using and Creating Skills](#using-creating-skills)
相关源码文件 以下源码文件用于生成本页说明： - [website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html) - [website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx) - [website/src/components/sections/Contributing.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/Contributing.tsx) - [website/src/components/sections/Tutorials.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/Tutorials.tsx) - [website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx) - [website/src/components/Footer.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Footer.tsx)
# Quick Start Guide ## Overview The **Agent Skill Index** is a curated collection of AI agent skills—portable instruction files that teach AI assistants how to perform specific tasks. Skills are designed as `SKILL.md` files containing YAML frontmatter and plain-English instructions that agents can load on demand. The repository serves three primary audiences: | Audience | Use Case | |----------|----------| | **Complete newcomers** | Find a skill, copy its GitHub URL, paste it into an AI chat | | **Teams and enterprises** | Capture organizational knowledge in portable, version-controlled packages | | **Skill authors** | Build capabilities once and deploy across any skills-compatible agent | 资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html) ## Three-Step Workflow Getting started with Agent Skills follows a simple three-step process: ```mermaid graph TD A[Find a Skill] --> B[Load into AI] B --> C[Ask in Plain English] ``` ### Step 1: Find a Skill Browse the skills directory on the website. Skills are organized by category including development, data, automation, and security. Each card links directly to the skill on GitHub. 资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html) ### Step 2: Load It Into Your AI Copy the GitHub URL and add it to your AI agent. Each platform supports different methods: | Platform | Command / Method | |----------|------------------| | **Claude Code** | `/skills add ` | | **Claude.ai** | Paste raw SKILL.md URL in chat | | **Other CLI tools** | `npx skills add anthropics/skills/docx` | Alternatively, you can manually place skill folders into supported directories: ``` .github/skills/skill-name/ ``` 资料来源：[website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx) ### Step 3: Ask in Plain English Simply tell your AI what you want. The agent reads the skill instructions automatically and executes accordingly. No commands to memorize, no configuration required. 资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html) ## SKILL.md Format Every skill is a folder containing a `SKILL.md` file. The file uses YAML frontmatter followed by plain Markdown content. ### Required Frontmatter Fields | Field | Type | Description | |-------|------|-------------| | `name` | Required | Lowercase alphanumeric + hyphens only, 1–64 characters, must match parent directory | | `description` | Required | 1–256 characters describing when to use the skill | ### Optional Frontmatter Fields | Field | Type | Description | |-------|------|-------------| | `license` | Optional | License identifier (e.g., Apache-2.0) | | `compatibility` | Optional | Environment requirements | | `version` | Optional | Semantic version string | | `allowed-tools` | Optional · Experimental | Space-delimited list of pre-approved tools (e.g., `Bash(git:*) Read Write`) | ### Recommended Body Structure The Markdown body is free-form, but the documentation recommends these sections: ```markdown ## When to use this skill Trigger conditions, scope, and limitations. ## Instructions Step-by-step procedure. Be explicit. ## Gotchas Environment-specific facts. Things that defy expectations. ## Examples Concrete input → output pairs. ## Validation How to verify the output is correct. ``` 资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html) ### Minimal Example ```yaml --- name: roll-dice description: Roll dice using a random number generator. Use when asked to roll a die (d6, d20, etc.). --- To roll a die, run: ```bash echo $((RANDOM % + 1)) ``` ``` ### Complete Example ```yaml --- name: pdf-processing description: > Extract text and tables from PDF files, fill PDF forms, and merge multiple PDFs. Use when working with PDF documents, forms, or when the user mentions PDFs, document extraction, or form filling. license: Apache-2.0 compatibility: Requires Python 3.11+ and uv metadata: author: example-org version: "1.0" allowed-tools: Bash(uv:*) Read Write --- ## When to use this skill Activate when the user needs to extract text, fill forms, or merge PDFs. ## Instructions 1. Verify the input is a valid PDF. 2. Run the appropriate script from scripts/. 3. Validate output before returning. ## Gotchas - Scanned PDFs require OCR (scripts/ocr.py, not scripts/extract.py) - Password-protected PDFs need decryption first ``` 资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html) ## How Skills Load The system uses **progressive disclosure** for efficiency: ```mermaid graph TD A[Agent Startup] --> B[Lightweight Scan] B --> C[Load name + description only] C --> D[~50-100 tokens per skill] D --> E[Task Matches Description?] E -->|Yes| F[Load Full SKILL.md] E -->|No| G[Stay Unloaded] F --> H[Execute Instructions] ``` At startup, agents load only the `name` and `description` of every available skill. Full instructions are loaded only when a task matches a skill's description. 资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html) ## Compatible Platforms Agent Skills is an open standard adopted by 30+ platforms: | Category | Platforms | |----------|-----------| | Anthropic | Claude Code, Claude.ai | | OpenAI | Codex | | Microsoft | GitHub Copilot | | Others | Cursor, Gemini CLI, and more | Skills you create work across all these platforms without modification. 资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html) ## Creating Your First Skill To create a skill: 1. **Create a folder** named after your skill (lowercase, hyphens only) 2. **Add `SKILL.md`** inside with required frontmatter 3. **Write instructions** in plain English below 4. **Place the folder** in `.claude/skills/` or `.github/skills/` depending on your AI tool For detailed guidelines, refer to the [Creating Custom Skills documentation](https://support.claude.com/en/articles/12512198-creating-custom-skills). 资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html) ## Skill Quality Standards High-quality skills follow these patterns: | Pattern | Example | |---------|---------| | **Good** | "Before committing, run tests and confirm green. If tests fail, fix then re-run." | | **Bad** | Vague or incomplete instructions without validation steps | Scripts within skills should be designed to be agent-friendly: - Avoid interactive prompts - Use structured output (JSON/CSV) - Write errors to stderr - Exit with meaningful codes 资料来源：[website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx) ## Adding Optional Scripts Place executable files in a `scripts/` subdirectory. Scripts can use PEP 723 inline dependencies: ```bash #!/usr/bin/env -S uv run # /// script # requires-python = ">= 3.11" # dependencies = ["requests", "rich"] # /// import sys, json print(json.dumps({"result": "ok"})) ``` 资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html) ## Learning Resources The repository provides tutorials for different experience levels: | Tutorial | Platform | Description | |----------|----------|-------------| | Building your first MCP server | Model Context Protocol | Step-by-step guide to creating MCP servers | Additional resources are available through the [Tutorials section](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/Tutorials.tsx). 资料来源：[website/src/components/sections/Tutorials.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/Tutorials.tsx) ## Contributing To contribute new skills or improve existing ones: 1. Read the [Contributing Guide](https://github.com/heilcheng/awesome-agent-skills/blob/main/CONTRIBUTING.md) 2. Review quality standards before submission 3. Use GitHub Discussions for questions and ideas 资料来源：[website/src/components/sections/Contributing.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/Contributing.tsx) ## Quick Reference | Item | Command / Path | |------|----------------| | Skills directory | `.claude/skills/` or `.github/skills/` | | Add via CLI | `npx skills add ` | | Add via Claude Code | `/skills add ` | | Manual path | `.github/skills/skill-name/` | | Required files | `SKILL.md` with `name` and `description` | | Optional directory | `scripts/` for executable files | 资料来源：[website/src/components/Footer.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Footer.tsx) --- ## Compatible Agents ### 相关页面 相关主题：[Project Introduction](#project-introduction), [Skill Directories](#skill-directories)
Relevant Source Files The following source files were used to generate this page: - [README.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.md) - [website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html) - [website/src/components/Footer.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Footer.tsx) - [README.ko.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.ko.md)
# Compatible Agents Agent Skills is an open standard that has been adopted by leading AI development tools and platforms. This document provides a comprehensive overview of the compatible agents ecosystem, explaining how skills work across different platforms, the supported agent list, and how to leverage cross-platform compatibility. ## Overview Agent Skills were originally developed by Anthropic as an open standard for packaging and distributing reusable instructions for AI assistants. The format was designed with portability as a core principle — skills created for one agent platform can work seamlessly on any other platform that implements the specification. The ecosystem now includes **30+ agent products** that support the SKILL.md format. This widespread adoption means that skill authors can write instructions once and deploy them across multiple platforms without modification, while users can share and discover skills that work with their preferred AI tools. 资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html) ## How Skills Work Across Platforms The Agent Skills system uses a lightweight discovery mechanism that enables cross-platform compatibility. At startup, agents scan configured directories and load only the `name` and `description` fields from each skill's SKILL.md file — approximately 50–100 tokens per skill. This keeps startup performance fast while allowing the agent to know what capabilities are available. When a user's task matches a skill's description, the agent loads the complete SKILL.md file into context, executing the instructions and using any provided scripts. This on-demand loading pattern ensures that skills are only consumed when relevant, maintaining efficient resource usage. ```mermaid graph TD A[Agent Startup] --> B[Scan Skills Directories] B --> C[Load name + description only] C --> D[Skill Discovery Complete] D --> E[User Request] E --> F{Does request match skill?} F -->|Yes| G[Load Full SKILL.md] F -->|No| H[Process without skill] G --> I[Execute Instructions] H --> J[Return Response] I --> J ``` 资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html) ## Supported Agent Platforms The following table lists the major agent platforms that support the Agent Skills standard: | Platform | Documentation | |----------|---------------| | Claude Code | [code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills) | | Claude.ai | [support.claude.com](https://support.claude.com/en/articles/12512180-using-skills-in-claude) | | OpenAI Codex | [developers.openai.com](https://developers.openai.com/docs/agents) | | GitHub Copilot | [github.com/features/copilot](https://github.com/features/copilot) | | Cursor | [cursor.com](https://cursor.com) | | Gemini CLI | [google.github.io](https://google.github.io/gemini-cli/) | 资料来源：[README.ko.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.ko.md) ### Complete Platform List The ecosystem includes over 30 platforms that have adopted the Agent Skills standard. Based on the website documentation, the full list of supported platforms includes: | Category | Platforms | |----------|-----------| | Anthropic | Claude Code, Claude.ai | | OpenAI | Codex | | Microsoft | GitHub Copilot | | General AI | Cursor, Gemini CLI | | Development Tools | Multiple integrated development environments | 资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html) ## Skills Installation Methods by Platform Different agent platforms support various methods for adding and managing skills. Understanding these installation methods is essential for effectively using the skill ecosystem. ### Claude Code CLI For Claude Code users, skills can be added directly through the command-line interface: ```bash /claude/skills add ``` ### Claude.ai Web Interface Claude.ai users can paste the raw SKILL.md URL directly into their chat. The agent automatically detects and loads skill instructions when relevant context is provided. ### Manual File Placement For development workflows and offline scenarios, skills can be manually placed in platform-specific directories: | Platform | Directory Path | |----------|---------------| | Claude | `.claude/skills/` | | GitHub | `.github/skills/` | | General Agents | `.agents/skills/` | | User Home | `~/.agents/skills/` | 资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html) ### npx skills CLI Tool The `npx skills` command-line tool provides a unified interface for skill discovery, addition, and management across supported platforms: | Command | Description | |---------|-------------| | `npx skills find [query]` | Search for relevant skills | | `npx skills add ` | Add a skill from GitHub | | `npx skills list` | List installed skills | | `npx skills check` | Check for updates | | `npx skills update` | Update all skills | | `npx skills remove [skill-name]` | Remove a skill | 资料来源：[README.ko.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.ko.md) The tool supports multiple input formats: - **GitHub shorthand**: `owner/repo` - **Full URLs**: `https://github.com/owner/repo` - **Local paths**: Relative or absolute file paths ## Cross-Platform Compatibility Architecture The Agent Skills specification defines a standard format that ensures compatibility across all implementing platforms. This architecture consists of several layers: ```mermaid graph TD A[SKILL.md File] --> B[Frontmatter Metadata] A --> C[Markdown Body] B --> D[name field] B --> E[description field] B --> F[optional fields] C --> G[Instructions] C --> H[Examples] C --> I[Gotchas] C --> J[Validation steps] F --> K[license] F --> L[compatibility] F --> M[allowed-tools] ``` ### Required Frontmatter Fields Every SKILL.md file must include the following YAML frontmatter: | Field | Type | Description | Constraints | |-------|------|-------------|-------------| | `name` | string | Skill identifier | Lowercase alphanumeric + hyphens, 1–64 characters, must match directory name | | `description` | string | Human-readable description | 1–512 characters, used for skill discovery | ### Optional Frontmatter Fields | Field | Description | |-------|-------------| | `license` | License identifier (e.g., Apache-2.0) | | `compatibility` | Platform-specific requirements or dependencies | | `metadata` | Custom metadata including author and version | | `allowed-tools` | Pre-approved tools for the skill to use | 资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html) ## Skill Directory Structure Agent platforms scan specific directories to discover available skills. The standard directory structure ensures consistent behavior across all supported platforms: ``` .claude/skills/ # Claude Code and Claude.ai .github/skills/ # GitHub-integrated agents .agents/skills/ # General agent platforms ~/.agents/skills/ # User-level skills (user home directory) ``` Within each skills directory, skills are organized in subdirectories with the following structure: ``` / └── SKILL.md # Required: Contains frontmatter + instructions scripts/ # Optional: Executable scripts the skill can run ``` 资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html) ## Platform-Specific Considerations ### Claude Code Claude Code provides native support for skills through the `/skills` command: ```bash /claude/skills add ``` Skills installed via Claude Code are automatically scanned at startup and loaded when relevant. ### Claude.ai Web Claude.ai users can utilize skills by: 1. Copying a skill's GitHub URL 2. Pasting the raw SKILL.md URL into the chat The web interface automatically detects skill format and applies instructions as needed. ### Third-Party Platforms For platforms like Codex, Copilot, Cursor, and Gemini CLI, the specific skill loading mechanisms may vary. Users should consult individual platform documentation for detailed instructions on skill installation and usage. 资料来源：[website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html) ## Skill Discovery and Management The skill ecosystem supports multiple discovery mechanisms to help users find relevant skills: ### Direct URL Addition Users can directly add skills by providing GitHub repository URLs or shorthand notation. The agent resolves the URL, fetches the SKILL.md file, and installs it in the appropriate skills directory. ### CLI-Based Discovery The `npx skills find [query]` command enables keyword-based search across registered skills. This is particularly useful for discovering skills that address specific use cases or domains. ### Manual Installation For offline environments or custom workflows, users can manually download skill folders and place them in the appropriate directory: ```bash # Example: Manual skill installation cp -r /path/to/downloaded-skill \ ~/.agents/skills/my-skill-name ``` 资料来源：[README.ko.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.ko.md) ## Verification and Validation The Agent Skills ecosystem includes validation mechanisms to ensure skill quality and compatibility: | Validation Type | Purpose | |-----------------|---------| | Directory structure check | Verify SKILL.md exists in expected location | | Frontmatter validation | Ensure required fields are present and valid | | Update checking | `npx skills check` verifies skill versions | Users can verify that a skill is correctly installed by checking for the presence of its SKILL.md file: ```bash ls ~/.agents/skills/my-skill/SKILL.md ``` 资料来源：[README.ko.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.ko.md) ## Related Resources For more information about compatible agents and the Agent Skills ecosystem, refer to: - [Official Specification](https://agentskills.io/specification) — Complete SKILL.md format specification - [Creating Skills Guide](https://support.claude.com/en/articles/12512198-creating-custom-skills) — Tutorial for skill authors - [Using Skills in Claude](https://support.claude.com/en/articles/12512180-using-skills-in-claude) — Claude.ai user guide --- ## Next.js Website Structure ### 相关页面 相关主题：[Component Architecture](#component-architecture), [Deployment Configuration](#deployment-config)
Related Source Files The following source files were used to generate this documentation: - [website/src/lib/i18n.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/lib/i18n.tsx) - [website/src/components/sections/HowItWorks.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/HowItWorks.tsx) - [website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx) - [website/src/components/sections/CompatibleAgents.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/CompatibleAgents.tsx) - [website/src/components/Footer.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Footer.tsx) - [website/src/components/WikiSidebar.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/WikiSidebar.tsx)
# Next.js Website Structure ## Overview The `awesome-agent-skills` repository includes a Next.js-based website (`/website`) that serves as the public-facing documentation and showcase for agent skills. This web application is built using Next.js 14+ with the App Router paradigm, TypeScript for type safety, and Tailwind CSS for styling. The site provides an interactive interface for exploring agent skills, understanding how they work, and navigating through comprehensive documentation. The website architecture follows a component-based modular design where reusable UI sections are organized in `/src/components/sections/`, while shared utilities like internationalization (i18n) live in `/src/lib/`. The application uses the Next.js App Router for routing and leverages server-side rendering capabilities for optimal performance and SEO. 资料来源：[website/src/lib/i18n.tsx]() ## Project Architecture ### Directory Structure The website follows a standard Next.js App Router structure: ``` website/ ├── src/ │ ├── app/ # App Router pages and layouts │ ├── components/ # Reusable React components │ │ ├── sections/ # Page section components │ │ ├── Footer.tsx # Global footer component │ │ └── WikiSidebar.tsx # Navigation sidebar │ └── lib/ # Utility functions │ └── i18n.tsx # Internationalization setup ├── public/ # Static assets ├── next.config.ts # Next.js configuration └── tsconfig.json # TypeScript configuration ``` ### Technology Stack | Technology | Purpose | Version | |------------|---------|---------| | Next.js | React framework with App Router | 14+ | | TypeScript | Type-safe JavaScript | Latest | | Tailwind CSS | Utility-first CSS framework | Latest | | framer-motion | Animation library for React | Latest | The project utilizes CSS variables for theming, supporting both light and dark modes through Tailwind's dark mode variants. The application uses `next/font` for automatic font optimization, loading Geist font family for consistent typography across the site. 资料来源：[website/README.md]() ## Component Architecture ### Section Components The website is composed of modular section components located in `/src/components/sections/`. Each section represents a distinct portion of the page content: | Component | Purpose | Key Features | |-----------|---------|---------------| | `HowItWorks.tsx` | Explains the three-step process | Grid layout with step cards | | `QualityStandards.tsx` | Defines skill quality criteria | Good vs bad pattern comparison | | `CompatibleAgents.tsx` | Lists supported agent platforms | Responsive table layout | | `FindingSkills.tsx` | Guides on discovering skills | CLI commands display | | `UsingSkills.tsx` | Demonstrates skill usage | Copy-enabled code panels | | `SkillDirectory.tsx` | Interactive skills catalog | Animated filtering grid | | `CreatingSkills.tsx` | SKILL.md creation guide | Blueprint documentation | | `Tutorials.tsx` | Learning resources | Card-based layout | | `Contributing.tsx` | Contribution guidelines | CTA buttons and links | #### Section Component Pattern Each section component follows a consistent pattern using the `"use client"` directive for client-side interactivity: ```typescript "use client"; import { useTranslations } from "@/lib/i18n"; export default function SectionName() { const t = useTranslations(); return (

{t.section.title}

{/* Section content */}
); } ``` 资料来源：[website/src/components/sections/HowItWorks.tsx]() ### Navigation Components #### WikiSidebar.tsx The `WikiSidebar` component provides hierarchical navigation within the documentation. It renders a collapsible sidebar with grouped navigation items and supports visual indicators for new content. Key features include: - Hierarchical category grouping - "New" badge support for recent additions - External link indicators - Dark mode compatible styling - Animated transitions using framer-motion The sidebar fetches navigation data from the i18n configuration and renders links with appropriate styling based on their type (internal or external). 资料来源：[website/src/components/WikiSidebar.tsx]() #### Footer.tsx The global footer component provides site-wide information and external links: - Site branding and copyright information - Social media links (GitHub, X/Twitter) - Contact email link - BibTeX citation format for academic references - Call-to-action buttons for main resources ```typescript export default function Footer() { return (
{/* BibTeX citation block */} {/* Social links: GitHub, Twitter, Email */} {/* External resource buttons */}
); } ``` 资料来源：[website/src/components/Footer.tsx]() ## Internationalization (i18n) ### i18n Implementation The website implements internationalization using a custom i18n solution defined in `/src/lib/i18n.tsx`. The system provides translations for multiple languages including English, Japanese, and presumably Chinese based on the repository's focus. #### Translation Structure Translations are organized hierarchically: ```typescript export const translations = { nav: { title: "Navigation", items: ["Skills", "Directory", "Standards", "Guide", "Trends", "FAQ"] }, resources: { title: "Resources", items: [ { label: "agent-skill.co", href: "https://agent-skill.co" }, { label: "GitHub Repository", href: "..." } ] }, how: { title: "How it works", subtitle: "...", steps: [ { step: "01", title: "...", desc: "..." } ] } // Additional translation keys... }; ``` #### Translation Hook Components access translations through the `useTranslations()` hook: ```typescript const t = useTranslations(); // Access nested properties t.nav.title // Returns "Navigation" t.how.steps // Returns array of step objects ``` 资料来源：[website/src/lib/i18n.tsx]() ### Supported Languages Based on the i18n file content, the website supports: | Language | Key Indicators | |----------|----------------| | English | Default language | | Japanese | `ナビゲーション`, `引用` labels | | Chinese (implied) | Repository focus on Chinese-speaking developers | ## Styling and Theming ### Tailwind CSS Integration The website uses Tailwind CSS with the following configuration: - Dark mode support via `dark:` class variants - Custom color palette using neutral grays - Responsive design breakpoints (md, lg) - Custom scroll margin for anchor navigation (`scroll-mt-20`) ### Color System The styling uses a neutral color system defined through Tailwind classes: | Element | Light Mode | Dark Mode | |---------|------------|-----------| | Background | `white` | `neutral-900` | | Text Primary | `neutral-900` | `white` | | Text Secondary | `neutral-500` | `neutral-400` | | Borders | `neutral-200` | `neutral-800` | ### Component Styling Patterns #### Card Components Section cards use consistent styling patterns: ```typescript

{title}

{description}

``` #### Table Components Data tables follow a consistent structure: ```typescript {/* Rows */}
Column
``` 资料来源：[website/src/components/sections/QualityStandards.tsx](), [website/src/components/sections/CompatibleAgents.tsx]() ## Page Sections and Content Flow ### Main Page Structure The primary page (`/app/page.tsx`) renders sections in a specific order: ```mermaid graph TD A[Hero Section] --> B[How It Works] B --> C[Quality Standards] C --> D[Compatible Agents] D --> E[Finding Skills] E --> F[Using Skills] F --> G[Creating Skills] G --> H[Skill Directory] H --> I[Tutorials] I --> J[Contributing] J --> K[FAQ] K --> L[Footer] ``` ### Section Details #### How It Works Section Explains the three-step process for agent skills: 1. **Find** - Discover skills in the directory 2. **Add** - Add skills to your AI tool 3. **Use** - Agent automatically applies the skill Each step is displayed in a card with a large step number, title, and description. 资料来源：[website/src/components/sections/HowItWorks.tsx]() #### Quality Standards Section Defines what makes a good agent skill: - **Good vs Bad Pattern Comparison**: Side-by-side code examples - **Pattern Validation**: Shows recommended vs discouraged practices - **Icon Indicators**: CheckCircle2 for good, XCircle for bad ```typescript // Good pattern

{t.quality.goodPattern}

// Bad pattern

{t.quality.badPattern}

``` 资料来源：[website/src/components/sections/QualityStandards.tsx]() #### Skill Directory Section The interactive skills catalog features: - **Framer Motion Integration**: Animated grid with layout animations - **Filtering**: Client-side filtering by skill category - **Card Design**: Each skill displays name, icon, and external link - **Responsive Grid**: `grid-cols-1 md:grid-cols-2` for mobile to desktop ```typescript {filtered.map((skill) => ( {/* Skill card content */} ))} ``` 资料来源：[website/src/components/sections/SkillDirectory.tsx]() ## Interactive Features ### Code Copy Functionality The `UsingSkills.tsx` component includes copy-to-clipboard functionality: ```typescript const [copied, setCopied] = useState(false); const copyCode = async () => { await navigator.clipboard.writeText(code); setCopied(true); setTimeout(() => setCopied(false), 2000); }; return ( ); ``` 资料来源：[website/src/components/sections/UsingSkills.tsx]() ### Active Navigation Highlighting The website implements scroll-based active navigation using the Intersection Observer API: ```typescript const navLinks = document.querySelectorAll('.nav-link'); const sections = ['newcomer', 'tutorial', 'reference', 'dir-section', 'agents', 'resources']; const observer = new IntersectionObserver(entries => { for (const e of entries) { if (e.isIntersecting) { const id = e.target.id; navLinks.forEach(l => { l.classList.toggle('active', l.getAttribute('href') === `#${id}`); }); } } }, { threshold: 0.2, rootMargin: '-52px 0px 0px 0px' }); ``` This provides visual feedback as users scroll through different page sections. 资料来源：[website/index.html]() ## Build and Deployment ### Development Workflow ```bash npm run dev # Start development server yarn dev # Alternative with Yarn pnpm dev # Alternative with pnpm bun dev # Alternative with Bun ``` ### Font Optimization The project uses `next/font` for automatic font optimization: ```typescript // In layout.tsx import { Geist } from "next/font/google"; // Font configuration is handled automatically ``` This loads the Geist font family and optimizes it for performance, reducing layout shift during page loads. ### Production Build The Next.js application can be deployed to Vercel or any Node.js-compatible hosting platform. The standard build process: ```bash npm run build # Create production build npm start # Start production server ``` 资料来源：[website/README.md]() ## Summary The Next.js website structure for `awesome-agent-skills` demonstrates a well-organized, component-based architecture suitable for documentation and showcase sites. Key architectural decisions include: - **Modular Sections**: Each page section is a self-contained component - **i18n System**: Custom translation hook with hierarchical structure - **Theming**: Dark mode support through Tailwind CSS - **Animations**: Framer Motion for smooth transitions - **Accessibility**: Semantic HTML with proper ARIA attributes - **Performance**: Next.js App Router with automatic font optimization The architecture prioritizes maintainability and extensibility, making it straightforward to add new sections or modify existing ones. The separation of concerns between presentation components and utility functions (i18n) ensures clean code organization as the project scales. --- ## Component Architecture ### 相关页面 相关主题：[Next.js Website Structure](#nextjs-structure), [Internationalization (i18n)](#internationalization)
相关源码文件 以下源码文件用于生成本页说明： - [website/src/components/WikiSidebar.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/WikiSidebar.tsx) - [website/src/components/Navbar.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Navbar.tsx) - [website/src/components/Footer.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Footer.tsx) - [website/src/components/sections/SkillDirectory.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/SkillDirectory.tsx) - [website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx) - [website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx) - [website/src/components/sections/CreatingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/CreatingSkills.tsx) - [website/src/components/sections/WhatIsIt.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/WhatIsIt.tsx) - [website/src/components/sections/Contributing.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/Contributing.tsx) - [website/src/components/sections/FindingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/FindingSkills.tsx) - [website/src/components/sections/Tutorials.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/Tutorials.tsx)
# Component Architecture ## Overview The awesome-agent-skills website is a Next.js-based documentation and showcase platform built with React and TypeScript. The component architecture follows a modular, section-driven design pattern where reusable UI components are composed into distinct page sections. The project uses Tailwind CSS for styling with dark mode support and framer-motion for animations. 资料来源：[website/src/components/sections/SkillDirectory.tsx:1-50]() ## Directory Structure ``` website/src/components/ ├── LayoutShell.tsx # Main layout wrapper ├── Navbar.tsx # Top navigation bar ├── Footer.tsx # Page footer ├── WikiSidebar.tsx # Documentation sidebar navigation └── sections/ ├── Hero.tsx # Hero banner section ├── WhatIsIt.tsx # Project introduction ├── SkillDirectory.tsx # Skills catalog grid ├── UsingSkills.tsx # Usage instructions ├── CreatingSkills.tsx # Skill creation guide ├── FindingSkills.tsx # Skill discovery resources ├── QualityStandards.tsx # Good vs bad patterns ├── Tutorials.tsx # Interactive tutorials └── Contributing.tsx # Contribution guide ``` ## Component Hierarchy ```mermaid graph TD A[LayoutShell] --> B[Navbar] A --> C[WikiSidebar] A --> D[Section Components] A --> E[Footer] D --> D1[WhatIsIt] D --> D2[SkillDirectory] D --> D3[UsingSkills] D --> D4[CreatingSkills] D --> D5[FindingSkills] D --> D6[QualityStandards] D --> D7[Tutorials] D --> D8[Contributing] B --> B1[LanguageSelector] B --> B2[ThemeToggle] B --> B3[GitHubStars] ``` ## Core Layout Components ### LayoutShell The `LayoutShell` component serves as the main application wrapper that orchestrates all other components. It integrates the `Navbar`, `WikiSidebar`, page sections, and `Footer` into a cohesive layout structure. ### Navbar The `Navbar` component provides top-level navigation and global controls. Key features include: | Feature | Implementation | |---------|----------------| | GitHub Stars Display | Parses and formats star count (e.g., "1.2k") | | Language Selector | Dropdown with flag icons using `LANGUAGES` array | | Theme Toggle | Dark/light mode switching | 资料来源：[website/src/components/Navbar.tsx:1-40]() The language selector uses framer-motion for smooth dropdown animations with the following states: ```typescript {langOpen && ( {LANGUAGES.map((l) => (...))} )} ``` ### WikiSidebar The `WikiSidebar` component provides documentation navigation with hierarchical menu items. It supports: - Collapsible menu sections with `AnimatePresence` - "New" badge indicators using the `Sparkles` icon for newly added items - External links to agent-skill.co and GitHub repository - Smooth fade animations for menu state changes 资料来源：[website/src/components/WikiSidebar.tsx:1-60]() ### Footer The `Footer` component displays project metadata and social links: ```typescript agent-skill.co ``` Includes BibTeX citation format for academic references. 资料来源：[website/src/components/Footer.tsx:1-30]() ## Section Components ### WhatIsIt Introduces the project concept using icon-based cards. Each card displays a title, description, and corresponding icon in a responsive grid layout. ### SkillDirectory The `SkillDirectory` component renders a filterable grid of skills with the following structure: | Element | Purpose | |---------|---------| | Search/Filter Bar | Filter skills by name or category | | Motion Grid | Animated grid using `framer-motion` layout | | Skill Cards | Each card shows icon, name, and description | ```typescript

{skill.name}

{skill.description}

 ``` 资料来源：[website/src/components/sections/SkillDirectory.tsx:1-50]() ### UsingSkills Demonstrates how to add skills to an agent with code examples: | Panel Type | Description | |------------|-------------| | CLI | Shows `npx skills add` command | | Manual Drop-in | Shows `.github/skills/skill-name/` path | Includes a copy-to-clipboard button that uses `Check` and `Copy` icons from Lucide React. 资料来源：[website/src/components/sections/UsingSkills.tsx:1-40]() ### CreatingSkills Displays the `SKILL.md` blueprint structure for creating new skills. Shows section-by-section breakdown with descriptions in a card format. ```typescript {t.creating.blueprint.map((section, i) => (
{section.section}

{section.desc}

))} ``` 资料来源：[website/src/components/sections/CreatingSkills.tsx:1-30]() ### QualityStandards Shows good vs bad code patterns side-by-side with visual indicators: | Pattern Type | Visual Treatment | |--------------|------------------| | Good | Green `CheckCircle2` icon, full opacity | | Bad | Gray `XCircle` icon, 70% opacity | Uses dark mode compatible styling with Tailwind's `dark:` modifier. 资料来源：[website/src/components/sections/QualityStandards.tsx:1-50]() ### FindingSkills Lists external resources for discovering agent skills including marketplaces and CLI commands: ```typescript {cliCommands.map(({ cmd, desc }) => (
{cmd} {desc}
))} ``` Supports conditional image rendering for marketplace and leaderboard sections. 资料来源：[website/src/components/sections/FindingSkills.tsx:1-40]() ### Tutorials Implements chat-style tutorial dialogues with: - Character avatars (emoji-based) - Quest/step indicators with icons - External links to documentation resources Uses `ArrowUpRight` icon for external link indicators. 资料来源：[website/src/components/sections/Tutorials.tsx:1-50]() ### Contributing Simple section with call-to-action buttons linking to: - Contributing Guide (`/CONTRIBUTING.md`) - GitHub Repository 资料来源：[website/src/components/sections/Contributing.tsx:1-30]() ## Data Flow Architecture ```mermaid graph LR A[i18n Translations] --> B[Section Components] C[Props/State] --> D[UI Rendering] B --> D E[External APIs] --> F[SkillDirectory Data] F --> D ``` ## Animation Strategy The project uses framer-motion consistently across components: | Animation | Usage | |-----------|-------| | `motion.div` | Fade and scale transitions | | `AnimatePresence` | Conditional rendering with exit animations | | `layout` prop | Automatic grid reordering | Example from SkillDirectory: ```typescript ``` ## Dark Mode Support All components implement dark mode using Tailwind's `dark:` modifier: | Element | Light Mode | Dark Mode | |---------|------------|-----------| | Background | `bg-white` | `dark:bg-neutral-900` | | Border | `border-neutral-200` | `dark:border-neutral-800` | | Text | `text-neutral-700` | `dark:text-neutral-300` | ## Dependencies Key external dependencies for the component architecture: | Package | Purpose | |---------|---------| | `framer-motion` | Animation and layout transitions | | `lucide-react` | Icon library | | `next` | React framework | ## State Management Pattern Components receive data via props and manage local state using React hooks. No global state management library is used; instead, props drilling and localized state is preferred for simplicity. --- ## Skill Directories ### 相关页面 相关主题：[Compatible Agents](#compatible-agents), [Skill Quality Standards](#skill-quality-standards)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.md) - [website/src/components/sections/SkillDirectory.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/SkillDirectory.tsx)
# Skill Directories ## Overview A **Skill Directory** is the organizational structure that stores, categorizes, and makes AI agent skills discoverable. This repository serves as a curated collection of reusable skills compatible with 30+ agent platforms including Claude Code, Claude.ai, OpenAI Codex, GitHub Copilot, Cursor, and more. The directory enables: - **Discovery**: Browse and search skills by category - **Installation**: Copy skills directly into your agent's skill folder - **Portability**: Skills work across different agents without modification - **Version Control**: Track changes and contributions via Git 资料来源：[website/index.html:1-50]() ## Directory Structure Skills in this repository follow a standardized folder structure. Each skill is contained within its own directory containing a mandatory `SKILL.md` file. ``` awesome-agent-skills/ ├── .claude/skills/ # Skills compatible with Claude Code ├── .github/skills/ # Skills compatible with GitHub-based agents └── website/ └── src/components/ └── sections/ └── SkillDirectory.tsx # Frontend component for browsing ``` ### Skill Package Structure ``` my-skill/ ├── SKILL.md # Required: skill metadata and instructions ├── LICENSE # Optional: license file └── scripts/ # Optional: executable helper scripts └── *.py └── *.sh ``` 资料来源：[website/index.html:85-120]() ## SKILL.md Format Specification Every skill must contain a `SKILL.md` file with YAML frontmatter. Only `name` and `description` are required. ### Required Fields | Field | Type | Constraints | Description | |-------|------|-------------|-------------| | `name` | string | 1-64 chars, lowercase alphanumeric + hyphens | Must match parent directory name. No consecutive hyphens or leading/trailing hyphens. | | `description` | string | 1-1024 chars | Most important field. Describes what the skill does AND when to activate it. Include specific keywords agents would encounter. | ### Optional Fields | Field | Type | Description | |-------|------|-------------| | `license` | string | License name (e.g., "MIT", "Apache-2.0") or reference to bundled LICENSE file | | `compatibility` | string | 1-500 chars describing environment requirements (e.g., "Requires Python 3.11+ and uv") | | `metadata` | object | Author, version, and other metadata | | `allowed-tools` | string | Space-delimited list of pre-approved tools (experimental, support varies) | 资料来源：[website/index.html:180-220]() ### Example SKILL.md ```yaml --- name: pdf-processing description: > Extract text and tables from PDF files, fill PDF forms, and merge multiple PDFs. Use when working with PDF documents, forms, or when the user mentions PDFs, document extraction, or form filling. license: Apache-2.0 compatibility: Requires Python 3.11+ and uv metadata: author: example-org version: "1.0" allowed-tools: Bash(uv:*) Read Write --- ## When to use this skill Activate when the user needs to extract text, fill forms, or merge PDFs. ## Instructions 1. Verify the input is a valid PDF. 2. Run the appropriate script from scripts/. 3. Validate output before returning. ## Gotchas - Scanned PDFs require OCR (scripts/ocr.py, not scripts/extract.py) - Password-protected PDFs need decryption first ``` 资料来源：[website/index.html:220-260]() ## Progressive Disclosure Architecture Skills implement a two-phase loading strategy to optimize performance: ```mermaid graph TD A[Agent Startup] --> B[Lightweight Scan] B --> C[Load name + description
~50-100 tokens per skill] C --> D[Agent Receives User Task] D --> E{Match skill description?} E -->|Yes| F[Load Full SKILL.md] E -->|No| G[Execute without skill] F --> H[Execute with skill context] G --> H style B fill:#e1f5fe style F fill:#fff3e0 ``` ### Discovery Phase At startup, the agent scans configured skill directories and loads only the `name` and `description` fields (~50-100 tokens per skill). Full instructions are not loaded yet. Supported directory locations: | Platform | Default Location | |----------|-----------------| | Claude Code | `~/.claude/skills/` | | Claude.ai | Imported via URL paste | | Generic | `~/.agents/skills/` | | Project-level | `.agents/skills/` | 资料来源：[website/index.html:280-310]() ### Activation Phase When a user's task matches a skill's description, the agent reads the full `SKILL.md` into context. This is when instructions, examples, and scripts are loaded and executed. ## Installation Methods ### Method 1: Direct Folder Placement Copy the skill folder into the agent's skills directory: ```bash # For Claude Code cp -r my-downloaded-skill ~/.claude/skills/my-skill # Verify structure ls ~/.claude/skills/my-skill/SKILL.md ``` ### Method 2: CLI Tool Use the `npx skills` command-line tool for quick installation: ```bash npx skills add # Add via GitHub shorthand npx skills add https://github.com/owner/repo # Full URL npx skills add /path/to/local-skill # Local path npx skills list # List installed skills npx skills check # Check for updates npx skills update # Update all skills npx skills remove [skill-name] # Remove a skill ``` 资料来源：[README.ko.md:45-60]() ### Method 3: IDE Drop-In Modern IDEs like Cursor and Claude Code automatically detect new folders in `.github/skills/`: ```bash # Drop folder directly into skills directory cp -r my-downloaded-skill .github/skills/my-skill ``` The IDE detects new knowledge instantly without requiring a restart. 资料来源：[website/src/components/sections/UsingSkills.tsx:1-30]() ## Skill Loading Workflow ```mermaid sequenceDiagram participant User participant Agent participant SkillFS as Skill Directory participant SkillMD as SKILL.md User->>Agent: Request task Agent->>SkillFS: Scan skills at startup SkillFS-->>Agent: Return metadata (name, description) User->>Agent: Specific task Agent->>SkillMD: Load matching skill SkillMD-->>Agent: Full instructions + scripts Agent->>Agent: Execute with skill context Agent-->>User: Task result ``` ## Quality Standards High-quality skills follow these guidelines: | Aspect | Recommendation | |--------|----------------| | **Scope** | Under 500 lines, under 5,000 tokens. Split larger skills into referenced files. | | **Instructions** | Focus on project conventions, domain-specific procedures, edge cases. Omit general knowledge the agent already has. | | **Activation** | Write descriptive `description` field with specific keywords agents would encounter. | | **Examples** | Include concrete input → output pairs in the Examples section. | | **Validation** | Document how to verify the output is correct. | | **Gotchas** | Add a Gotchas section for environment-specific facts that defy expectations. | 资料来源：[website/src/components/sections/QualityStandards.tsx:1-50]() ### Recommended Body Structure ```markdown ## When to use this skill Trigger conditions, scope, and limitations. ## Instructions Step-by-step procedure. Be explicit. ## Gotchas Environment-specific facts. Things that defy expectations. ## Examples Concrete input → output pairs. ## Validation How to verify the output is correct. ``` 资料来源：[website/index.html:150-175]() ## Compatible Agents The skill format is an open standard adopted by 30+ platforms: | Agent | Documentation | |-------|---------------| | Claude Code | code.claude.com/docs/en/skills | | Claude.ai | support.claude.com | | OpenAI Codex | developers.openai.com/codex | | GitHub Copilot | docs.github.com/copilot | | Cursor | cursor.com | | Gemini CLI | (official docs) | 资料来源：[website/index.html:320-340]() ## Skill Directory Component The `SkillDirectory.tsx` component renders the interactive skill browser on the website: ```typescript // website/src/components/sections/SkillDirectory.tsx // Renders skill cards with search, filtering, and category organization ``` Key features include: - **Search**: Filter skills by name or keyword - **Categories**: Skills organized by domain (development, data, automation, security, etc.) - **Direct Links**: Each card links directly to the skill's GitHub repository ## Creating Your Own Skill 1. **Create folder**: Name it with lowercase alphanumeric + hyphens only 2. **Add SKILL.md**: Include required `name` and `description` frontmatter 3. **Write instructions**: Structure with When to use, Instructions, Gotchas sections 4. **Add scripts (optional)**: Place executables in `scripts/` subdirectory 5. **Test**: Load into your agent and verify behavior ```bash mkdir my-first-skill cd my-first-skill cat > SKILL.md << 'EOF' --- name: my-first-skill description: Use when you need to [specific task]. Activates for [keywords]. --- ## When to use this skill ## Instructions 1. First, do this. 2. Then, do that. ## Gotchas - Important note about edge case EOF ``` 资料来源：[website/index.html:30-50]() ## Summary Skill Directories provide a portable, version-controlled mechanism for packaging AI agent capabilities. By standardizing on the `SKILL.md` format with YAML frontmatter and Markdown instructions, skills remain agent-agnostic while enabling: - Zero-infrastructure deployment - Cross-platform compatibility - Progressive disclosure for performance - Community sharing via Git --- ## Skill Quality Standards ### 相关页面 相关主题：[Skill Directories](#skill-directories), [Using and Creating Skills](#using-creating-skills)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.md) - [website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx)
# Skill Quality Standards ## Overview Skill Quality Standards define the criteria and best practices for creating effective, reliable, and maintainable Agent Skills within the awesome-agent-skills ecosystem. These standards ensure that skills are consistently structured, easily discoverable, and capable of delivering predictable behavior across different AI agents and platforms. The quality framework establishes what constitutes a "good" skill versus a poorly constructed one, providing authors with clear guidelines for implementation. This system helps maintain ecosystem integrity while enabling contributors to build skills that genuinely enhance AI agent capabilities. ## Purpose and Scope The Skill Quality Standards system serves multiple stakeholders within the AI agent ecosystem: - **For Skill Authors**: Provides concrete guidelines on how to structure skills for maximum effectiveness - **For AI Agents**: Ensures consistent instruction formatting that agents can reliably parse and execute - **For End Users**: Guarantees predictable, high-quality outcomes when deploying skills - **For Ecosystem Maintainers**: Offers evaluation criteria for curating and reviewing community submissions The scope encompasses all aspects of skill creation including file structure, instruction clarity, example quality, and validation mechanisms. Skills that meet these standards are more likely to function correctly across the 30+ supported agent platforms including Claude Code, Claude.ai, OpenAI Codex, GitHub Copilot, and Cursor. ## Quality Evaluation Framework ### Core Quality Dimensions Skills are evaluated across five primary dimensions that collectively determine their overall quality and reliability. | Dimension | Description | Weight | |-----------|-------------|--------| | **Instruction Clarity** | How clearly and unambiguously the instructions are written | High | | **Trigger Precision** | Accuracy of the description field in matching relevant use cases | High | | **Example Quality** | Relevance and completeness of provided examples | Medium | | **Edge Case Handling** | Coverage of gotchas, limitations, and error scenarios | Medium | | **Validation Logic** | Presence and effectiveness of output verification steps | Medium | ### Quality Assessment Process The quality assessment follows a structured evaluation workflow that ensures consistent scoring across all submitted skills. ```mermaid graph TD A[Skill Submission] --> B[Metadata Review] B --> C[Instruction Analysis] C --> D[Example Validation] D --> E[Edge Case Audit] E --> F[Final Quality Score] B --> B1{name matches dir?} B1 -->|No| G[Rejection: Name Mismatch] B1 -->|Yes| C C --> C1{Instructions clear?} C1 -->|Unclear| H[Return for Revision] C1 -->|Clear| D D --> D1{Examples valid?} D1 -->|Invalid| H D1 -->|Valid| E E --> E1{Gotchas documented?} E1 -->|Missing| I[Recommendation Added] E1 -->|Documented| F style G fill:#ff6b6b style H fill:#ffd93d style F fill:#6bcb77 ``` ## Good vs. Bad Pattern Examples The quality standards explicitly define what constitutes effective versus ineffective skill implementations through concrete pattern comparisons. ### Pattern Comparison Table | Aspect | Good Pattern | Bad Pattern | |--------|--------------|-------------| | **Specificity** | Actionable steps with clear scope | Vague descriptions lacking direction | | **Trigger Conditions** | Precise "Use when..." statements | Generic statements applicable to many contexts | | **Validation** | Output verification steps included | No mechanism to verify correctness | | **Examples** | Concrete input → output pairs | Missing or abstract examples | | **Limitations** | Known constraints documented | Implicit assumptions unstated | ### Implementation Example The quality standards component provides visual comparison panels that demonstrate these differences: ```typescript // QualityStandards.tsx structure interface QualityStandard { title: string; description: string; } interface PatternComparison { goodHeader: string; badHeader: string; goodPattern: string; badPattern: string; goodDesc: string; badDesc: string; } ``` The component renders two side-by-side panels: - **Left Panel (Good)**: Green-accented header with CheckCircle2 icon, displays the recommended pattern in monospace font, includes explanatory text below - **Right Panel (Bad)**: Muted header with XCircle icon, displays the anti-pattern with reduced opacity, includes descriptive critique ## Skill Structure Requirements Beyond instruction quality, the standards define structural requirements that skills must satisfy. ### Directory Structure ``` skill-name/ ├── SKILL.md # Required: Main skill definition ├── scripts/ # Optional: Executable helper scripts │ └── *.py, *.sh ├── LICENSE # Optional: License specification └── README.md # Optional: Extended documentation ``` ### Frontmatter Requirements | Field | Type | Required | Constraints | |-------|------|----------|-------------| | `name` | string | Yes | 1-64 chars, lowercase alphanumeric + hyphens, must match parent directory | | `description` | string | Yes | 1-1024 chars, describes both capability AND trigger conditions | | `license` | string | No | License name or reference to bundled file | | `compatibility` | string | No | 1-500 chars, environment requirements | | `metadata` | object | No | Author, version, or custom fields | | `allowed-tools` | string | No | Space-delimited list of approved tools (experimental) | ## Progressive Disclosure Model The quality standards embrace a progressive disclosure architecture that optimizes for both initial discovery performance and comprehensive execution capability. ```mermaid graph LR subgraph Discovery["Startup Phase - Lightweight Scan"] A1[Agent loads] --> A2[Read name] A2 --> A3[Read description] A3 --> A4[~50-100 tokens per skill] end subgraph Activation["On-Demand Loading"] B1[Task matches description?] -->|Yes| B2[Load full SKILL.md] B2 --> B3[Read instructions] B3 --> B4[Load examples] B4 --> B5[Load scripts if needed] end A4 -.->|Task relevance?| B1 style Discovery fill:#e3f2fd style Activation fill:#fff3e0 ``` This model ensures that agents remain responsive during startup while having access to complete instructions when a relevant task is detected. ## Best Practices Summary Based on the quality standards framework, skill authors should adhere to the following practices: 1. **Write Descriptive Trigger Conditions**: The `description` field should explicitly state when to activate the skill, including specific keywords users would employ 2. **Structure Instructions Step-by-Step**: Break procedures into numbered, sequential steps that agents can follow unambiguously 3. **Document Edge Cases**: Include a `Gotchas` section covering environment-specific behaviors, common failure modes, and known limitations 4. **Provide Concrete Examples**: Include input → output pairs that demonstrate expected behavior in realistic scenarios 5. **Include Validation Steps**: Define how to verify that the skill's output meets success criteria 6. **Use Agent-Friendly Scripts**: When including scripts, design them to avoid interactive prompts, produce structured output (JSON/CSV), and exit with meaningful codes ## Integration with Skill Ecosystem The quality standards integrate with the broader skill ecosystem through the following mechanisms: | Integration Point | Description | |-------------------|-------------| | **Discovery** | Skills meeting standards appear in the curated directory with quality indicators | | **Compatibility** | Standards ensure cross-platform compatibility across 30+ supported agents | | **CLI Integration** | `npx skills` tool validates skills against quality criteria during add/check operations | | **Community Curation** | Maintainers use standards to review and recommend improvements for submitted skills | The `npx skills` command provides validation through `npx skills check`, which verifies that skills conform to the defined standards and alerts authors to areas needing improvement. ## References - Quality Standards Component: `website/src/components/sections/QualityStandards.tsx` - README Documentation: `README.md` - Skill Specification: [agentskills.io/specification](https://agentskills.io/specification) --- ## Using and Creating Skills ### 相关页面 相关主题：[Quick Start Guide](#quick-start-guide), [Skill Quality Standards](#skill-quality-standards)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.md) - [website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html) - [website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx) - [CONTRIBUTING.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/CONTRIBUTING.md)
# Using and Creating Skills Agent Skills are portable instruction packages that teach AI assistants how to perform specific tasks. A skill consists of a `SKILL.md` file containing YAML frontmatter and markdown instructions, optionally bundled with executable scripts. Skills follow an open standard originally developed by Anthropic, now adopted by 30+ agent platforms including Claude, Codex, Cursor, Copilot, and Gemini CLI. ## Overview The SKILL.md format enables AI agents to load domain knowledge, team conventions, and repeatable workflows on demand. At startup, agents perform a lightweight scan of available skills, loading only the `name` and `description` fields (~50-100 tokens per skill). Full instructions are loaded only when a task matches a skill's description. ## Skill Discovery Locations Agents scan the following directories for available skills: | Location | Description | |----------|-------------| | `~/.claude/skills/` | User-level skills | | `.claude/skills/` | Project-level skills | | `.github/skills/` | Repository-level skills | | `~/.agents/skills/` | Alternative user-level location | ## SKILL.md Format Specification ### Required Frontmatter Fields ```yaml --- name: pdf-processing description: > Extract text and tables from PDF files, fill PDF forms, and merge multiple PDFs. Use when working with PDF documents, forms, or when the user mentions PDFs, document extraction, or form filling. --- ``` | Field | Required | Format | Constraints | |-------|----------|--------|-------------| | `name` | Yes | Lowercase alphanumeric + hyphens | 1-64 characters, must match parent directory, no consecutive/leading/trailing hyphens | | `description` | Yes | Free-form text | 1-1024 characters, describes what and when to use | ### Optional Frontmatter Fields | Field | Required | Description | |-------|----------|-------------| | `license` | No | License name or reference to bundled file (e.g., `MIT`, `Apache-2.0`, `LICENSE.txt`) | | `compatibility` | No | Environment requirements (e.g., `Requires Python 3.11+ and uv`) | | `metadata` | No | Structured metadata object with author, version, etc. | | `allowed-tools` | No (Experimental) | Space-delimited list of pre-approved tools to run | ### Recommended Body Structure The markdown body following frontmatter has no format restrictions. Recommended sections: ```markdown ## When to use this skill Trigger conditions, scope, and limitations. ## Instructions Step-by-step procedure. Be explicit. ## Gotchas Environment-specific facts. Things that defy expectations. ## Examples Concrete input → output pairs. ## Validation How to verify the output is correct. ``` ## Adding Skills to Your Agent ### Using the CLI Tool The `npx skills` CLI provides commands for managing skills: ```bash npx skills find [query] # Search for relevant skills npx skills add # Add a skill (supports GitHub shorthand, full URLs, or local paths) npx skills list # List installed skills npx skills check # Check for updates npx skills update # Upgrade all skills npx skills remove [skill-name] # Remove a skill ``` ### Manual Drop-In Skills can be manually placed in the appropriate directory: ```bash # Copy skill folder to agent skills directory cp -r my-downloaded-skill ~/.agents/skills/my-skill # Verify structure ls ~/.agents/skills/my-skill/SKILL.md ``` ### Platform-Specific Loading | Platform | Command | |----------|---------| | Claude Code | `/skills add ` | | Claude.ai | Paste raw SKILL.md URL in chat | ## Creating a New Skill ### Step 1: Create the Directory Create a folder named after your skill. The folder name must match the `name` field in frontmatter. ```bash mkdir my-custom-skill ``` ### Step 2: Create SKILL.md Place a `SKILL.md` file inside the folder: ```bash touch my-custom-skill/SKILL.md ``` ### Step 3: Write Frontmatter Add required YAML frontmatter at the top: ```yaml --- name: my-custom-skill description: > A brief description of what this skill does and when to use it. Include keywords the agent might encounter. --- ``` ### Step 4: Write Instructions Add clear, step-by-step instructions in the markdown body: ```markdown ## When to use this skill Activate when the user needs to [specific task]. ## Instructions 1. First, do this. 2. Then, do that. 3. Finally, validate the output. ## Gotchas - Scanned PDFs require OCR - Password-protected files need additional handling ``` ### Step 5: Add Scripts (Optional) Place executable files in a `scripts/` subdirectory. Scripts should be agent-friendly: ```python #!/usr/bin/env -S uv run # /// script # requires-python = ">= 3.11" # dependencies = ["requests", "rich"] # /// import sys, json # Design principles: # - Avoid interactive prompts # - Use structured output (JSON/CSV) # - Write errors to stderr # - Exit with meaningful codes print(json.dumps({"result": "ok"})) ``` ## Quality Standards Good skill descriptions clearly explain what the skill does AND when to activate it: | Pattern | Example | |---------|---------| | Good | "Extracts text and tables from PDF files. Use when working with PDFs, forms, or document extraction." | | Poor | "Helps with PDFs." | Include specific keywords agents would encounter in user requests. Use imperative phrasing like "Use this skill when...". --- ## Internationalization (i18n) ### 相关页面 相关主题：[Component Architecture](#component-architecture), [Next.js Website Structure](#nextjs-structure)
相关源码文件 以下源码文件用于生成本页说明： - [website/src/lib/i18n.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/lib/i18n.tsx) - [README.es.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.es.md) - [README.ja.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.ja.md) - [README.ko.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.ko.md) - [README.zh-CN.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.zh-CN.md) - [README.zh-TW.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.zh-TW.md) - [website/src/components/Navbar.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Navbar.tsx) - [website/src/components/Footer.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Footer.tsx)
# Internationalization (i18n) ## Overview The awesome-agent-skills project implements a comprehensive internationalization system that enables the website and documentation to be presented in multiple languages. The i18n system supports six languages: English (default), Spanish, Japanese, Korean, Simplified Chinese, and Traditional Chinese. The architecture leverages Next.js App Router conventions with a centralized translation library that provides type-safe access to localized content across all components. ## Architecture ```mermaid graph TD A[User Interface] --> B[Navbar Component] B --> C{Language Selector} C --> D[Set Language State] D --> E[i18n Context] E --> F[useTranslations Hook] F --> G[Translation Files] H[Localized README Files] --> I[website/public] H --> J[GitHub Repository] K[Spanish] --> G L[Japanese] --> G M[Korean] --> G N[Simplified Chinese] --> G O[Traditional Chinese] --> G P[English] --> G ``` ## Supported Languages The project maintains translations for the following languages: | Language | Code | Flag | README File | |----------|------|------|-------------| | English | `en` | 🇺🇸 | (default) | | Spanish | `es` | 🇪🇸 | `README.es.md` | | Japanese | `ja` | 🇯🇵 | `README.ja.md` | | Korean | `ko` | 🇰🇷 | `README.ko.md` | | Simplified Chinese | `zh-CN` | 🇨🇳 | `README.zh-CN.md` | | Traditional Chinese | `zh-TW` | 🇹🇼 | `README.zh-TW.md` | 资料来源：[README.es.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.es.md) 资料来源：[README.ja.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.ja.md) 资料来源：[README.ko.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.ko.md) 资料来源：[README.zh-CN.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.zh-CN.md) 资料来源：[README.zh-TW.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/README.zh-TW.md) ## Core Components ### i18n Library The translation system is implemented in `website/src/lib/i18n.tsx`. This module provides the foundational translation infrastructure used throughout the React application. Key exports include: - Translation context provider - `useTranslations()` hook for component-level translations - Language configuration constants 资料来源：[website/src/components/Navbar.tsx:3](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Navbar.tsx) ### Language Configuration The `LANGUAGES` array defines all supported locales with their metadata: ```typescript // Configuration includes: { code: string, // Locale identifier (e.g., 'en', 'zh-CN') flag: string, // Emoji flag for UI display } ``` 资料来源：[website/src/components/Navbar.tsx:1-50](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Navbar.tsx) ## Language Selector Component ### Component Structure The language selector is implemented in the `Navbar` component, providing users with an accessible dropdown to change their preferred language. ```mermaid graph LR A[Globe Icon] --> B[Button Click] B --> C{langOpen State} C -->|true| D[Show Dropdown] C -->|false| E[Hide Dropdown] D --> F[Language Options] F --> G[Select Language] G --> H[setLang Function] H --> I[Update Context] I --> J[Close Dropdown] ``` ### Features | Feature | Description | |---------|-------------| | Dropdown Toggle | Animated show/hide with `AnimatePresence` | | Language List | Renders all languages from `LANGUAGES` array | | Flag Display | Shows flag emoji for quick visual identification | | State Management | Uses `langRef` for click-outside detection | | Accessibility | Includes `aria-label` for screen readers | 资料来源：[website/src/components/Navbar.tsx:1-60](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Navbar.tsx) ### Implementation Details ```tsx
{langOpen && ( {LANGUAGES.map((l) => (
``` 资料来源：[website/src/components/Navbar.tsx:15-40](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Navbar.tsx) ## Usage Patterns ### Component-Level Translations Components access translations via the `useTranslations()` hook: ```tsx import { useTranslations } from "@/lib/i18n"; export default function ExampleComponent() { const t = useTranslations(); return (

{t.how.title}

{t.how.subtitle}

); } ``` 资料来源：[website/src/components/sections/HowItWorks.tsx:3-8](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/HowItWorks.tsx) ### Translation Namespace Access Translations are organized into namespaces (e.g., `how`, `quality`, `footer`). Components access specific sections: ```tsx const stages = t.how.stages; // Array of stage data const quality = t.quality; // Quality section content const footer = t.footer; // Footer translations ``` 资料来源：[website/src/components/sections/WhatIsIt.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/WhatIsIt.tsx) 资料来源：[website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx) 资料来源：[website/src/components/Footer.tsx:1-30](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Footer.tsx) ## Documentation Localization ### README Translations The repository maintains full README translations in all supported languages. Each localized README follows the naming convention `README.{locale}.md`. | File | Purpose | |------|---------| | `README.md` | English (default) | | `README.es.md` | Spanish documentation | | `README.ja.md` | Japanese documentation | | `README.ko.md` | Korean documentation | | `README.zh-CN.md` | Simplified Chinese documentation | | `README.zh-TW.md` | Traditional Chinese documentation | ### Citation Format The Footer component displays BibTeX citation format that adapts to the selected language context: ```bibtex @misc{awesome-agent-skills, author = {Hailey Cheng (Cheng Hei Lam)}, title = {Agent Skill Index}, year = {2026}, publisher = {GitHub}, url = {https://github.com/heilcheng/awesome-agent-skills} } ``` 资料来源：[website/src/components/Footer.tsx:20-30](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Footer.tsx) ## Adding New Translations ### Adding a New Language 1. Create a new `README.{code}.md` file in the repository root 2. Add the language configuration to the `LANGUAGES` array in `i18n.tsx` 3. Add translation keys to the translation files 4. Update the language selector dropdown styling if needed ### Translation Key Structure ```typescript interface Translations { nav: { // Navigation translations }; how: { title: string; subtitle: string; steps: Array<{ step: string; title: string; desc: string; }>; }; quality: { // Quality standards translations }; footer: { // Footer text including citation label }; } ``` ## Best Practices ### Type Safety The i18n system uses TypeScript to ensure type-safe access to translation keys. Always use the `useTranslations()` hook rather than direct object access to maintain type checking. ### Lazy Loading Translation content is loaded on-demand through the Next.js App Router, ensuring minimal bundle impact when users view the site. ### Accessibility The language selector includes proper ARIA labels and keyboard navigation support for screen reader users. ## External Resources - Official specification: [agentskills.io/specification](https://agentskills.io/specification) - Project repository: [github.com/heilcheng/awesome-agent-skills](https://github.com/heilcheng/awesome-agent-skills) - Agent Skill website: [agent-skill.co](https://agent-skill.co) 资料来源：[website/src/components/WikiSidebar.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/WikiSidebar.tsx) --- ## Deployment Configuration ### 相关页面 相关主题：[Next.js Website Structure](#nextjs-structure), [Component Architecture](#component-architecture)
相关源码文件 以下源码文件用于生成本页说明： - [website/README.md](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/README.md) - [website/package.json](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/package.json) - [website/index.html](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/index.html) - [website/src/components/Footer.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/Footer.tsx) - [website/src/components/sections/Contributing.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/Contributing.tsx) - [website/src/components/sections/UsingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/UsingSkills.tsx) - [website/src/components/sections/FindingSkills.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/FindingSkills.tsx) - [website/src/components/sections/WhatIsIt.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/WhatIsIt.tsx) - [website/src/components/sections/QualityStandards.tsx](https://github.com/heilcheng/awesome-agent-skills/blob/main/website/src/components/sections/QualityStandards.tsx)
# Deployment Configuration ## Overview The **awesome-agent-skills** project is a Next.js application that serves as a comprehensive directory for AI agent skills. The deployment configuration encompasses the build system, runtime environment, and hosting setup required to deploy this web application to production. 资料来源：[website/README.md:1]() The project is designed to be deployed on **Vercel**, the platform created by the developers of Next.js, which provides optimized deployment workflows for Next.js applications. 资料来源：[website/README.md:32-34]() ## Project Architecture The project follows a modern Next.js architecture using the App Router pattern. This architectural choice impacts how the application is built and deployed. 资料来源：[website/README.md:13]() ```mermaid graph TD A[Source Code] --> B[Next.js Build] B --> C[Static Assets] B --> D[Server Components] D --> E[Vercel Edge Network] C --> E E --> F[End Users] G[Environment Variables] --> B H[Dependencies] --> B ``` ## Build System Configuration ### Package Manager Support The project supports multiple package managers for development and dependency installation: | Package Manager | Command | Notes | |----------------|---------|-------| | npm | `npm run dev` | Default Node.js package manager | | yarn | `yarn dev` | Facebook's package manager | | pnpm | `pnpm dev` | Fast, disk space efficient | | bun | `bun dev` | JavaScript runtime and toolchain | 资料来源：[website/README.md:7-15]() ### Development Server The development server runs locally on `http://localhost:3000` by default. This can be configured through environment variables or the Next.js configuration file. 资料来源：[website/README.md:17]() ```bash # Starting the development server npm run dev # or yarn dev # or pnpm dev # or bun dev ``` ### Production Build The project uses standard Next.js build commands. When deployed to Vercel, the platform automatically detects the Next.js framework and runs the appropriate build commands. 资料来源：[website/README.md:32-34]() ## Font Optimization The project uses `next/font` for automatic font optimization. This feature optimizes fonts and removes layout shifts for improved performance. 资料来源：[website/README.md:21]() ```typescript // Example usage from Next.js documentation import { Geist } from "next/font/google" // Configuration is handled automatically by next/font ``` The font optimization occurs at build time, embedding font files directly into the application for faster page loads and reduced external requests. ## Theme and Styling Configuration ### Dark/Light Theme Support The application implements a CSS custom properties-based theming system that supports both dark and light modes. The theming is defined through CSS variables at the `:root` level. 资料来源：[website/index.html:1-50]() ```css :root{ --bg:#000; --bg1:rgba(255,255,255,0.03); --bg2:rgba(255,255,255,0.05); --bg3:rgba(255,255,255,0.08); --border:rgba(255,255,255,0.08); --border2:rgba(255,255,255,0.12); --text:rgba(255,255,255,0.95); } ``` The theme configuration includes: | Variable | Purpose | |----------|---------| | `--bg` | Primary background color | | `--bg1`, `--bg2`, `--bg3` | Background opacity variations | | `--border`, `--border2` | Border and divider colors | | `--text` | Primary text color | 资料来源：[website/index.html:8-16]() ### Component-Level Theming Individual components implement theme-aware styling using Tailwind CSS utility classes with dark mode variants: ```typescript // Example from Footer.tsx className="text-white dark:text-neutral-900" className="bg-zinc-900 dark:bg-white" ``` 资料来源：[website/src/components/Footer.tsx:10-12]() ## Environment Configuration ### Public Environment Variables The project exposes certain environment variables for public use. These are prefixed with `NEXT_PUBLIC_` and are accessible in both server and client code. 资料来源：[website/README.md:17]() ### Site Metadata The deployment includes the following metadata configuration: | Setting | Value | |---------|-------| | Site Title | Agent Skill Index | | Description | The Ultimate AI Agent Skills List & Tutorials | | Language | English (en) | | Theme Color | Dark (default) | 资料来源：[website/index.html:2-7]() ## Deployment to Vercel ### Automatic Detection Vercel automatically detects Next.js projects during deployment. The platform performs the following steps: 1. Detects `next` in `package.json` dependencies 2. Identifies the framework as Next.js 3. Runs the appropriate build command 4. Optimizes the output for edge deployment 资料来源：[website/README.md:32-34]() ### Deployment Links The project includes configured deployment links for easy access: | Environment | URL | Purpose | |------------|-----|---------| | Production | agent-skill.co | Primary production site | | Repository | github.com/heilcheng/awesome-agent-skills | Source code hosting | 资料来源：[website/src/components/Footer.tsx:7-13]() ## Linting and Code Quality ### ESLint Configuration The project uses ESLint for code quality enforcement. The configuration file is located at `website/eslint.config.mjs`. 资料来源：[查询文件: website/eslint.config.mjs]() ESLint runs during the development process and CI/CD pipelines to ensure code consistency and catch potential issues before deployment. ### Code Style Guidelines Components follow consistent coding patterns: - TypeScript for type safety - Tailwind CSS utility classes for styling - Dark mode support via `dark:` variants - Consistent naming conventions 资料来源：[website/src/components/sections/QualityStandards.tsx:1-20]() ## Post-Processing Configuration ### PostCSS Configuration The project uses PostCSS for processing CSS. Configuration is defined in `website/postcss.config.mjs` to support: - Tailwind CSS - Autoprefixer for browser compatibility - CSS modules (if used) 资料来源：[查询文件: website/postcss.config.mjs]() ## CI/CD Considerations The repository structure supports continuous integration and deployment through GitHub. When changes are pushed to the repository: 1. Vercel automatically pulls the latest changes 2. Build process runs automatically 3. Preview deployments are created for pull requests 4. Production deployment occurs on merges to main 资料来源：[website/src/components/sections/Contributing.tsx:25-35]() ## Development Workflow ```mermaid graph LR A[Local Development] -->|npm run dev| B[Dev Server] B --> C[Code Changes] C --> D[Auto Hot Reload] D --> B E[Git Push] --> F[Vercel] F --> G[Build] G --> H[Preview Deployment] I[Merge to Main] --> F H --> J[Production Deployment] ``` ## Related Documentation For additional deployment and development information, refer to: - [Next.js Documentation](https://nextjs.org/docs) - Official Next.js features and API documentation - [Vercel Platform](https://vercel.com/docs) - Deployment platform documentation - [Tailwind CSS](https://tailwindcss.com/docs) - Styling framework documentation ## Summary The deployment configuration for awesome-agent-skills is straightforward, leveraging Next.js's built-in deployment capabilities with Vercel. Key aspects include: 1. **Framework**: Next.js with App Router 2. **Hosting**: Vercel (automatic detection and deployment) 3. **Styling**: Tailwind CSS with dark/light theme support 4. **Fonts**: Automatic optimization via next/font 5. **Package Managers**: Supports npm, yarn, pnpm, and bun 6. **Code Quality**: ESLint integration for consistent code standards The configuration is production-ready out of the box and requires minimal additional setup for deployment. --- --- ## Doramagic 踩坑日志 项目：heilcheng/awesome-agent-skills 摘要：发现 10 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。 ## 1. 身份坑 · 仓库名和安装名不一致 - 严重度：medium - 证据强度：runtime_trace - 发现：仓库名 `awesome-agent-skills` 与安装入口 `skills` 不完全一致。 - 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。 - 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。 - 复现命令：`npx skills` - 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。 - 证据：identity.distribution | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | repo=awesome-agent-skills; install=skills ## 2. 配置坑 · 可能修改宿主 AI 配置 - 严重度：medium - 证据强度：source_linked - 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。 - 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 - 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。 - 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。 - 证据：capability.host_targets | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | host_targets=claude ## 3. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 建议检查：将假设转成下游验证清单。 - 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。 - 证据：capability.assumptions | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | README/documentation is current enough for a first validation pass. ## 4. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。 - 防护动作：维护活跃度未知时，推荐强度不能标为高信任。 - 证据：evidence.maintainer_signals | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | last_activity_observed missing ## 5. 安全/权限坑 · 下游验证发现风险项 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：下游已经要求复核，不能在页面中弱化。 - 建议检查：进入安全/权限治理复核队列。 - 防护动作：下游风险存在时必须保持 review/recommendation 降级。 - 证据：downstream_validation.risk_items | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | no_demo; severity=medium ## 6. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 建议检查：把风险写入边界卡，并确认是否需要人工复核。 - 防护动作：评分风险必须进入边界卡，不能只作为内部分数。 - 证据：risks.scoring_risks | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | no_demo; severity=medium ## 7. 安全/权限坑 · 来源证据：Add Rug Munch Intelligence - Crypto Security & Analytics Agent Skills (x402, Base + Solana) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add Rug Munch Intelligence - Crypto Security & Analytics Agent Skills (x402, Base + Solana) - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_dc99192b4a9b4b8089f4f6696f332a7d | https://github.com/heilcheng/awesome-agent-skills/issues/218 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。 ## 8. 安全/权限坑 · 来源证据：⚡ Pay-per-call web search, scraping & AI tools for your agent — VERITY (L402) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：⚡ Pay-per-call web search, scraping & AI tools for your agent — VERITY (L402) - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_0703404b82014fe3baddd3eaab1100bd | https://github.com/heilcheng/awesome-agent-skills/issues/226 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。 ## 9. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 建议检查：抽样最近 issue/PR，判断是否长期无人处理。 - 防护动作：issue/PR 响应未知时，必须提示维护风险。 - 证据：evidence.maintainer_signals | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | issue_or_pr_quality=unknown ## 10. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 建议检查：确认最近 release/tag 和 README 安装命令是否一致。 - 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。 - 证据：evidence.maintainer_signals | github_repo:1124920990 | https://github.com/heilcheng/awesome-agent-skills | release_recency=unknown