Key Features
- Generates skill manifest from a GitHub skills directory
- MCP server for recommending and downloading repository-specific AI agent skills
- Supports
stdioand HTTP runtime modes from the same codebase
[!IMPORTANT] This tool doesn't provide security checks. To find official skills repository, visit: https://skills.sh/official
Getting Started
Example MCP Configuration
{
"mcpServers": {
"suggest-skills": {
"command": "npx",
"args": [
"-y",
"suggest-skills",
"--",
"--output=.agents/skills",
"https://github.com/sator-imaging/suggest-skills/blob/main/official/official-skills.md",
"https://github.com/sator-imaging/suggest-skills/blob/main/community/community-skills.md"
],
"env": {
"SUGGEST_SKILLS_MANIFEST_URLS": [
"https://some/skill-manifest.md",
"https://other/skill-manifest.md"
]
}
}
}
}
Official & Community Skills
Prebuilt skill manifests can be found in this repository:
[!TIP] Security scanning is provided by NVIDIA SkillSpector via the CI workflow. Each skill is scanned individually and the resulting risk value is written to the
Security Riskcolumn.
Generate a Manifest
npx suggest-skills generate \
https://github.com/OWNER/REPO/tree/main/skills
npx suggest-skills generate \
--recursive \
https://github.com/OWNER/REPO/tree/main/skills
This may write the following files in the current working directory:
<owner>.<repo>[.<path>].skills.md: entries collected from skill directories that containSKILL.md<owner>.<repo>[.<path>].designs.md: entries collected from skill directories that containDESIGN.md<owner>.<repo>[.<path>].agents.md: entries collected from flat top-level markdown files, withNameandDescriptioncolumns only- Accepts plain GitHub repository URLs in generate mode by assuming repo root on
main
Generate mode uses these rules:
- GitHub directory discovery uses a recursive tree listing internally
SKILL.mdandDESIGN.mdare discovered in skill directories, and bundled assets are any other files next to them or in nested subdirectories- Symlinks found during generate are not handled specially; they may appear in bundled assets, but are not traversed
- Without
--recursive,SKILL.mdandDESIGN.mdare discovered from direct child directories of the generate root - With
--recursive, only subdirectory search is expanded, so nested directories are also scanned forSKILL.mdandDESIGN.md - Root-level markdown files for
.agents.mdare still discovered the same way whether--recursiveis present or not - Output file naming stays based on the original generate root whether
--recursiveis present or not - Output file names are normalized to remove redundant type suffixes (e.g.,
some-skills.mdinstead ofsome-skills.skills.skills.md) DESIGN.mdreads optionalnameanddescriptionfrom YAML front matter, and emitsNonewhen description is missing- flat top-level markdown files with front matter are treated as agent definitions for
.agents.md - Empty generated outputs are skipped, so no file is written and no overwrite prompt is shown for them
Configuration
Environment Variables
GITHUB_PAT is optional and is used for authenticated requests to api.github.com.
SUGGEST_SKILLS_MANIFEST_URLS is required and must contain at least one URL.
Accepted formats:
- JSON array
- Comma-separated string
- Newline-separated string
GitHub blob URLs are converted to raw.githubusercontent.com URLs automatically.
CLI Options
-o <dir>or--output <dir>: output directory for installed skillsgenerate [-r|--recursive] <github-url>: generate markdown inventories from a GitHub skills directory or repo rootserver --port <number>: run the streamable HTTP server
Default output directory:
.agents/skills
Run in stdio Mode
SUGGEST_SKILLS_MANIFEST_URLS='["https://some/skill-manifest.md"]' \
npx suggest-skills
Run in HTTP Mode
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 and the health check is available at http://localhost:3100/health.
MCP Tools
suggest_skills
Accepts an optional manifestUrl to overwrite the default configuration.
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 anything until requested
fetch_manifest
Accepts a manifest URL and returns its text content.
download_skill
Accepts a GitHub folder URL in the form:
https://github.com/<owner>/<repo>/tree/<ref>/<path>
Returns every file in that folder with:
- Path relative to the requested folder
- UTF-8 text content
- File symlinks are downloaded when GitHub provides a
download_url - Repository-relative directory symlinks are resolved and downloaded recursively
Technology Stack
- Bun
- TypeScript
- @modelcontextprotocol/sdk
- Zod
Project Architecture
Config -> MCP tool registration -> stdio or HTTP transport
CLI generate -> GitHub directory scan -> manifest markdown file
\-> GitHub URL normalization / folder download
Coding Standards
The codebase follows a few clear implementation patterns:
- Small focused modules with runtime concerns split by file
- Explicit config validation through
ConfigError - Typed tool schemas and structured output for MCP tools
- Minimal transport wrappers around shared server creation
- Tests centered on observable behavior rather than implementation detail
Contributing
- Keep changes aligned with the MCP server's current responsibilities
- Prefer updating shared logic in
src/core.ts,src/config.ts, and helper modules before adding transport-specific behavior - Add or update tests when changing config parsing, MCP responses, or GitHub download behavior
- Use
SPEC.mdas the starting point for intended behavior and direction
