# https://github.com/sator-imaging/suggest-skills 项目说明书
生成时间：2026-05-15 11:39:34 UTC
## 目录
- [Project Overview](#overview)
- [Installation and Quick Start](#installation)
- [System Architecture](#system-architecture)
- [Core Components](#core-components)
- [MCP Tools Reference](#mcp-tools-reference)
- [CLI Commands](#cli-commands)
- [Environment Variables](#environment-variables)
- [Bundled Skills Reference](#bundled-skills)
- [Manifest Generation](#manifest-generation)
- [Runtime Modes](#runtime-modes)
## Project Overview
### 相关页面
相关主题：[Installation and Quick Start](#installation), [System Architecture](#system-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
- [package.json](https://github.com/sator-imaging/suggest-skills/blob/main/package.json)
- [src/download.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)
- [src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)
- [.github/workflows/generate-manifests.yml](https://github.com/sator-imaging/suggest-skills/blob/main/.github/workflows/generate-manifests.yml)
# Project Overview
**suggest-skills** is a Model Context Protocol (MCP) server and CLI tool that helps AI agents discover, compare, and manage available skills from remote manifests and locally installed skill collections. The project serves as a bridge between remote skill repositories and AI agent workflows, enabling intelligent skill suggestion without requiring immediate installation.
## Purpose and Scope
The primary purpose of suggest-skills is to provide AI agents with a systematic way to:
- **Fetch available skills** from configured remote manifests
- **Scan locally installed skills** in a standardized directory structure
- **Compare remote and local capabilities** to identify gaps and opportunities
- **Present suggestions** to users without forcing immediate installation
The project acts as a skill discovery layer, not a skill executor. It identifies what skills exist and recommends which ones might be useful based on context, but leaves the actual installation and execution to separate processes. 资料来源：[README.md]()
## Technology Stack
suggest-skills is built with modern JavaScript/TypeScript tooling optimized for server-side execution in AI agent environments.
| Component | Technology | Purpose |
|-----------|------------|---------|
| Runtime | Bun | Fast JavaScript runtime with built-in package management |
| Language | TypeScript | Type-safe development with compile-time checks |
| Protocol | @modelcontextprotocol/sdk | Standardized MCP communication |
| Validation | Zod | Runtime schema validation for configuration and tool inputs |
| Transport | stdio / HTTP | Dual-mode server communication |
资料来源：[README.md](), [package.json]()
## Architecture Overview
The project follows a layered architecture with clear separation between configuration, tool registration, and transport layers.
```mermaid
graph TD
A[Configuration
Environment Variables] --> B[Config Validation
ConfigError]
B --> C[MCP Tool Registration
suggest_skills, fetch_manifest
download_skill]
C --> D[Transport Layer]
D --> E[stdio Mode
stdin/stdout]
D --> F[HTTP Mode
localhost:3100]
G[GitHub API] --> H[download_skill tool]
I[Remote Manifests] --> J[suggest_skills tool]
J --> K[Local Skills Scanner]
```
资料来源：[README.md]()
## Core Components
### 1. Configuration System
The configuration layer validates environment settings and provides defaults for all operational parameters.
| Variable | Required | Format | Default |
|----------|----------|--------|---------|
| `GITHUB_PAT` | No | String | None (anonymous) |
| `SUGGEST_SKILLS_MANIFEST_URLS` | Yes | JSON array / CSV / newline-sep | None |
| `--port` (CLI) | No | Number | 3100 |
| `-o` / `--output` (CLI) | No | Directory path | `.agents/skills` |
The configuration accepts manifest URLs in multiple formats:
- JSON array: `["https://example.com/manifest.md"]`
- Comma-separated: `https://a.com/manifest.md,https://b.com/manifest.md`
- Newline-separated: `https://a.com/manifest.md\nhttps://b.com/manifest.md`
资料来源：[README.md]()
### 2. MCP Tools
The server exposes three primary MCP tools for agent interaction:
#### `suggest_skills`
Accepts an optional `manifestUrl` to overwrite the default configuration. Returns a generated instruction payload that tells an agent how to discover and compare skills.
**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `manifestUrl` | string | No | Override URL for manifest fetching |
#### `fetch_manifest`
Accepts a manifest URL and returns its raw text content for parsing.
**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `manifestUrl` | string | Yes | URL of the skill manifest to fetch |
#### `download_skill`
Downloads all files from a GitHub folder, preserving directory structure and file content.
**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `folderUrl` | string | Yes | GitHub folder URL in format `https://github.com///tree/[/` |
**Returns:**
- Path relative to the requested folder
- UTF-8 text content
- Resolved symlinks for GitHub-provided download URLs
资料来源：[README.md]()
### 3. CLI Commands
The command-line interface provides two primary operations:
#### Generate Mode
```bash
npx suggest-skills generate [options]
```
**Options:**
| Flag | Description |
|------|-------------|
| `-r, --recursive` | Recursively scan subdirectories |
**Output Files:**
- `.[.].skills.md` - Skill entries from directories containing `SKILL.md`
- `.[.].designs.md` - Design entries from directories containing `DESIGN.md`
- `.[.].agents.md` - Agent entries from flat markdown files with `Name` and `Description` columns
#### Server Mode
```bash
npx suggest-skills server --port
```
Starts the HTTP transport server for remote MCP connections.
资料来源：[README.md]()
## Transport Modes
suggest-skills supports dual transport mechanisms for different deployment scenarios:
```mermaid
graph LR
A[Agent] -->|stdio| B[suggest-skills]
A -->|HTTP| C[localhost:3100/mcp]
B --> D[Local Skills]
C --> D
C --> E[Health Check]
/health]
D --> F[Remote Manifests
via GitHub API]
```
### Stdio Mode
Suitable for local agent integration where the MCP server runs as a child process:
```bash
SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
npx suggest-skills
```
### HTTP Mode
Suitable for networked deployments where the agent connects remotely:
```bash
SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
npx suggest-skills server --port 3100
```
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/mcp` | POST | MCP protocol endpoint |
| `/health` | GET | Health check for monitoring |
资料来源：[README.md]()
## GitHub Integration
The download functionality integrates with GitHub's API to fetch skill packages:
### URL Processing
The system automatically handles GitHub URL normalization:
- Converts `github.com/blob/` URLs to `raw.githubusercontent.com` format
- Supports tree URLs for directory downloads
- Uses GitHub Contents API for file retrieval
### Download Flow
```mermaid
sequenceDiagram
participant Agent
participant Server as suggest-skills
participant GitHub as GitHub API
Agent->>Server: download_skill(folderUrl)
Server->>GitHub: GET /repos/{owner}/{repo}/git/trees/{sha}?recursive=1
GitHub-->>Server: Tree structure with file/blob entries
Server->>GitHub: For each file: GET /repos/{owner}/{repo}/contents/{path}
GitHub-->>Server: File contents
Server-->>Agent: Array of {path, download_url, type, content}
```
资料来源：[src/download.ts]()
## Project Structure
```
suggest-skills/
├── src/
│ ├── download.ts # GitHub folder download logic
│ └── generate.ts # Manifest generation logic
├── official/ # Official bundled skills
├── community/ # Community-contributed skills
├── .github/
│ └── workflows/
│ └── generate-manifests.yml # Cron-based manifest updates
├── package.json
└── README.md
```
The repository maintains both official and community skill manifests, updated daily via a cron workflow that scans skill directories and generates indexed markdown files. 资料来源：[README.md]()
## Coding Standards
The codebase adheres to several architectural principles:
| Principle | Implementation |
|-----------|----------------|
| **Modularity** | Small focused modules with runtime concerns split by file |
| **Configuration** | Explicit validation through `ConfigError` class |
| **Type Safety** | Typed tool schemas and structured output for all MCP tools |
| **Testing** | Observable behavior over implementation detail |
资料来源：[README.md]()
## Workflow Integration
The typical agent workflow using suggest-skills follows this pattern:
1. **Initialization**: Agent loads suggest-skills MCP server with manifest URLs
2. **Discovery**: Agent calls `suggest_skills` to get guidance on available capabilities
3. **Comparison**: Agent scans local `.agents/skills` directory against remote manifests
4. **Recommendation**: Agent presents available skills without forcing installation
5. **Installation**: On user request, agent uses `download_skill` to fetch specific packages
This separation allows agents to provide informed recommendations while deferring resource-intensive installation operations until explicitly requested.
资料来源：[README.md]()
## Key Features Summary
| Feature | Description |
|---------|-------------|
| Multi-manifest support | Fetch from multiple remote sources simultaneously |
| Dual transport | stdio and HTTP server modes |
| GitHub integration | Direct repository scanning and file download |
| Automated updates | Daily cron job regenerates skill manifests |
| Offline capability | Compare local skills without network access |
| Type-safe | Full TypeScript with Zod validation |
| Bundled skills | Official skills, agents, and designs included |
---
## Installation and Quick Start
### 相关页面
相关主题：[Project Overview](#overview), [Runtime Modes](#runtime-modes)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
- [src/download.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)
- [src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)
- [src/cmd_generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/cmd_generate.ts)
- [Unity/unity-yaml-format/references/class-id-reference.md](https://github.com/sator-imaging/suggest-skills/blob/main/Unity/unity-yaml-format/references/class-id-reference.md)
# Installation and Quick Start
## Overview
`suggest-skills` is a Model Context Protocol (MCP) server that helps AI agents discover, compare, and suggest skills from configured manifests and locally installed skill repositories. The tool enables agents to understand available capabilities without requiring immediate installation, facilitating intelligent skill recommendations for various tasks.
The server operates in two modes:
- **stdio mode**: Direct integration with AI agent tooling via standard input/output
- **HTTP mode**: Streamable HTTP server for remote agent connections
资料来源：[README.md]()
## Prerequisites
Before installing `suggest-skills`, ensure your environment meets the following requirements:
| Requirement | Version | Notes |
|-------------|---------|-------|
| Runtime | Bun 1.0+ | Primary runtime for the project |
| Node.js | 18+ | Alternative runtime if Bun is unavailable |
| Git | Any recent version | For repository operations |
| GitHub PAT | Optional | Increases API rate limits for GitHub operations |
资料来源：[README.md]()
## Installation Methods
### Method 1: NPX (Recommended for Quick Start)
The simplest way to run `suggest-skills` without installation:
```bash
npx suggest-skills
```
### Method 2: Global Installation
For frequent use, install globally via npm:
```bash
npm install -g suggest-skills
```
### Method 3: Local Project Installation
For project-specific usage:
```bash
npm install suggest-skills
```
### Method 4: Build from Source
```bash
git clone https://github.com/sator-imaging/suggest-skills.git
cd suggest-skills
bun install
bun build
```
资料来源：[README.md]()
## Configuration
### Environment Variables
The server requires configuration through environment variables:
| Variable | Required | Description |
|----------|----------|-------------|
| `SUGGEST_SKILLS_MANIFEST_URLS` | Yes | URLs to skill manifest files (JSON array, comma-separated, or newline-separated) |
| `GITHUB_PAT` | No | Personal Access Token for authenticated GitHub API requests |
#### Configuration Examples
**JSON array format:**
```bash
SUGGEST_SKILLS_MANIFEST_URLS='["https://example.com/manifest.md", "https://other.com/skills.md"]' \
npx suggest-skills
```
**Comma-separated format:**
```bash
SUGGEST_SKILLS_MANIFEST_URLS='https://example.com/manifest.md,https://other.com/skills.md' \
npx suggest-skills
```
**Newline-separated format:**
```bash
SUGGEST_SKILLS_MANIFEST_URLS='https://example.com/manifest.md
https://other.com/skills.md' \
npx suggest-skills
```
资料来源：[README.md]()
### Manifest URL Conversion
The system automatically converts GitHub `blob` URLs to `raw.githubusercontent.com` URLs:
```
# Input (blob URL)
https://github.com/OWNER/REPO/blob/main/skills/manifest.md
# Automatically converted to
https://raw.githubusercontent.com/OWNER/REPO/main/skills/manifest.md
```
资料来源：[README.md]()
## Running the Tool
### stdio Mode
Standard I/O mode for direct agent integration:
```bash
SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
npx suggest-skills
```
### HTTP Mode
Streamable HTTP server for remote agent connections:
```bash
SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
npx suggest-skills server --port 3100
```
| Endpoint | URL | Purpose |
|----------|-----|---------|
| MCP Server | `http://localhost:3100/mcp` | Main MCP protocol endpoint |
| Health Check | `http://localhost:3100/health` | Server status verification |
资料来源：[README.md]()
## CLI Commands
### Generate Command
Create markdown inventories from GitHub skill directories:
```bash
npx suggest-skills generate
```
**Options:**
| Option | Description |
|--------|-------------|
| `-o `, `--output ` | Output directory for installed skills (default: `.agents/skills`) |
| `-r`, `--recursive` | Recursively scan subdirectories |
**Examples:**
```bash
# Generate from skills directory
npx suggest-skills generate https://github.com/OWNER/REPO/tree/main/skills
# Generate with recursive scanning
npx suggest-skills generate --recursive https://github.com/OWNER/REPO/tree/main/skills
# Generate with custom output directory
npx suggest-skills generate -o ./my-skills https://github.com/OWNER/REPO/tree/main/skills
```
### Generate Output Files
The generate command creates the following files in the current working directory:
| File Pattern | Content |
|-------------|---------|
| `.[.].skills.md` | Skill entries from directories containing `SKILL.md` |
| `.[.].designs.md` | Design entries from directories containing `DESIGN.md` |
| `.[.].agents.md` | Agent entries from top-level markdown files |
### Server Command
Start the HTTP MCP server:
```bash
npx suggest-skills server --port
```
资料来源：[README.md]()
## MCP Tools
The server provides three MCP tools for agent interaction:
### suggest_skills
Returns a generated instruction payload that tells an agent how to:
- Fetch available skills from configured manifests
- Scan locally installed skills
- Compare remote and local capabilities
- Present suggestions without installing until requested
```json
{
"manifestUrl": "optional-override-url"
}
```
### fetch_manifest
Fetches and returns the text content of a manifest URL:
```json
{
"manifestUrl": "https://example.com/manifest.md"
}
```
### download_skill
Downloads all files from a GitHub folder URL:
```json
{
"folderUrl": "https://github.com///tree/[/"
}
```
Returns each file with:
- Path relative to the requested folder
- UTF-8 text content
- Symlinks resolved and downloaded recursively
资料来源：[README.md]()
## Project Architecture
```mermaid
graph TD
A[Config] --> B[MCP Tool Registration]
B --> C[Stdio Transport]
B --> D[HTTP Transport]
E[CLI Generate] --> F[GitHub Directory Scan]
E --> G[Manifest Markdown File]
H[GitHub URL Normalization] --> F
H --> I[Folder Download]
J[GitHub API] --> K[Tree API]
J --> L[Contents API]
K --> M[Recursive Discovery]
L --> M
```
### Technology Stack
| Component | Technology | Purpose |
|-----------|------------|---------|
| Runtime | Bun | Primary JavaScript runtime |
| Language | TypeScript | Type-safe development |
| SDK | @modelcontextprotocol/sdk | MCP protocol implementation |
| Validation | Zod | Runtime schema validation |
资料来源：[README.md]()
## Coding Standards
The codebase follows these implementation patterns:
- **Modular design**: Small, focused modules with runtime concerns split by file
- **Config validation**: Explicit validation through `ConfigError` class
- **Typed schemas**: Tool schemas with structured output for MCP tools
- **Minimal transport wrappers**: Lightweight wrappers around shared server creation
- **Behavior-driven tests**: Tests focused on observable behavior rather than implementation details
资料来源：[README.md]()
## Troubleshooting
### Common Issues
| Issue | Solution |
|-------|----------|
| "Manifest URL required" error | Set `SUGGEST_SKILLS_MANIFEST_URLS` environment variable |
| Rate limiting from GitHub | Set `GITHUB_PAT` environment variable |
| Empty manifest output | Verify manifest URLs are accessible |
| Symlink issues | Note that repository-relative symlinks are resolved recursively, but symlinks found during generate are not handled specially |
### Health Check Verification
For HTTP mode, verify the server is running:
```bash
curl http://localhost:3100/health
```
资料来源：[README.md]()
## Next Steps
After completing installation:
1. **Configure manifests**: Set up `SUGGEST_SKILLS_MANIFEST_URLS` with your skill repositories
2. **Explore official skills**: Browse the [official skills](https://github.com/sator-imaging/suggest-skills/tree/main/official/skills) directory
3. **Explore community skills**: Browse the [community skills](https://github.com/sator-imaging/suggest-skills/tree/main/community/) directory
4. **Generate custom manifests**: Use the CLI to create skill inventories from any GitHub repository
5. **Integrate with agents**: Connect the MCP server to your AI agent tooling
---
## System Architecture
### 相关页面
相关主题：[Core Components](#core-components), [MCP Tools Reference](#mcp-tools-reference)
]
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
- [src/config.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)
- [src/download.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)
- [src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)
# System Architecture
## Overview
`suggest-skills` is an MCP (Model Context Protocol) server and CLI tool that helps AI agents discover, compare, and manage skills from configured manifests and local installations. The system provides a unified interface for skill discovery without requiring immediate installation, enabling agents to make informed decisions about which capabilities to load. 资料来源：[README.md:1-50]()
## Technology Stack
| Component | Technology | Purpose |
|-----------|------------|---------|
| Runtime | Bun | JavaScript/TypeScript execution runtime |
| Language | TypeScript | Type-safe application development |
| Protocol | @modelcontextprotocol/sdk | MCP server implementation |
| Validation | Zod | Runtime schema validation |
资料来源：[README.md:180-190]()
## High-Level Architecture
```mermaid
graph TD
subgraph "Configuration Layer"
ENV[Environment Variables]
CLI[CLI Arguments]
CFG[Config Validator]
end
subgraph "Transport Layer"
STDIO[Stdio Transport]
HTTP[HTTP Server Transport]
end
subgraph "Core Layer"
MCP[MCP Tool Registration]
CORE[Core Logic]
end
subgraph "External Services"
GITHUB[GitHub API]
MANIFEST[Skill Manifests]
end
ENV --> CFG
CLI --> CFG
CFG --> MCP
MCP --> STDIO
MCP --> HTTP
CORE --> GITHUB
CORE --> MANIFEST
style Configuration Layer fill:#e1f5fe
style Transport Layer fill:#fff3e0
style Core Layer fill:#e8f5e9
```
The architecture follows a layered approach where configuration flows downward to tool registration, which then branches into transport modes. 资料来源：[README.md:192-205]()
## Core Components
### Project Architecture Pattern
```text
Config -> MCP tool registration -> stdio or HTTP transport
CLI generate -> GitHub directory scan -> manifest markdown file
\-> GitHub URL normalization / folder download
```
资料来源：[README.md:192-205]()
### Directory Structure
```
src/
├── index.ts # Entry point and server initialization
├── config.ts # CLI argument parsing and configuration
├── core.ts # Core business logic
├── download.ts # GitHub folder download utilities
└── generate.ts # Manifest generation logic
```
### Component Responsibilities
| Component | File | Responsibilities |
|-----------|------|------------------|
| Entry Point | `src/index.ts` | Server initialization, transport setup |
| Configuration | `src/config.ts` | CLI parsing, environment variable validation |
| Core Logic | `src/core.ts` | Skill suggestion algorithms, manifest processing |
| Download | `src/download.ts` | GitHub API integration, file retrieval |
| Generation | `src/generate.ts` | Manifest file creation, directory scanning |
资料来源：[src/config.ts:1-80]()
## MCP Tools
The server exposes three primary MCP tools for agent interaction:
### Tool Specifications
| Tool Name | Purpose | Input | Output |
|-----------|---------|-------|--------|
| `suggest_skills` | Generate skill suggestions based on manifests | `manifestUrl?: string` | Instruction payload for agent |
| `fetch_manifest` | Retrieve manifest content | `manifestUrl: string` | Raw manifest text |
| `download_skill` | Download skill folder contents | `githubUrl: string` | File contents with paths |
资料来源：[README.md:130-170]()
### `download_skill` Tool
Accepts GitHub folder URLs in the format:
```
https://github.com///tree/[/
```
Returns files with:
- Path relative to requested folder
- UTF-8 text content
- Resolved symlinks for repository-relative directory symlinks
资料来源：[README.md:155-165]()
## CLI Interface
### Command Structure
```mermaid
graph LR
A[suggest-skills] --> B[generate]
A --> C[download]
A --> D[server]
A --> E[stdio mode]
B --> F[]
B --> G[-r --recursive]
C --> H[]
C --> I[-r --recursive]
D --> J[--port ]
```
资料来源：[src/config.ts:1-50]()
### CLI Commands
| Command | Syntax | Description |
|---------|--------|-------------|
| Generate | `npx suggest-skills generate ` | Generate markdown inventories |
| Generate (recursive) | `npx suggest-skills generate --recursive ` | Recursive directory scan |
| Download | `npx suggest-skills download ` | Download skills to local directory |
| Server | `npx suggest-skills server --port ` | Run HTTP server mode |
| Stdio | `npx suggest-skills` | Run in stdio mode (default) |
### CLI Options
| Option | Description | Default |
|--------|-------------|---------|
| `-o `, `--output ` | Output directory for installed skills | `.agents/skills` |
| `-r`, `--recursive` | Recursive scan for generate/download | `false` |
资料来源：[src/config.ts:10-60]()
## Configuration System
### Environment Variables
| Variable | Required | Description |
|----------|----------|-------------|
| `GITHUB_PAT` | Optional | Personal Access Token for authenticated GitHub API requests |
| `SUGGEST_SKILLS_MANIFEST_URLS` | Required | Comma-separated list of manifest URLs |
### Manifest URL Formats
Accepted formats for `SUGGEST_SKILLS_MANIFEST_URLS`:
- JSON array: `["https://some/skill-manifest.md"]`
- Comma-separated string: `https://one/skill.md,https://two/skills.md`
- Newline-separated string
- GitHub `blob` URLs auto-converted to `raw.githubusercontent.com`
资料来源：[README.md:208-230]()
### Configuration Validation
```typescript
interface CliRuntimeMode {
kind: "generate" | "download" | "server" | "stdio";
url?: string;
recursive?: boolean;
config: {
outputDirectory: string;
sourceUrls: string[];
};
}
```
资料来源：[src/config.ts:50-80]()
## Transport Modes
### Stdio Mode
Default mode for local agent integration:
```bash
SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
npx suggest-skills
```
Messages exchanged via standard input/output streams. 资料来源：[README.md:238-242]()
### HTTP Server Mode
Streamable HTTP transport for distributed deployments:
```bash
SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
npx suggest-skills server --port 3100
```
| Endpoint | Purpose |
|----------|---------|
| `http://localhost:3100/mcp` | MCP protocol endpoint |
| `http://localhost:3100/health` | Health check endpoint |
资料来源：[README.md:245-252]()
## GitHub Integration
### API Integration Flow
```mermaid
sequenceDiagram
participant CLI as CLI/Server
participant API as GitHub API
participant FS as File System
CLI->>API: Request directory tree (recursive)
API-->>CLI: Tree structure with paths and SHAs
CLI->>API: Request contents for each file
API-->>CLI: File contents
CLI->>FS: Write files to output directory
Note over CLI: buildTreeApiUrl()
Note over CLI: buildContentsApiUrl()
```
资料来源：[src/download.ts:30-80]()
### URL Building Utilities
| Function | Purpose |
|----------|---------|
| `buildContentsApiUrl()` | Construct GitHub contents API endpoint |
| `buildTreeApiUrl()` | Construct GitHub git trees API endpoint |
| `buildGithubRawUrl()` | Build raw content URLs for downloads |
资料来源：[src/download.ts:30-70]()
### Directory Scanning Logic
The generate command scans directories with these rules:
1. Discover `SKILL.md` and `DESIGN.md` in skill directories
2. Bundle assets are files next to or nested within skill directories
3. Empty generated outputs are skipped
4. Symlinks are not traversed specially; may appear in bundled assets
资料来源：[src/generate.ts:1-80]()
资料来源：[README.md:90-100]()
## Coding Standards
The codebase adheres to specific implementation patterns:
- **Modularity**: Small, focused modules with runtime concerns split by file
- **Validation**: Explicit config validation through `ConfigError`
- **Typing**: Typed tool schemas and structured output for MCP tools
- **Testing**: Observable behavior over implementation detail
- **Transport**: Minimal wrappers around shared server creation
资料来源：[README.md:207-215]()
## Manifest Generation
### Output Files
The generate command produces markdown files:
| File Pattern | Source | Content |
|--------------|--------|---------|
| `..skills.md` | Directories with `SKILL.md` | Skill entries with descriptions |
| `..designs.md` | Directories with `DESIGN.md` | Design entries |
| `..agents.md` | Top-level markdown files | Agent definitions (Name + Description only) |
### Generation Rules
- GitHub directory discovery uses recursive tree listing internally
- `SKILL.md` and `DESIGN.md` are discovered in skill directories
- Bundled assets are files next to them or in nested subdirectories
- Symlinks found are not handled specially
- Empty outputs are skipped silently
资料来源：[README.md:83-100]()
## Data Flow Diagrams
### Stdio Mode Data Flow
```mermaid
graph TD
A[User/Agent] -->|Stdin| B[MCP Server]
B -->|Parse Command| C[Config Validator]
C -->|Valid Config| D[Tool Executor]
D -->|suggest_skills| E[Fetch Manifests]
D -->|fetch_manifest| F[HTTP Request]
D -->|download_skill| G[GitHub API]
E -->|Skill List| B
F -->|Manifest Text| B
G -->|File Contents| B
B -->|Stdout| A
```
### HTTP Server Mode Data Flow
```mermaid
graph TD
A[Remote Agent] -->|HTTP POST /mcp| B[HTTP Server]
B -->|Forward| C[MCP Handler]
C -->|Execute| D[Tool Executor]
D -->|GitHub API| E[External Services]
C -->|Response| B
B -->|HTTP Response| A
F[Health Check] -->|GET /health| B
B -->|200 OK| F
```
## Configuration Error Handling
The system validates configuration at startup and throws `ConfigError` for:
- Missing required environment variables
- Invalid manifest URL formats
- Invalid CLI argument combinations
资料来源：[src/config.ts:60-80]()
---
## Core Components
### 相关页面
相关主题：[System Architecture](#system-architecture), [MCP Tools Reference](#mcp-tools-reference)
]
相关源码文件
以下源码文件用于生成本页说明：
- [src/config.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)
- [src/constants.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/constants.ts)
- [src/utils.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/utils.ts)
- [src/suggest.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/suggest.ts)
- [src/download.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)
- [src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)
# Core Components
## Overview
The suggest-skills project implements an MCP (Model Context Protocol) server that provides skill discovery and installation capabilities for AI agents. The core components handle configuration management, skill suggestion logic, GitHub repository scanning, and manifest generation.
The system operates in two primary modes: **stdio mode** for direct CLI interaction and **HTTP mode** for network-accessible MCP endpoints. 资料来源：[README.md]()
## Architecture Overview
```mermaid
graph TD
subgraph "Transport Layer"
STDIO[Stdio Transport]
HTTP[HTTP Transport]
end
subgraph "Core Components"
CONFIG[Config Module]
CONSTANTS[Constants Module]
UTILS[Utils Module]
end
subgraph "MCP Tools"
SUGGEST[Suggest Skills Tool]
FETCH[Fetch Manifest Tool]
DOWNLOAD[Download Skill Tool]
end
subgraph "CLI Components"
GENERATE[Generate Module]
end
STDIO --> SERVER[Server Creation]
HTTP --> SERVER
SERVER --> CONFIG
SERVER --> SUGGEST
SERVER --> FETCH
SERVER --> DOWNLOAD
SERVER --> GENERATE
CONFIG --> CONSTANTS
CONFIG --> UTILS
```
## Component Breakdown
### 1. Config Module (`src/config.ts`)
The Config module handles application configuration validation and management.
**Responsibilities:**
- Validates required environment variables
- Parses manifest URLs from configuration
- Handles `ConfigError` exceptions for invalid configurations
**Environment Variables:**
| Variable | Required | Description |
|----------|----------|-------------|
| `SUGGEST_SKILLS_MANIFEST_URLS` | Yes | Comma-separated, newline-separated, or JSON array of manifest URLs |
| `GITHUB_PAT` | No | Personal Access Token for authenticated GitHub API requests |
**Configuration Flow:**
```mermaid
graph LR
A[Environment Variables] --> B[Config Parser]
B --> C{Valid Manifest URLs?}
C -->|Yes| D[Return Valid Config]
C -->|No| E[Throw ConfigError]
```
资料来源：[src/config.ts]()
### 2. Constants Module (`src/constants.ts`)
The Constants module defines reusable values used across the application.
**Key Constants:**
| Constant | Value | Purpose |
|----------|-------|---------|
| `GITHUB_API_BASE_URL` | `https://api.github.com` | Base URL for GitHub API |
| `DEFAULT_OUTPUT_DIR` | `.agents/skills` | Default installation directory |
| `DEFAULT_PORT` | `3100` | Default HTTP server port |
The module also defines type aliases and reusable schema patterns for MCP tool inputs. 资料来源：[src/constants.ts]()
### 3. Utils Module (`src/utils.ts`)
The Utils module provides shared utility functions used by multiple components.
**Core Utilities:**
| Function | Purpose |
|----------|---------|
| `basename()` | Extract filename from path |
| `dirname()` | Extract directory from path |
| `shouldIgnoreGeneratedAsset()` | Filter out generated manifest files |
**Path Handling:**
```mermaid
graph TD
A[GitHub Path] --> B{Nested Directory?}
B -->|No| C[Immediate Entry]
B -->|Yes| D[Create Dir Entry]
D --> E[Recursive Processing]
```
The utility functions handle path normalization by removing leading slashes and ensuring consistent URL construction. 资料来源：[src/utils.ts]()
### 4. Suggest Module (`src/suggest.ts`)
The Suggest module implements the `suggest_skills` MCP tool that generates instruction payloads for skill discovery.
**Tool Interface:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `manifestUrl` | string | No | Override manifest URL |
**Workflow:**
```mermaid
graph TD
A[Suggest Request] --> B{manifestUrl Provided?}
B -->|Yes| C[Use Provided URL]
B -->|No| D[Load from Config]
C --> E[Fetch Available Skills]
D --> E
E --> F[Scan Local Skills]
F --> G[Compare Remote vs Local]
G --> H[Generate Instruction Payload]
H --> I[Return to Agent]
```
**Instruction Payload Contents:**
- How to fetch skills from configured manifests
- How to scan locally installed skills
- Comparison logic for remote and local capabilities
- Presentation format for suggestions without installation
资料来源：[src/suggest.ts]()
### 5. Download Module (`src/download.ts`)
The Download module handles GitHub repository folder downloads with recursive symlink resolution.
**GitHub Directory Resolution:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `owner` | string | Repository owner |
| `repo` | string | Repository name |
| `ref` | string | Branch, tag, or commit SHA |
| `path` | string | Directory path within repo |
**Download Process:**
```mermaid
graph TD
A[GitHub Folder URL] --> B[Parse Location]
B --> C[Build Contents API URL]
C --> D[Fetch Tree Recursively]
D --> E{Entry Type?}
E -->|tree| F[Add Dir Entry]
E -->|blob| G[Build Raw URL]
G --> H[Add File Entry]
F --> I[Return Entries]
H --> I
```
**URL Construction:**
```typescript
function buildGithubRawUrl(owner: string, repo: string, ref: string, path: string): string
```
The module transforms blob entries into downloadable URLs using `raw.githubusercontent.com`. 资料来源：[src/download.ts]()
### 6. Generate Module (`src/generate.ts`)
The Generate module creates markdown inventory files from GitHub skills directories.
**Discovery Rules:**
| File | Purpose | Output |
|------|---------|--------|
| `SKILL.md` | Skill definitions | `...skills.md` |
| `DESIGN.md` | Design specifications | `...designs.md` |
| Flat markdown files | Agent definitions | `...agents.md` |
**Generation Flow:**
```mermaid
graph TD
A[GitHub URL] --> B[Recursive Tree Listing]
B --> C[Scan for SKILL.md]
B --> D[Scan for DESIGN.md]
C --> E[Collect Assets per Dir]
D --> E
E --> F{File Type?}
F -->|SKILL.md| G[Set skillFileUrl]
F -->|DESIGN.md| H[Set designFileUrl]
F -->|Other| I[Add to Assets]
G --> J[Write Manifest Files]
H --> J
I --> J
J --> K[Skip Empty Outputs]
```
**Asset Collection:**
- Bundled assets are files next to `SKILL.md` or `DESIGN.md`
- Nested subdirectory contents are included
- Symlinks are downloaded when GitHub provides `download_url`
- Repository-relative symlinks are resolved recursively
**Symlink Handling:**
- Symlinks with `download_url` are followed and downloaded
- Directory symlinks are traversed recursively
- Symlinks without `download_url` are skipped
资料来源：[src/generate.ts]()
## Data Models
### GitHub Directory Location
```typescript
interface GithubDirectoryLocation {
owner: string;
repo: string;
ref: string;
path: string;
}
```
### Content Entry
```typescript
interface ContentEntry {
path: string;
download_url: string | null;
type: "file" | "dir";
}
```
### Directory Summary
```typescript
interface DirectorySummary {
skillFileUrl?: string;
designFileUrl?: string;
assets: string[];
}
```
## CLI Mode
### Generate Command
```bash
npx suggest-skills generate \
https://github.com/OWNER/REPO/tree/main/skills
```
**Options:**
- `-r, --recursive`: Scan directories recursively
- `-o, --output `: Output directory (default: `.agents/skills`)
### Server Command
```bash
npx suggest-skills server --port 3100
```
## HTTP Mode
| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/mcp` | POST | MCP tool invocation |
| `/health` | GET | Health check |
**Default Port:** `3100`
## Type Safety
The project uses **Zod** for schema validation at runtime:
- Tool input schemas
- Configuration validation
- Structured output for MCP tools
This ensures type safety beyond compile-time checks. 资料来源：[README.md]()
## Technology Stack
| Component | Technology | Purpose |
|-----------|------------|---------|
| Runtime | Bun | JavaScript runtime with built-in TypeScript support |
| Language | TypeScript | Type-safe JavaScript |
| Protocol | MCP SDK | Model Context Protocol implementation |
| Validation | Zod | Runtime schema validation |
## Summary
The core components follow a layered architecture:
1. **Configuration** manages environment setup and validation
2. **Constants** provide shared values across modules
3. **Utils** offer reusable path and file handling utilities
4. **Suggest** generates skill discovery instructions for agents
5. **Download** handles GitHub repository content retrieval
6. **Generate** creates markdown manifests from skill directories
The separation allows the MCP server to operate in both stdio and HTTP transport modes while sharing core business logic. 资料来源：[src/config.ts](), [src/constants.ts](), [src/utils.ts](), [src/suggest.ts](), [src/download.ts](), [src/generate.ts]()
---
## MCP Tools Reference
### 相关页面
相关主题：[System Architecture](#system-architecture), [Runtime Modes](#runtime-modes)
Relevant Source Files
The following source files were used to generate this documentation page:
- [src/suggest.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/suggest.ts)
- [src/download.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)
- [src/stdio.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/stdio.ts)
- [src/http.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/http.ts)
- [src/config.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)
- [README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
# MCP Tools Reference
This document provides comprehensive documentation for the Model Context Protocol (MCP) tools exposed by the `suggest-skills` server. These tools enable AI agents to dynamically discover, fetch, and download skill manifests and skill assets from GitHub repositories.
## Overview
The MCP Tools Reference documents the three primary tools exposed by the `suggest-skills` MCP server:
| Tool Name | Purpose |
|-----------|---------|
| `suggest_skills` | Generate instruction payloads for skill discovery and comparison |
| `fetch_manifest` | Retrieve and parse skill manifest files from remote URLs |
| `download_skill` | Download skill directories with all bundled assets from GitHub |
These tools follow the MCP specification using the `@modelcontextprotocol/sdk` and leverage `Zod` for runtime schema validation.
资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
## Architecture
### System Components
```mermaid
graph TD
A["CLI / Server Entry"] --> B["Config Module
(config.ts)"]
B --> C["MCP Tool Handlers"]
C --> D["suggest_skills
(suggest.ts)"]
C --> E["fetch_manifest
(suggest.ts)"]
C --> F["download_skill
(download.ts)"]
D --> G["Skill Manifest URLs"]
E --> H["GitHub API / Raw Content"]
F --> H
G --> I["Local Skills Scan"]
H --> J["Downloaded Assets"]
K["Transport Layer"] -->|"stdio"| C
K -->|"HTTP"| L["Streamable HTTP Server
(http.ts)"]
```
### Transport Modes
The MCP server supports two transport mechanisms:
| Transport | Command | Endpoint |
|-----------|---------|----------|
| **stdio** | Default | Standard I/O streams |
| **HTTP** | `server --port ` | `http://localhost:/mcp` |
资料来源：[README.md:58-72](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
## Tool Specifications
### `suggest_skills`
**Purpose:** Generates an instruction payload that guides an AI agent through the skill discovery workflow.
**Input Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `manifestUrl` | string | No | Overrides the default manifest URL from configuration |
**Workflow Steps:**
```mermaid
graph TD
A["Invoke suggest_skills"] --> B{"manifestUrl provided?"}
B -->|Yes| C["Use provided URL"]
B -->|No| D["Read from SUGGEST_SKILLS_MANIFEST_URLS"]
C --> E["Generate instruction payload"]
D --> E
E --> F["Return structured instructions"]
F --> G["Agent: Fetch available skills"]
G --> H["Agent: Scan local skills"]
H --> I["Agent: Compare remote vs local"]
I --> J["Agent: Present suggestions"]
J --> K["Wait for user confirmation"]
K --> L["Agent: Install selected skills"]
```
**Output:** Returns a generated instruction payload containing guidance for:
- Fetching available skills from configured manifests
- Scanning locally installed skills
- Comparing remote and local capabilities
- Presenting suggestions without installing until requested
资料来源：[README.md:48-57](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
### `fetch_manifest`
**Purpose:** Retrieves the raw text content of a skill manifest file from a given URL.
**Input Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `manifestUrl` | string | Yes | The URL of the manifest to fetch |
**Behavior:**
1. Accepts a manifest URL
2. Performs HTTP GET request to the specified URL
3. Returns the raw UTF-8 text content of the manifest
**URL Processing:**
The tool automatically handles GitHub `blob` URLs by converting them to `raw.githubusercontent.com` format:
```
Input: https://github.com/owner/repo/blob/main/skills/manifest.md
Output: https://raw.githubusercontent.com/owner/repo/main/skills/manifest.md
```
资料来源：[README.md:48-57](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
### `download_skill`
**Purpose:** Downloads complete skill directories from GitHub, including all bundled assets.
**Input Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | Yes | GitHub folder URL in format: `https://github.com///tree/[/` |
**Behavior:**
```mermaid
graph TD
A["download_skill URL"] --> B["Parse GitHub URL"]
B --> C["Build Contents API URL"]
B --> D["Fetch Git Tree SHA"]
C --> E["Call GitHub Contents API"]
D --> E
E --> F{"Entry Type"}
F -->|"tree"| G["Create directory entry"]
F -->|"blob"| H["Build raw download URL"]
G --> I["Collect all entries"]
H --> I
I --> J["Return file list with paths and download URLs"]
J --> K["Download all files"]
K --> L["Resolve symlinks recursively"]
L --> M["Save to output directory"]
```
**Return Structure:**
```typescript
{
path: string; // Relative path from requested folder
download_url: string | null; // null for directories
type: "file" | "dir";
}
```
**Special Handling:**
- **File symlinks:** Downloaded when GitHub provides a `download_url`
- **Directory symlinks:** Resolved and downloaded recursively
- **Empty outputs:** Skipped silently, no file written
资料来源：[README.md:48-57](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
资料来源：[src/download.ts:30-60](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)
## Configuration
### Environment Variables
| Variable | Required | Description |
|----------|----------|-------------|
| `SUGGEST_SKILLS_MANIFEST_URLS` | Yes | At least one manifest URL |
| `GITHUB_PAT` | No | Personal Access Token for authenticated GitHub API requests |
**Manifest URL Formats:**
| Format | Example |
|--------|---------|
| JSON array | `["https://example.com/manifest.md"]` |
| Comma-separated | `https://a.com/manifest.md,https://b.com/manifest.md` |
| Newline-separated | `https://a.com/manifest.md\nhttps://b.com/manifest.md` |
资料来源：[README.md:60-73](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
### CLI Options
| Option | Command | Description |
|--------|---------|-------------|
| `-o, --output ` | All | Output directory for installed skills (default: `.agents/skills`) |
| `generate [-r\|--recursive]` | generate | Generate markdown inventories from GitHub |
| `download [-r\|--recursive]` | download | Download skills to current directory |
| `server --port ` | server | Run streamable HTTP server |
资料来源：[src/config.ts:1-30](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)
## Usage Examples
### Stdio Mode
```bash
SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
npx suggest-skills
```
### HTTP Mode
```bash
SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
npx suggest-skills server --port 3100
```
This exposes:
- MCP endpoint: `http://localhost:3100/mcp`
- Health check: `http://localhost:3100/health`
资料来源：[README.md:66-72](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
### Generate Manifests
```bash
npx suggest-skills generate \
https://github.com/OWNER/REPO/tree/main/skills
```
With recursive scanning:
```bash
npx suggest-skills generate \
--recursive \
https://github.com/OWNER/REPO/tree/main/skills
```
**Generated Output Files:**
| File Pattern | Contents |
|--------------|----------|
| `.[.].skills.md` | Entries with `SKILL.md` files |
| `.[.].designs.md` | Entries with `DESIGN.md` files |
| `.[.].agents.md` | Flat top-level markdown with Name/Description columns |
资料来源：[README.md:28-45](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
## Data Models
### GitHub Directory Location
Used internally for parsing and building GitHub URLs:
```typescript
interface GithubDirectoryLocation {
owner: string;
repo: string;
ref: string;
path: string;
}
```
### Content Entry
Returned by the download tool to represent files and directories:
```typescript
interface ContentEntry {
path: string; // Relative path from requested folder
download_url: string | null; // null for directories
type: "file" | "dir";
}
```
### CLI Runtime Mode
Defines the operational mode of the CLI:
```typescript
type CliRuntimeMode =
| { kind: "generate"; url: string; recursive: boolean; config: CliConfig }
| { kind: "download"; url: string; recursive: boolean; config: CliConfig }
| { kind: "server"; port?: number }
| { kind: "stdio"; config: CliConfig };
```
资料来源：[src/config.ts:15-45](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)
资料来源：[src/download.ts:30-60](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)
## Technology Stack
| Component | Purpose |
|-----------|---------|
| **Bun** | JavaScript runtime and package manager |
| **TypeScript** | Type-safe development |
| **@modelcontextprotocol/sdk** | MCP protocol implementation |
| **Zod** | Runtime schema validation |
资料来源：[README.md:75-81](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
## Coding Standards
The MCP tools implementation follows these architectural patterns:
1. **Modular Design:** Small, focused modules with runtime concerns split by file
2. **Explicit Validation:** Configuration errors raised through `ConfigError`
3. **Typed Schemas:** Zod schemas for tool input validation
4. **Structured Output:** Consistent return types for all tools
5. **Minimal Transport:** Clean wrappers around shared server creation
6. **Behavior-Driven Tests:** Focus on observable behavior over implementation details
资料来源：[README.md:83-94](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
---
## CLI Commands
### 相关页面
相关主题：[Environment Variables](#environment-variables), [Manifest Generation](#manifest-generation)
]
相关源码文件
以下源码文件用于生成本页说明：
- [src/config.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)
- [src/cmd_generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/cmd_generate.ts)
- [src/download.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)
- [src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)
- [src/index.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/index.ts)
# CLI Commands
The `suggest-skills` CLI provides a command-line interface for generating skill manifests, downloading skills, and running the MCP server in different modes. The CLI is built using the `cac` (Command And Argument) parser and supports multiple runtime modes that determine how the application executes.
## Architecture Overview
```mermaid
graph TD
A[CLI Entry] --> B[parseCli]
B --> C{Runtime Mode}
C -->|generate| D[onGenerate]
C -->|download| E[onDownload]
C -->|server| F[onServer]
C -->|stdio| G[onStdio]
D --> H[generate.ts]
E --> I[download.ts]
F --> J[MCP Server]
G --> J
```
## Command Structure
The CLI uses `cac` for argument parsing and supports four primary commands. Each command maps to a specific runtime mode that configures how the application processes requests. 资料来源：[src/config.ts:26-54]()
| Command | Description | Arguments |
|---------|-------------|-----------|
| `generate ` | Generate markdown inventories from a GitHub skills directory or repo root | GitHub URL |
| `download ` | Download skills, agents and designs to the current directory | GitHub URL |
| `server [...args]` | Run the streamable HTTP server | Optional arguments |
| `[...args]` | Run in stdio mode (default) | Optional arguments |
## Global Options
| Short | Long | Description | Default |
|-------|------|-------------|---------|
| `-o` | `--output ` | Output directory for installed skills | `.agents/skills` |
| `-r` | `--recursive` | Recursive scan | `false` |
| `--port ` | Port number for HTTP server | `3100` |
## Generate Command
The `generate` command scans a GitHub repository directory and produces markdown inventory files listing available skills, agents, and designs.
### Usage
```bash
npx suggest-skills generate \
https://github.com/OWNER/REPO/tree/main/skills
```
```bash
npx suggest-skills generate \
--recursive \
https://github.com/OWNER/REPO/tree/main/skills
```
### Output Files
The generate command may write the following files in the current working directory:
- `.[.].skills.md` - Entries collected from skill directories containing `SKILL.md`
- `.[.].designs.md` - Entries collected from skill directories containing `DESIGN.md`
- `.[.].agents.md` - Entries collected from flat top-level markdown files with `Name` and `Description` columns
Empty generated outputs are skipped automatically. 资料来源：[README.md:59-75]()
### Discovery Rules
The generate mode uses these rules for discovery:
- GitHub directory discovery uses a recursive tree listing internally
- `SKILL.md` and `DESIGN.md` are discovered in skill directories
- Bundled assets include files next to them or in nested subdirectories
- Symlinks found during generate are not handled specially and may appear in bundled assets 资料来源：[README.md:77-81]()
### Markdown Table Formatting
The `cmd_generate.ts` module handles formatting of generated markdown tables with special character escaping.
```typescript
function escapeTableCell(value: string): string {
return value.replaceAll("|", "\\|").replaceAll("\n", " ");
}
```
#### Empty Document Detection
Generated documents that contain only headers without any data rows are considered empty:
```typescript
function isEmptyGeneratedDocument(document: GeneratedDocument): boolean {
return document.markdown === "| Name | Description |\n| -----|-------------|\n"
|| document.markdown === "| Name | Description | Bundled Assets |\n| -----|-------------|----------------|\n";
}
```
#### Bundled Assets Formatting
Assets are formatted inline when the count is below the threshold, otherwise summarized. 资料来源：[src/cmd_generate.ts:1-50]()
## Download Command
The `download` command retrieves all files from a GitHub folder, including skills, agents, and designs.
### Usage
```bash
npx suggest-skills download \
https://github.com///tree/[/
```
### GitHub API Integration
The download functionality builds GitHub API URLs dynamically:
#### Contents API URL
```typescript
function buildContentsApiUrl(location: GithubDirectoryLocation): string {
const pathSuffix = location.path
.split("/")
.filter(Boolean)
.map((part) => encodeURIComponent(part))
.join("/");
const pathname = pathSuffix
? `/repos/${encodeURIComponent(location.owner)}/${encodeURIComponent(location.repo)}/contents/${pathSuffix}`
: `/repos/${encodeURIComponent(location.owner)}/${encodeURIComponent(location.repo)}/contents`;
const url = new URL(pathname, GITHUB_API_BASE_URL);
url.searchParams.set("ref", location.ref);
return url.toString();
}
```
#### Tree API URL
For recursive operations, the tree API provides efficient directory traversal:
```typescript
function buildTreeApiUrl(owner: string, repo: string, treeSha: string): string {
const pathname = `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/git/trees/${encodeURIComponent(treeSha)}`;
const url = new URL(pathname, GITHUB_API_BASE_URL);
url.searchParams.set("recursive", "1");
return url.toString();
}
```
#### Raw URL Construction
```typescript
function buildGithubRawUrl(owner: string, repo: string, ref: string, path: string): string {
// Returns raw.githubusercontent.com URL for file downloads
}
```
资料来源：[src/download.ts:1-80]()
## Server Command
Runs the streamable HTTP server for MCP tool access.
### Usage
```bash
npx suggest-skills server --port 3100
```
### Endpoints
| Endpoint | Description |
|----------|-------------|
| `http://localhost:3100/mcp` | MCP tool endpoint |
| `http://localhost:3100/health` | Health check |
## Stdio Mode
Default mode where the MCP server communicates via standard input/output.
### Usage
```bash
SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
npx suggest-skills
```
## Runtime Mode Types
The CLI parses commands into structured runtime modes:
```typescript
type CliRuntimeMode =
| { kind: "generate"; url: string; recursive: boolean; config: ... }
| { kind: "download"; url: string; recursive: boolean; config: ... }
| { kind: "server"; port?: number; config: ... }
| { kind: "stdio"; config: ... };
```
资料来源：[src/config.ts:56-75]()
## Configuration
CLI runtime modes incorporate configuration from environment variables:
| Variable | Required | Description |
|----------|----------|-------------|
| `GITHUB_PAT` | Optional | Authentication token for GitHub API |
| `SUGGEST_SKILLS_MANIFEST_URLS` | Required | Manifest URLs (JSON array, comma-separated, or newline-separated) |
GitHub `blob` URLs are converted to `raw.githubusercontent.com` URLs automatically. 资料来源：[README.md:83-97]()
## CLI Parsing Flow
```mermaid
sequenceDiagram
participant User
participant CLI as parseCli()
participant CAC
participant Actions
User->>CLI: process.argv
CLI->>CAC: Create cac instance
CAC->>Actions: Register commands
Actions->>CAC: Define onGenerate/onDownload/onServer/onStdio
User->>CAC: Run command
CAC->>Actions: Call matching action
Actions->>CLI: Return CliRuntimeMode
CLI->>User: Execute with mode
```
## Entry Point
The main entry point is `src/index.ts` which initializes the CLI and handles the selected runtime mode. The `parseCli()` function is called with `process.argv` and `process.env` to determine the appropriate execution path. 资料来源：[src/index.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/index.ts)()
## Default Output Directory
The default output directory for installed skills is `.agents/skills` when using the `-o` or `--output` option. 资料来源：[src/config.ts:30]()
## Summary
The `suggest-skills` CLI provides four distinct commands for different use cases:
1. **generate** - Create markdown inventories from GitHub skill repositories
2. **download** - Fetch skill files from GitHub to local storage
3. **server** - Run as HTTP MCP server
4. **stdio** - Run as stdio-based MCP server (default)
All commands share common options for output directory specification and recursive processing, making the CLI flexible for both one-time operations and automated workflows.
---
## Environment Variables
### 相关页面
相关主题：[CLI Commands](#cli-commands), [Runtime Modes](#runtime-modes)
]
相关源码文件
以下源码文件用于生成本页说明：
- [src/config.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)
- [README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
- [src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)
- [src/download.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)
- [src/server.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/server.ts) (implied)
# Environment Variables
The suggest-skills project uses environment variables for configuration management, enabling flexible deployment across different execution contexts (CLI, MCP server modes). Configuration is centralized in `src/config.ts` with explicit validation through `ConfigError` to ensure required variables are properly set before runtime.
## Overview
Environment variables in suggest-skills serve two primary purposes:
1. **Authentication**: Enable authenticated GitHub API requests for higher rate limits
2. **Manifest Configuration**: Define which skill manifests the agent should reference
资料来源：[README.md]()
```mermaid
graph TD
A[Application Start] --> B{Validate Config}
B -->|Missing SUGGEST_SKILLS_MANIFEST_URLS| C[Throw ConfigError]
B -->|Valid Config| D[Load Manifest URLs]
D --> E{Optional GITHUB_PAT?}
E -->|Yes| F[Enable Authenticated Requests]
E -->|No| G[Use Anonymous Requests]
F --> H[Register MCP Tools]
G --> H
```
## Configuration Variables
### Required Variables
| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `SUGGEST_SKILLS_MANIFEST_URLS` | URLs pointing to skill manifest markdown files | **Yes** | None |
The `SUGGEST_SKILLS_MANIFEST_URLS` variable is validated at startup. If omitted, the application throws a `ConfigError` and terminates. This ensures the agent always has at least one manifest to reference for skill suggestions.
资料来源：[README.md]()
### Supported Format Types
The `SUGGEST_SKILLS_MANIFEST_URLS` variable accepts multiple input formats:
| Format Type | Example |
|-------------|---------|
| JSON Array | `["https://example.com/manifest.md"]` |
| Comma-separated String | `https://a.com/manifest.md,https://b.com/manifest.md` |
| Newline-separated String | `https://a.com/manifest.md`
`https://b.com/manifest.md` |
The configuration loader automatically parses any of these formats, normalizing them into an internal array for manifest fetching operations.
资料来源：[README.md]()
### Optional Variables
| Variable | Description | Purpose |
|----------|-------------|---------|
| `GITHUB_PAT` | GitHub Personal Access Token | Authenticated requests to `api.github.com` with higher rate limits |
When `GITHUB_PAT` is provided, all GitHub API calls use Bearer token authentication. Without it, requests are made anonymously, which may encounter stricter rate limiting from GitHub.
资料来源：[README.md]()
## URL Processing
### GitHub Blob URL Conversion
The system automatically converts GitHub `blob` URLs to `raw.githubusercontent.com` format for content retrieval:
```
Input: https://github.com/owner/repo/blob/main/skills/manifest.md
Output: https://raw.githubusercontent.com/owner/repo/main/skills/manifest.md
```
资料来源：[README.md]()
This conversion happens during manifest URL validation, ensuring consistent URL handling throughout the codebase regardless of how users reference GitHub-hosted manifests.
```mermaid
graph LR
A[Manifest URL Input] --> B{Is GitHub Blob URL?}
B -->|Yes| C[Extract Owner/Repo/Ref/Path]
C --> D[Build Raw URL]
B -->|No| E[Use as-is]
D --> F[Fetch Content]
E --> F
```
## CLI Usage Patterns
### Stdio Mode (Default MCP)
```bash
SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
npx suggest-skills
```
资料来源：[README.md]()
### HTTP Server Mode
```bash
SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
npx suggest-skills server --port 3100
```
The HTTP endpoint is served at `http://localhost:3100/mcp` with health check at `http://localhost:3100/health`.
资料来源：[README.md]()
### Generate Mode with Authentication
```bash
GITHUB_PAT=ghp_xxx \
SUGGEST_SKILLS_MANIFEST_URLS='["https://github.com/org/repo/skills/manifest.md"]' \
npx suggest-skills generate \
--recursive \
https://github.com/OWNER/REPO/tree/main/skills
```
When generating manifests recursively, authenticated requests improve reliability when traversing large repository trees.
## Configuration Validation
The configuration module implements explicit validation with descriptive error messages:
```typescript
// Conceptual validation flow from src/config.ts
function validateConfig(): void {
const manifestUrls = process.env.SUGGEST_SKILLS_MANIFEST_URLS;
if (!manifestUrls || manifestUrls.trim() === "") {
throw new ConfigError(
"SUGGEST_SKILLS_MANIFEST_URLS is required and must contain at least one URL"
);
}
// Parse and normalize URL formats...
}
```
资料来源：[src/config.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)
## Configuration Override Mechanism
### MCP Tool Override
The `suggest_skills` MCP tool accepts an optional `manifestUrl` parameter that overwrites the configured `SUGGEST_SKILLS_MANIFEST_URLS` at runtime:
| Parameter | Type | Description |
|-----------|------|-------------|
| `manifestUrl` | string (optional) | Single manifest URL to use instead of configured defaults |
资料来源：[README.md]()
This allows agents to dynamically reference different manifest sources without modifying environment configuration.
## Architecture Summary
```mermaid
graph TD
subgraph "Configuration Layer"
A[Environment Variables] --> B[config.ts]
B --> C{ConfigError?}
end
subgraph "Manifest Processing"
C -->|Valid| D[Parse Manifest URLs]
D --> E[Normalize GitHub Blob URLs]
E --> F[Fetch Manifest Content]
F --> G[fetch_manifest Tool]
end
subgraph "Tool Registration"
G --> H[suggest_skills]
H --> I[MCP Server]
end
subgraph "GitHub API Integration"
A -->|GITHUB_PAT| J[Authenticated Client]
J --> K[download_skill Tool]
end
```
## Best Practices
1. **Always set `SUGGEST_SKILLS_MANIFEST_URLS`** before launching the application
2. **Use `GITHUB_PAT`** for production deployments to avoid rate limiting
3. **Validate URL accessibility** before deploying manifest configurations
4. **Use JSON array format** for multiple URLs when shell quoting is not a concern
## Error Handling
| Error Condition | Cause | Resolution |
|-----------------|-------|------------|
| Missing manifest URLs | `SUGGEST_SKILLS_MANIFEST_URLS` not set | Set the variable with at least one URL |
| Invalid URL format | Malformed URL in manifest list | Verify all URLs are properly formatted |
| Rate limit exceeded | Anonymous requests hitting GitHub limits | Add `GITHUB_PAT` for authenticated access |
---
## Bundled Skills Reference
### 相关页面
相关主题：[Manifest Generation](#manifest-generation), [MCP Tools Reference](#mcp-tools-reference)
相关源码文件
以下源码文件用于生成本页说明：
- [official/skills/ALL.md](https://github.com/sator-imaging/suggest-skills/blob/main/official/skills/ALL.md)
- [community/skills/ALL.md](https://github.com/sator-imaging/suggest-skills/blob/main/community/skills/ALL.md)
- [official/skills/anthropics.skills.md](https://github.com/sator-imaging/suggest-skills/blob/main/official/skills/anthropics.skills.md)
- [official/skills/openai.skills.skills.md](https://github.com/sator-imaging/suggest-skills/blob/main/official/skills/openai.skills.skills.md)
- [official/skills/google-labs-code.stitch-skills.md](https://github.com/sator-imaging/suggest-skills/blob/main/official/skills/google-labs-code.stitch-skills.md)
- [community/skills/ComposioHQ.awesome-claude-skills.md](https://github.com/sator-imaging/suggest-skills/blob/main/community/skills/ComposioHQ.awesome-claude-skills.md)
# Bundled Skills Reference
## Overview
Bundled Skills Reference is a curated collection of prebuilt skill manifests available within the `suggest-skills` repository. These manifests provide machine-readable inventories of skills, agents, and designs that can be consumed by MCP (Model Context Protocol) clients. The reference aggregates skill definitions from multiple upstream sources including official repositories (Anthropic, OpenAI, Google Labs) and community-contributed collections.
资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
## Architecture
### Skill Manifest Structure
Each bundled manifest follows a structured format containing skill entries with metadata and file references:
```mermaid
graph TD
A[Manifest URL] --> B[Skill Entry]
B --> C[Name]
B --> D[Description]
B --> E[Trigger Keywords]
B --> F[Bundled Files]
F --> G[SKILL.md]
F --> H[DESIGN.md]
F --> I[agents/*.yaml]
F --> J[assets/*]
F --> K[references/*]
F --> L[scripts/*]
```
资料来源：[official/skills/ALL.md](https://github.com/sator-imaging/suggest-skills/blob/main/official/skills/ALL.md)
### Repository Organization
```mermaid
graph LR
A[suggest-skills repo] --> B[official/skills/]
A --> C[community/skills/]
B --> D[anthropics.skills.md]
B --> E[openai.skills.skills.md]
B --> F[google-labs-code.stitch-skills.md]
C --> G[ComposioHQ.*.md]
C --> H[obra.superpowers.skills.md]
```
## Official Skills
### Anthropic Skills
The Anthropic skills collection provides capabilities for common AI assistant workflows.
| Skill Name | Description | Bundled Assets |
|------------|-------------|----------------|
| `doc-coauthoring` | Guide users through structured documentation co-authoring workflows | None |
| `docx` | Create, read, edit Word documents (.docx) | editing.md, pptxgenjs.md, scripts (4 files) |
| `pdf` | PDF manipulation including reading, merging, splitting, watermarking | forms.md, reference.md, scripts (8 files) |
| `pptx` | Slide deck creation and manipulation | editing.md, pptxgenjs.md, scripts (4 files) |
| `skill-creator` | Create and optimize skills, run evaluations | agents (3 files), eval-viewer (2 files), scripts (9 files) |
| `slack-gif-creator` | Create animated GIFs optimized for Slack | reference (4 files), scripts (4 files) |
资料来源：[official/skills/anthropics.skills.md](https://github.com/sator-imaging/suggest-skills/blob/main/official/skills/anthropics.skills.md)
### OpenAI Skills
The OpenAI skills collection focuses on integration with OpenAI platforms and Codex.
| Skill Name | Description | Bundled Assets |
|------------|-------------|----------------|
| `codex` | Research and answer questions about OpenAI models and APIs | agents/openai.yaml, references (3 files), scripts |
| `figma` | Fetch design context via Figma MCP server | LICENSE.TXT, agents/openai.yaml, assets (3 files), references (7 files) |
| `figma-implement-design` | Translate Figma designs into production code | LICENSE.txt, agents/openai.yaml, assets (3 files) |
| `jupyter-notebook` | Create and edit Jupyter notebooks (.ipynb) | agents/openai.yaml, assets (4 files), scripts/new_notebook.py |
| `linear` | Manage issues and projects in Linear | LICENSE.txt, agents/openai.yaml, assets (2 files) |
| `netlify-deploy` | Deploy to Netlify cloud platform | agents/openai.yaml, assets (2 files), references (3 files) |
| `notion-*` | Various Notion integrations (capture, meeting, research, spec) | agents/openai.yaml, assets, evaluations, examples, reference |
| `pdf` | PDF reading and creation with visual rendering | agents/openai.yaml, assets/pdf.png |
| `playwright` | Automate real browser interactions | agents/openai.yaml, references (2 files), scripts |
| `render-deploy` | Deploy to Render platform | agents/openai.yaml, assets (8 files), references (10 files) |
| `vercel-deploy` | Deploy to Vercel platform | agents/openai.yaml, assets (2 files), scripts/deploy.sh |
资料来源：[official/skills/openai.skills.skills.md](https://github.com/sator-imaging/suggest-skills/blob/main/official/skills/openai.skills.skills.md)
### Google Labs Code Stitch Skills
The Stitch skills collection provides UI/UX design integration capabilities.
| Skill Name | Description | Bundled Assets |
|------------|-------------|----------------|
| `shadcn-ui` | Integration guidance for shadcn/ui components | README.md, examples (3 files), resources (4 files) |
| `stitch-design` | Unified entry for Stitch design work with design system synthesis | README.md, references (3 files), workflows (3 files) |
| `stitch-loop` | Autonomous baton-passing loop for iterative website building | README.md, examples (2 files), resources (2 files) |
| `taste-design` | Semantic Design System with premium UI standards | README.md, examples (2 files), resources (2 files) |
资料来源：[official/skills/google-labs-code.stitch-skills.md](https://github.com/sator-imaging/suggest-skills/blob/main/official/skills/google-labs-code.stitch-skills.md)
## Community Skills
### ComposioHQ Awesome-Claude-Skills
A collection of community-contributed skills for various use cases.
| Skill Name | Description | Bundled Assets |
|------------|-------------|----------------|
| `theme-factory` | Toolkit for styling artifacts with pre-set themes | LICENSE.txt, theme-showcase.pdf, themes (10 files) |
| `twitter-algorithm-optimizer` | Analyze and optimize tweets for maximum reach | None |
| `youtube-downloader` | Download YouTube videos with quality/format options | scripts/download_video.py |
| `webapp-testing` | Interact with and test web applications using Playwright | None |
资料来源：[community/skills/ComposioHQ.awesome-claude-skills.md](https://github.com/sator-imaging/suggest-skills/blob/main/community/skills/ComposioHQ.awesome-claude-skills.md)
### OBRA Superpowers
Skills focused on improving agent capabilities for writing and planning.
| Skill Name | Trigger Condition | Bundled Assets |
|------------|-------------------|----------------|
| `writing-plans` | Spec or requirements for multi-step task | plan-document-reviewer-prompt.md |
| `writing-skills` | Creating or editing skills | anthropic-best-practices.md, graphviz-conventions.dot, persuasion-principles.md, render-graphs.js, testing-skills-with-subagents.md |
资料来源：[community/skills/obra.superpowers.skills.md](https://github.com/sator-imaging/suggest-skills/blob/main/community/skills/obra.superpowers.skills.md)
## Skill Directory Structure
Each skill directory follows a consistent file organization pattern:
```
skill-name/
├── SKILL.md # Required: Main skill definition
├── DESIGN.md # Optional: Design specifications
├── LICENSE.txt # License file
├── agents/ # Agent configuration files
│ └── openai.yaml # Agent definitions with Name/Description
├── assets/ # Static assets (images, templates)
│ ├── icon.png
│ └── preview.png
├── references/ # Reference documentation
│ ├── api.md
│ └── guide.md
├── scripts/ # Helper scripts
│ └── helper.sh
└── evaluations/ # Evaluation/test data (optional)
└── test-cases.yaml
```
资料来源：[official/skills/ALL.md](https://github.com/sator-imaging/suggest-skills/blob/main/official/skills/ALL.md)
## MCP Tools Integration
### suggest_skills
Returns a generated instruction payload that tells an agent how to fetch, scan, and compare skills.
```typescript
interface SuggestSkillsParams {
manifestUrl?: string; // Optional: overwrite default manifest URLs
}
```
### fetch_manifest
Retrieves raw manifest content from a configured URL.
```typescript
interface FetchManifestParams {
manifestUrl: string; // Required: URL of the skill manifest
}
```
### download_skill
Downloads all files from a GitHub folder URL.
```typescript
interface DownloadSkillParams {
folderUrl: string; // Format: https://github.com/{owner}/{repo}/tree/{ref}/{path}
}
```
Returns files with:
- Path relative to the requested folder
- UTF-8 text content
- Resolved symlinks when GitHub provides download_url
资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
## Configuration
### Environment Variables
| Variable | Required | Description |
|----------|----------|-------------|
| `SUGGEST_SKILLS_MANIFEST_URLS` | Yes | Comma-separated, newline-separated, or JSON array of manifest URLs |
| `GITHUB_PAT` | No | Personal Access Token for authenticated GitHub API requests |
### Manifest URL Formats
Accepted formats for `SUGGEST_SKILLS_MANIFEST_URLS`:
```json
["https://some/skill-manifest.md"]
```
```
https://some/skill-manifest.md,https://other/skill-manifest.md
```
```
https://some/skill-manifest.md
https://other/skill-manifest.md
```
GitHub `blob` URLs are automatically converted to `raw.githubusercontent.com` URLs.
## Usage Modes
### stdio Mode
```bash
SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
npx suggest-skills
```
### HTTP Mode
```bash
SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
npx suggest-skills server --port 3100
```
| Endpoint | Purpose |
|----------|---------|
| `http://localhost:3100/mcp` | MCP protocol endpoint |
| `http://localhost:3100/health` | Health check endpoint |
### Generate Mode
```bash
npx suggest-skills generate \
https://github.com/OWNER/REPO/tree/main/skills
```
Generates markdown inventories:
- `.[.].skills.md` - entries from skill directories with `SKILL.md`
- `.[.].designs.md` - entries from skill directories with `DESIGN.md`
- `.[.].agents.md` - entries from flat markdown files with Name/Description columns
资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
## Technology Stack
| Component | Technology |
|-----------|------------|
| Runtime | Bun |
| Language | TypeScript |
| Protocol SDK | @modelcontextprotocol/sdk |
| Validation | Zod |
## Workflow Diagram
```mermaid
graph TD
A[Configure manifest URLs] --> B[Start suggest-skills]
B --> C{Transport Mode}
C -->|stdio| D[Read from stdin/stdout]
C -->|HTTP| E[Start HTTP server on port 3100]
D --> F[MCP Tool: suggest_skills]
E --> F
F --> G[Fetch skill manifests]
G --> H[Compare with local skills]
H --> I[Present skill suggestions]
I --> J[User requests skill installation]
J --> K[MCP Tool: download_skill]
K --> L[Download skill folder from GitHub]
L --> M[Save to .agents/skills/]
```
## Key Design Patterns
1. **Manifest-driven discovery**: Skills are discovered through manifest URLs rather than hardcoded lists
2. **Bundled asset support**: Each skill can include scripts, references, and assets alongside definitions
3. **Symlink resolution**: Repository symlinks are automatically resolved during download
4. **Lazy installation**: Skills are suggested but not installed until explicitly requested
资料来源：[README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
---
## Manifest Generation
### 相关页面
相关主题：[CLI Commands](#cli-commands), [Bundled Skills Reference](#bundled-skills)
相关源码文件
以下源码文件用于生成本页说明：
- [src/generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/generate.ts)
- [src/cmd_generate.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/cmd_generate.ts)
- [src/download.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/download.ts)
- [src/config.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)
- [README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
# Manifest Generation
## Overview
Manifest Generation is the core feature of `suggest-skills` that scans GitHub repositories containing skill definitions and produces structured markdown inventory files. These inventories capture available skills, designs, and agents from a repository, enabling the MCP server to provide intelligent skill suggestions to users.
The generation process discovers skill artifacts by traversing GitHub directory trees, identifying files matching specific naming conventions (`SKILL.md`, `DESIGN.md`, or agent definition files), and bundling associated assets.
资料来源：[README.md:1-100]()
## Architecture
```mermaid
graph TD
A[CLI: npx suggest-skills generate] --> B[cmd_generate.ts]
B --> C[Parse GitHub URL]
C --> D[Fetch Git Tree Recursively]
D --> E[download.ts: fetchGitTree]
E --> F[Generate.ts: scanDirectoryTree]
F --> G{File Type?}
G -->|SKILL.md| H[Mark as Skill Directory]
G -->|DESIGN.md| I[Mark as Design Directory]
G -->|agents.md format| J[Mark as Agent Definition]
G -->|Other files| K[Bundle as Asset]
H --> L[Build Skills Manifest]
I --> M[Build Designs Manifest]
J --> N[Build Agents Manifest]
K --> L
K --> M
L --> O[..skills.md]
M --> P[..designs.md]
N --> Q[..agents.md]
```
## CLI Usage
### Basic Generation
```bash
npx suggest-skills generate \
https://github.com/OWNER/REPO/tree/main/skills
```
### Recursive Generation
```bash
npx suggest-skills generate \
--recursive \
https://github.com/OWNER/REPO/tree/main/skills
```
### Output Directory
```bash
npx suggest-skills generate \
-o ./my-skills \
https://github.com/OWNER/REPO/tree/main/skills
```
| Option | Short | Description |
|--------|-------|-------------|
| `--output ` | `-o` | Output directory for generated manifests |
| `--recursive` | `-r` | Enable recursive subdirectory scanning |
资料来源：[README.md:70-90]()
## Output File Types
The generate command produces three types of manifest files based on discovery rules:
### Skills Manifest
**File naming:** `.[.].skills.md`
Contains entries from skill directories that contain a `SKILL.md` file. Each entry includes:
- Skill name
- GitHub URL
- Description
- Associated assets (files bundled with the skill)
### Designs Manifest
**File naming:** `.[.].designs.md`
Contains entries from directories that contain a `DESIGN.md` file. Supports optional YAML front matter for `name` and `description` fields.
```yaml
---
name: My Design
description: Design system for the project
---
```
When description is missing from front matter, the manifest outputs `None`.
资料来源：[README.md:85-100]()
### Agents Manifest
**File naming:** `.[.].agents.md`
Contains flat top-level markdown files with `Name` and `Description` columns. Files must use front matter format:
```yaml
---
Name: Agent Name
Description: What this agent does
---
```
## Discovery Rules
### Recursive vs Non-Recursive Scanning
| Mode | Behavior |
|------|----------|
| **Without `--recursive`** | Scans direct child directories of the generate root for `SKILL.md` and `DESIGN.md` |
| **With `--recursive`** | Expands subdirectory search; nested directories at any depth are scanned for `SKILL.md` and `DESIGN.md` |
In both modes, root-level markdown files for `.agents.md` are discovered identically.
资料来源：[README.md:101-120]()
### Asset Bundling
Bundled assets are collected based on proximity:
```mermaid
graph LR
A[SKILL.md] --> B[Same Directory Files]
A --> C[Nested Subdirectories]
B --> D[Included as Assets]
C --> D
```
- **Same directory files**: All files co-located with `SKILL.md` or `DESIGN.md`
- **Nested subdirectories**: Files within subdirectories of the skill/design root
- **Ignored patterns**: Generated files matching ignore rules are excluded
### Symlink Handling
Symlinks found during generation are not handled specially:
- They may appear in bundled assets
- They are not traversed recursively
- Repository-relative directory symlinks are resolved and downloaded when GitHub provides a `download_url`
资料来源：[README.md:115-130]()
### Output File Naming
Output files are normalized to remove redundant type suffixes:
| Input Path | Output File |
|------------|-------------|
| `skills` | `owner.repo.skills.md` |
| `some-skills` | `some-skills.md` (not `some-skills.skills.skills.md`) |
Empty generated outputs are skipped, meaning no file is written and no overwrite prompt is shown for them.
资料来源：[README.md:121-130]()
## Source Code Components
### generate.ts
The core generation module handles:
1. **Directory Tree Scanning** (`scanDirectoryTree`)
- Processes GitHub tree entries
- Identifies immediate child directories
- Categorizes files by type
2. **Summary Construction**
- Builds directory summaries with asset lists
- Links `SKILL.md` and `DESIGN.md` URLs
- Tracks nested candidate directories
3. **Candidate Directory Resolution**
- Determines which directories contain discoverable artifacts
- Filters based on recursion mode
```typescript
// Key function signature
function scanDirectoryTree(
rootPath: string,
tree: GitTreeEntry[],
summariesByDirectory: Map
): {
immediateEntries: Map;
nestedCandidateDirectories: Set;
}
```
资料来源：[src/generate.ts:1-80]()
### cmd_generate.ts
Handles the command-line invocation for generation mode:
1. Validates the GitHub URL
2. Normalizes URLs (blob URLs → raw content)
3. Orchestrates the fetch-and-generate workflow
4. Writes output files to the configured directory
### download.ts
Provides GitHub API integration for tree fetching:
```typescript
async function fetchGitTree(
location: GithubDirectoryLocation
): Promise
```
The function:
- Fetches the Git tree recursively via GitHub API
- Builds raw download URLs for blob entries
- Returns unified `ContentEntry[]` for directory and file nodes
资料来源：[src/download.ts:1-60]()
### config.ts
Defines CLI configuration for the generate command:
```typescript
cli
.command("generate ", "Generate markdown inventories from a GitHub skills directory or repo root")
.option("-r, --recursive", "Recursive scan")
.action(actions.onGenerate);
```
资料来源：[src/config.ts:1-50]()
## Configuration
### Environment Variables
| Variable | Required | Description |
|----------|----------|-------------|
| `GITHUB_PAT` | No | Personal Access Token for authenticated GitHub API requests |
| `SUGGEST_SKILLS_MANIFEST_URLS` | Yes | At least one manifest URL (for stdio/HTTP modes) |
### Accepted URL Formats for SUGGEST_SKILLS_MANIFEST_URLS
- JSON array: `["https://some/skill-manifest.md"]`
- Comma-separated string: `https://first/manifest.md,https://second/manifest.md`
- Newline-separated string
### URL Normalization
GitHub `blob` URLs are automatically converted to `raw.githubusercontent.com` URLs:
```
https://github.com/owner/repo/blob/main/path/file.md
↓
https://raw.githubusercontent.com/owner/repo/main/path/file.md
```
资料来源：[README.md:135-155]()
## GitHub API Integration
### Tree Fetching Strategy
The generation process uses the GitHub Contents API internally:
```mermaid
sequenceDiagram
participant CLI as suggest-skills
participant GitHub as GitHub API
participant Output as .skills.md/.designs.md/.agents.md
CLI->>GitHub: GET /repos/{owner}/{repo}/git/trees/{sha}?recursive=1
GitHub-->>CLI: Full tree structure
CLI->>CLI: Filter by file naming rules
CLI->>Output: Write manifest files
```
### API Rate Limiting
- Unauthenticated requests: 60 requests/hour
- Authenticated requests (`GITHUB_PAT`): 5,000 requests/hour
资料来源：[src/download.ts:40-60]()
## Example Workflow
Given a repository structure:
```
skills/
├── api-docs/
│ ├── SKILL.md
│ ├── README.md
│ └── examples/
│ └── example.py
├── ui-components/
│ ├── SKILL.md
│ └── references/
│ └── guide.md
└── agents/
├── openai.yaml
└── linear.yaml
```
### Non-Recursive Output (`skills.skills.md`)
```markdown
| Skill | Description | URL | Assets |
|-------|-------------|-----|--------|
| api-docs | Guide for API docs | ... | README.md, examples/ |
| ui-components | UI component library | ... | references/ |
```
### Recursive Output (`skills.skills.md`)
Adds nested directory discoveries; subdirectories at any depth containing `SKILL.md` are included.
## Error Handling
| Scenario | Behavior |
|----------|----------|
| Empty discovery results | No file written; no overwrite prompt |
| Invalid GitHub URL | Error message with usage instructions |
| API rate limit exceeded | Retry with exponential backoff (if `GITHUB_PAT` set) |
| Network failure | Propagate error with context |
| Missing required manifest URLs | Validation error on startup |
## Best Practices
1. **Use descriptive front matter**: Add `name` and `description` to `DESIGN.md` files
2. **Co-locate assets**: Keep supporting files next to `SKILL.md` for automatic bundling
3. **Avoid redundant naming**: Use paths like `skills` instead of `skills-skills`
4. **Set up GITHUB_PAT**: For repositories with frequent updates or large skill collections
5. **Use recursive mode strategically**: Enable only when nested skill structures exist
---
## Runtime Modes
### 相关页面
相关主题：[Installation and Quick Start](#installation), [MCP Tools Reference](#mcp-tools-reference)
相关源码文件
以下源码文件用于生成本页说明：
- [src/config.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)
- [src/stdio.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/stdio.ts)
- [src/http.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/http.ts)
- [src/index.ts](https://github.com/sator-imaging/suggest-skills/blob/main/src/index.ts)
- [README.md](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
# Runtime Modes
The `suggest-skills` project supports multiple runtime modes to accommodate different integration scenarios. The architecture separates concerns between CLI operations, MCP tool registration, and transport mechanisms, enabling flexible deployment options.
## Overview
Runtime modes define how the application starts, processes requests, and communicates with external systems. The project implements a unified configuration system that branches into distinct operational modes based on CLI arguments and environment variables.
```mermaid
graph TD
A[CLI Entry Point] --> B{parseCli}
B --> C[stdio Mode]
B --> D[HTTP Server Mode]
B --> E[Generate Mode]
B --> F[Download Mode]
C --> G[MCP Tools]
D --> H[HTTP Transport]
E --> I[File Output]
F --> J[Download Output]
```
资料来源：[src/config.ts:1-80](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)
## Available Runtime Modes
| Mode | Command | Purpose |
|------|---------|---------|
| **stdio** | `npx suggest-skills` (default) | Interactive stdio communication with Claude |
| **HTTP** | `npx suggest-skills server --port ` | Streamable HTTP server with MCP endpoint |
| **generate** | `npx suggest-skills generate ` | Generate markdown inventories from GitHub |
| **download** | `npx suggest-skills download ` | Download skills to local directory |
资料来源：[README.md:1-100](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
## CLI Runtime Mode Structure
The CLI parsing layer creates a typed runtime mode union that drives all subsequent behavior:
```typescript
type CliRuntimeMode =
| { kind: "stdio"; config: Config }
| { kind: "generate"; url: string; recursive: boolean; config: Config }
| { kind: "download"; url: string; recursive: boolean; config: Config }
| { kind: "server"; port?: number; config: Config };
```
资料来源：[src/config.ts:20-40](https://github.com/sator-imaging/suggest-skills/blob/main/src/config.ts)
### Configuration Sources
Runtime modes inherit configuration from two environment variables:
| Variable | Required | Format | Description |
|----------|----------|--------|-------------|
| `SUGGEST_SKILLS_MANIFEST_URLS` | Yes | JSON array, comma-separated, or newline-separated | URLs pointing to skill manifest files |
| `GITHUB_PAT` | No | String | Personal Access Token for authenticated GitHub API requests |
资料来源：[README.md:100-120](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
## Stdio Mode
Stdio mode enables the MCP server to communicate via standard input/output streams, making it suitable for direct integration with Claude Desktop or similar tools that spawn subprocesses.
```mermaid
graph LR
A[Claude Agent] -->|stdin| B[suggest-skills]
B -->|stdout| A
B --> C[MCP Tools]
C --> D[suggest_skills]
C --> E[fetch_manifest]
C --> F[download_skill]
```
### Usage
```bash
SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
npx suggest-skills
```
### MCP Tools Available
The stdio mode exposes three MCP tools:
| Tool | Parameters | Return Type | Purpose |
|------|------------|-------------|---------|
| `suggest_skills` | `manifestUrl?` | Instruction payload | Fetches and presents skill suggestions |
| `fetch_manifest` | `manifestUrl` | string | Returns raw manifest text content |
| `download_skill` | `githubUrl` | File array | Downloads entire skill folders from GitHub |
资料来源：[README.md:120-160](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
## HTTP Server Mode
HTTP mode runs a persistent server that exposes the MCP protocol over HTTP, allowing remote clients to access tools via RESTful endpoints.
### Usage
```bash
SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
npx suggest-skills server --port 3100
```
### Endpoints
| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/mcp` | POST | MCP protocol endpoint for tool invocations |
| `/health` | GET | Health check endpoint for monitoring |
```mermaid
graph TD
A[HTTP Client] -->|POST /mcp| B[MCP Server]
A -->|GET /health| B
B --> C[Tool Registration]
C --> D[suggest_skills]
C --> E[fetch_manifest]
C --> F[download_skill]
```
资料来源：[README.md:160-180](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
## Generate Mode
Generate mode scans GitHub repositories and produces markdown inventory files without installing anything locally.
### Usage
```bash
npx suggest-skills generate \
https://github.com/OWNER/REPO/tree/main/skills
```
### Recursive Scanning
```bash
npx suggest-skills generate \
--recursive \
https://github.com/OWNER/REPO/tree/main/skills
```
### Output Files
| File Pattern | Content |
|--------------|---------|
| `.[.].skills.md` | Entries from directories containing `SKILL.md` |
| `.[.].designs.md` | Entries from directories containing `DESIGN.md` |
| `.[.].agents.md` | Flat markdown files with Name/Description columns |
资料来源：[README.md:60-90](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
## Download Mode
Download mode fetches skill directories and saves them locally for offline use.
### Usage
```bash
npx suggest-skills download \
https://github.com///tree/[/
```
### File Handling
- Symlinks are downloaded when GitHub provides a `download_url`
- Repository-relative directory symlinks are resolved and downloaded recursively
- Empty generated outputs are skipped automatically
资料来源：[README.md:80-100](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
## Project Architecture
```mermaid
graph TB
subgraph "Configuration Layer"
A[Environment Variables]
B[Config Validation]
end
subgraph "Transport Layer"
C[stdio.ts]
D[http.ts]
end
subgraph "CLI Layer"
E[cli.parse]
F[Runtime Mode Dispatch]
end
subgraph "MCP Tools"
G[suggest_skills]
H[fetch_manifest]
I[download_skill]
end
A --> B
B --> E
E --> F
F -->|stdio| C
F -->|server| D
C --> G
C --> H
C --> I
D --> G
D --> H
D --> I
```
资料来源：[src/index.ts:1-30](https://github.com/sator-imaging/suggest-skills/blob/main/src/index.ts)
## Technology Stack
The runtime modes are built on these core technologies:
| Component | Technology | Role |
|-----------|------------|------|
| Runtime | Bun | JavaScript runtime for CLI execution |
| Language | TypeScript | Type-safe implementation |
| Protocol | MCP SDK | Model Context Protocol tool definitions |
| Validation | Zod | Runtime schema validation |
| CLI Parser | cac | Command-line argument parsing |
资料来源：[README.md:180-200](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
## Environment Configuration
### Default Output Directory
When installing skills via download, the default output directory is:
```text
.agents/skills
```
This can be overridden using the `-o ` or `--output ` CLI option.
### Manifest URL Formats
Manifest URLs support multiple formats:
| Format | Example |
|--------|---------|
| Direct manifest URL | `https://some/skill-manifest.md` |
| GitHub blob URL (auto-converted) | `https://github.com/org/repo/blob/main/skills/README.md` |
资料来源：[README.md:100-130](https://github.com/sator-imaging/suggest-skills/blob/main/README.md)
---
---
## Doramagic 踩坑日志
项目：sator-imaging/suggest-skills
摘要：发现 15 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。
## 1. 配置坑 · 可能修改宿主 AI 配置
- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
- 证据：capability.host_targets | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | host_targets=mcp_host, claude
## 2. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | README/documentation is current enough for a first validation pass.
## 3. 运行坑 · 来源证据：v1.0.1
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.0.1
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_e40d7a86377b444f8d3eca5e8ec2b1a4 | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.0.1 | 来源类型 github_release 暴露的待验证使用条件。
## 4. 运行坑 · 来源证据：v1.1.1
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.1.1
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_d9b5403807304a33aaf39f02f80d14be | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.1.1 | 来源类型 github_release 暴露的待验证使用条件。
## 5. 运行坑 · 来源证据：v1.2.1
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.2.1
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_452c2fc3dc7d4409a8e1a4ae5419599f | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.2.1 | 来源类型 github_release 暴露的待验证使用条件。
## 6. 运行坑 · 来源证据：v1.3.1
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.3.1
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_7cf71c15b4c64e7297db646b5300ba29 | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.3.1 | 来源类型 github_release 暴露的待验证使用条件。
## 7. 维护坑 · 来源证据：v1.0.2
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.0.2
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_2150c52f85274793bfce6c1d64d24f66 | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.0.2 | 来源类型 github_release 暴露的待验证使用条件。
## 8. 维护坑 · 来源证据：v1.0.3
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.0.3
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_ac612b4c6cd44d2194d9df8b4c026220 | https://github.com/sator-imaging/suggest-skills/releases/tag/v1.0.3 | 来源类型 github_release 暴露的待验证使用条件。
## 9. 维护坑 · 来源证据：v2.0.0
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v2.0.0
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_bc9655e0f7c54b22a783ef99c7841b5e | https://github.com/sator-imaging/suggest-skills/releases/tag/v2.0.0 | 来源类型 github_release 暴露的待验证使用条件。
## 10. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | last_activity_observed missing
## 11. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | no_demo; severity=medium
## 12. 安全/权限坑 · 存在安全注意事项
- 严重度：medium
- 证据强度：source_linked
- 发现：No sandbox install has been executed yet; downstream must verify before user use.
- 对用户的影响：用户安装前需要知道权限边界和敏感操作。
- 建议检查：转成明确权限清单和安全审查提示。
- 防护动作：安全注意事项必须面向用户前置展示。
- 证据：risks.safety_notes | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | No sandbox install has been executed yet; downstream must verify before user use.
## 13. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | no_demo; severity=medium
## 14. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | issue_or_pr_quality=unknown
## 15. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:1220908449 | https://github.com/sator-imaging/suggest-skills | release_recency=unknown
]