🥷 Agent Skills Ninja
Search, Install, and Manage Agent Skills for AI Coding Assistants
GitHub Copilot • Claude Code • Cursor • Windsurf • Cline
Features •
Installation •
Usage •
Copilot Chat •
Settings •
Development
Japanese / 日本語版はこちら
| Format |
Instruction file |
Catalog file (refCatalogFormat) |
| 🔗 Ref |
IMPORTANT + link only |
Separate file: full / compact / legacy |
| ✅ Full |
IMPORTANT + detailed table |
— |
| 📦 Compact |
IMPORTANT + compressed index |
— |
| 🕰️ Legacy |
Simple table (no IMPORTANT) |
— |
IMPORTANT Prompt
The ref, full, and compact formats include the IMPORTANT prompt that instructs agents to prioritize skill files. ref keeps the always-loaded instruction file lighter by keeping only the routing prompt and catalog link in the instruction file, while moving the detailed catalog into a separate Markdown file. Use skillNinja.refCatalogFormat to choose whether that linked catalog is full, compact, or legacy.
> **IMPORTANT**: Prefer skill-led reasoning over pre-training-led reasoning.
> Read the relevant SKILL.md before working on tasks covered by these skills.
<!-- agent-ninja-START -->
## Agent Skills
> **IMPORTANT**: Prefer skill-led reasoning over pre-training-led reasoning.
> See [Agent Skills](https://github.com/aktsmm/vscode-agent-skill-ninja/blob/HEAD/.github/skills/README.md) before working on tasks covered by these skills.
<!-- agent-ninja-END -->
The catalog is written to .github/skills/README.md. Its internal format is controlled by skillNinja.refCatalogFormat (full by default, or compact / legacy).
For workspace skills, relative skillNinja.refCatalogPath values are resolved from the workspace root. For user/global skills, they are resolved from the instruction file directory so personal instruction files stay portable.
<!-- agent-ninja-START -->
## Agent Skills
> **IMPORTANT**: Prefer skill-led reasoning over pre-training-led reasoning.
> Read the relevant SKILL.md before working on tasks covered by these skills.
### Skills
| Skill | Description |
| ------------------------------------ | --------------------------------------------------- |
| [docx](https://github.com/aktsmm/vscode-agent-skill-ninja/blob/HEAD/.github/skills/docx/SKILL.md) | Process Word documents (.docx). Use for .docx files |
| [pdf](https://github.com/aktsmm/vscode-agent-skill-ninja/blob/HEAD/.github/skills/pdf/SKILL.md) | PDF manipulation toolkit. Extract text, create PDFs |
<!-- agent-ninja-END -->
Settings → Output Format → Select ref, full, compact, or legacy
🥷 Features
📁 Workspace Skill Management
- Manage SKILL.md files across four scopes: workspace, user/global, read-only installed extensions, and optional built-in
- Use
skillNinja.skillsDirectory as the managed workspace root and auto-discover extra user/global roots from VS Code Agent Skill Locations
- Automatically sync managed skills to the closest instruction file for each writable root
- Create new skill from template
🔍 Skill Search & Discovery
- Search skills by keyword (local & GitHub)
- Multi-keyword Search - Scored by name, path, description relevance
- Parallel Fetch - Fast results with 50 concurrent requests
- Fallback Search - Auto-retry with fewer keywords if no results
- Search results with descriptions & category tags
- Star counts & organization badges
- Install / Preview / Favorite directly from search results
📦 Install & Manage
- Double-click a remote skill row to install it into the workspace skill root by default (
skillNinja.skillsDirectory, default: .github/skills)
- Optional single-click install toggle for Browse view (
skillNinja.singleClickInstall)
- Install target picker for toolbar/search/preview flows and other cases with multiple managed roots (workspace or user/global)
- Auto-update instruction file (AGENTS.md / copilot-instructions.md / CLAUDE.md)
- Table Format - Skills displayed in table with "When to Use" column
- Auto-extract "When to Use" - Extracted from SKILL.md
## When to Use section
- Edit Description - Right-click to customize skill description
- Uninstall functionality
- Reinstall All - Batch reinstall from latest source (with auto index update)
- Install Feedback - NEW badge, status bar notification, auto-select in tree view
- Open Folder - Quick access to installed skill folder
- Explain Skill State - Diagnose registration source, metadata path, coexistence owner, and instruction target from the tree item context menu
- Index Integrity Check - Auto-detect missing skills and prompt for index update
- Auto-detection of AI tools in workspace (Cursor, Windsurf, Cline, Claude Code, GitHub Copilot)
- Automatic format selection based on detected tool
- Manual override available in settings
- Supported output formats:
- Markdown (AGENTS.md, CLAUDE.md, copilot-instructions.md)
- Cursor Rules (.cursor/rules/)
- Windsurf Rules (.windsurfrules)
- Cline Rules (.clinerules)
💬 GitHub Copilot Chat Integration
@skill commands for direct chat operations/search, /install, /list, /recommend- Project-based skill recommendations
- Automatically available as tools in Agent Mode
- 8 Tools:
#searchSkills, #installSkill, #uninstallSkill, #listSkills, #recommendSkills, #updateSkillIndex, #webSearchSkills, #addSkillSource
- Trust badges (Official / Curated / Community)
- Auto-update instruction file on install
🌐 Multi-language & UI
- Japanese / English UI (auto-detect + manual switch)
- Skill preview in Webview
- Favorites feature
🎬 Demo
📥 Installation
VS Code Marketplace
ext install yamapan.agent-skill-ninja
Or search for "Agent Skills Ninja" in VS Code Extensions (Ctrl+Shift+X)
Manual Installation
- Download
.vsix from Releases
- In VS Code:
Ctrl+Shift+P → Extensions: Install from VSIX...
- Select the downloaded
.vsix file
🧩 Companion Extension
📚 Included Skill Sources
Preset index includes skills from official, curated, and community sources out of the box.
Use Update Index to refresh the latest skills and metadata from these sources.
🥷 Usage
- Click the spiral shuriken icon in the Activity Bar
- Installed Skills - Workspace managed skills grouped by skill root
- Workspace Skills: managed under
skillNinja.skillsDirectory (default: .github/skills)
- Newly installed skills (temporary badge)
- Toolbar: Skill Output / Update Instruction / Create / Refresh / Settings
- In the workspace view, Skill Output opens the workspace root directly without showing the all-roots picker
- In
ref mode, Skill Output opens the linked catalog; in full / compact / legacy, it opens the instruction file itself
- Empty state: Search / Create / Open Skill Output quick links
- Open skill folder or file from the workspace scope
- User / Global Skills - Personal skills grouped by skill root, plus read-only installed extension skills and read-only built-in skills
- User / Global Skills: discovered from standard personal roots (
~/.copilot/skills, ~/.claude/skills, ~/.agents/skills) plus VS Code Agent Skill Locations
- Installed Extensions: read-only skills discovered from skill folders bundled with installed VS Code extensions, grouped by extension first and then by variant/root
- Built-in Skills: read-only group for Copilot / VS Code packaged skills, grouped first by provider/origin (for example GitHub Copilot Chat, GitHub Copilot CLI, VS Code) and then by variant/root (for example Prompts, Skills, Package (Universal)); this group is shown by default and can be hidden from Settings
- Root nodes use concise home/product labels, while counts and full paths stay in the secondary description / tooltip
- Toolbar: Skill Output / Update Instruction / Create / Refresh / Settings
- In the user/global view, Skill Output opens the default writable user/global root directly without showing the all-roots picker
Default priority: VS Code user customizations, then Copilot home, Claude home, and finally the global agent home
- In
ref mode, Skill Output opens the linked catalog; in full / compact / legacy, it opens the instruction file itself
- Empty state: Create / Settings / Open Skill Output quick links
- Open skill folder or file from any visible user/global scope
- Remote Skills - Browse skills by source
- Favorites section at top
- Sources sorted: Official → Curated → Community
- Shows installed status with green icons
Double-click a row to install to the workspace root by default, or use the inline Install action when you want the scope picker
Toolbar: Search / Web Search / Update Index / Add Source / Create / Settings
Icon Legend
| Icon |
Meaning |
| check (green) |
Installed skill |
| NEW badge |
Recently installed (temporary badge) |
| star-full (yellow) |
Favorites section |
| verified (blue) |
Official source (Anthropic, OpenAI, GitHub, Microsoft) |
| star (yellow) |
Curated awesome-list |
| repo |
Community repository |
Command Palette
| Command |
Description |
Agent Skills Ninja: Search Skills |
Search and install skills |
Agent Skills Ninja: Update Index |
Update index from all sources |
Agent Skills Ninja: Search on GitHub |
Search skills on GitHub |
Agent Skills Ninja: Add Source Repository |
Add new source repository |
Agent Skills Ninja: Remove Source Repository |
Remove source repository |
Agent Skills Ninja: Uninstall Skill |
Uninstall a skill |
Agent Skills Ninja: Show Installed Skills |
Show installed skills |
Agent Skills Ninja: Create New Skill |
Create new workspace skill |
Agent Skills Ninja: Reinstall All |
Reinstall all skills from latest source |
Agent Skills Ninja: Uninstall All |
Uninstall all skills (with confirmation) |
Agent Skills Ninja: Uninstall Multiple |
Select multiple skills to uninstall |
Agent Skills Ninja: Reinstall Multiple |
Select multiple skills to reinstall |
Agent Skills Ninja: Open Skill Output |
Choose a managed scope, then open the linked catalog in ref, or the instruction file in other formats |
Agent Skills Ninja: Update Instruction |
Update instruction file manually |
Agent Skills Ninja: Open Skill Folder |
Open installed skill folder in OS |
Quick Start
1. Ctrl+Shift+P → "Agent Skills Ninja: Search Skills"
2. Enter keywords (e.g., "pdf", "azure", "git")
3. Select skill → Choose action (Install / Preview / Favorite / GitHub)
4. Done! Auto-registered in instruction file
Search Tips 💡
| Example |
Effect |
azure |
Keyword search |
azure devops |
Multiple keywords, ranked by relevance |
username keyword |
First word searched as username |
user:anthropics |
Explicit user search |
repo:owner/repo |
Repository search |
If no results found, keywords are automatically reduced and retried.
💬 Copilot Chat
Use @skill in GitHub Copilot Chat for skill operations:
@skill /search MCP server # Search skills
@skill /install github-mcp # Install skill
@skill /list # List installed
@skill /recommend # Project-based recommendations
@skill what tools for Python? # Natural language search
Commands
| Command |
Description |
/search <query> |
Search skills by keyword |
/install <name> |
Install a skill |
/list |
List installed skills |
/recommend |
Recommendations based on workspace |
Search results include install buttons for direct installation
In GitHub Copilot's Agent Mode, tools are automatically available.
| Tool Reference |
Description |
#searchSkills |
Search skills by keyword |
#installSkill |
Install a skill |
#uninstallSkill |
Uninstall a skill |
#listSkills |
List installed skills |
#recommendSkills |
Get project-based recommendations |
#updateSkillIndex |
Update skill index |
#webSearchSkills |
Web search skills on GitHub |
#addSkillSource |
Add new skill source |
Usage Examples
💬 "Find Azure-related skills"
→ #searchSkills automatically invoked, displays results
💬 "Install the bicep-mcp skill"
→ #installSkill installs, auto-updates instruction file
💬 "Search GitHub for MCP servers"
→ #webSearchSkills searches GitHub repositories
💬 "What skills would you recommend for this project?"
→ #recommendSkills analyzes workspace and recommends
Features
- Trust Badges: Shows Official / Curated / Community
- Recommended Skills: Suggests best skills from search results
- Index Update Info: Shows last update date with warnings if outdated
- Settings Integration: Respects
autoUpdateInstruction / skillsDirectory
- Token Efficiency: Save conversation context by using MCP tools
If you don't need MCP tools, you can disable them from GitHub Copilot Chat:
- Copilot Chat panel → Settings → Tools
- Toggle off "Agent Skills Ninja" tools
⚙️ Settings
| Order |
Setting |
Default |
Description |
| 1 |
skillNinja.autoUpdateInstruction |
true |
Auto-update instruction file on install |
| 2 |
skillNinja.instructionFile |
AGENTS.md |
Instruction file format (requires Auto Update) |
| 3 |
skillNinja.customInstructionPath |
"" |
Custom path (only when 'custom' selected) |
| 4 |
skillNinja.skillsDirectory |
.github/skills |
Directory to install and manage workspace skills |
| 5 |
skillNinja.useVsCodeAgentSkillLocations |
true |
Discover standard personal roots and extra user/global skill roots |
| 6 |
skillNinja.showBuiltInSkills |
true |
Show read-only built-in skills |
| 7 |
skillNinja.outputFormat |
ref |
Output format (ref / full / compact / legacy) |
| 8 |
skillNinja.refCatalogPath |
.github/skills/README.md |
Catalog file path used by the ref format |
| 9 |
skillNinja.refCatalogFormat |
full |
Catalog detail format used when outputFormat is ref |
| 10 |
skillNinja.language |
auto |
UI language (auto / en / ja) |
| 11 |
skillNinja.autoUpdateSkillsOnUpgrade |
prompt |
Update installed skills after extension upgrade |
| 12 |
skillNinja.githubToken |
"" |
GitHub Token (for API rate limit) |
| 13 |
skillNinja.singleClickInstall |
false |
Install remote skills with single click |
| 14 |
skillNinja.coexistenceMode |
auto |
Coexistence with Agent Resources Ninja (auto / independent) |
| 15 |
skillNinja.useSharedSourcesManifest |
false |
Share source-list SSOT with Agent Resources Ninja via ~/.agent-ninja/sources.json |
Settings are displayed in the order above
Legacy compatibility setting: skillNinja.includeLocalSkills is deprecated. Workspace skills stay scoped to skillNinja.skillsDirectory, while personal roots and additional user/global roots are discovered from skillNinja.useVsCodeAgentSkillLocations. Configured locations support ${workspaceFolder}, ${userHome}, ${env:APPDATA}, and %APPDATA%. Built-in read-only skills are controlled by skillNinja.showBuiltInSkills and are shown by default.
Coexistence with Agent Resources Ninja
When the companion extension Agent Resources Ninja is also installed, both extensions cooperate so that AGENTS.md / CLAUDE.md / etc. always contains exactly one shared block (<!-- agent-ninja-START --> / <!-- agent-ninja-END -->). Resources Ninja is the owner whenever both are active; Skill Ninja silently defers and migrates any pre-existing <!-- skill-ninja-* --> block into the shared marker.
Remote skills installed by either extension reuse the same .skill-meta.json contract. In coexistence mode, Skill Ninja now treats those shared metadata files as the source of truth for registration state as well, so skills installed from Resources Ninja still appear as managed skills and keep reinstall / unregister actions in Skill Ninja.
Local workspace skills managed by Resources Ninja keep source: "local" metadata. Skill Ninja lists them as local skills, but does not treat them as missing from the remote skill index and excludes them from remote-index reinstall commands.
If the sibling extension is uninstalled, Skill Ninja takes over the same shared block on the next vscode.extensions.onDidChange event — no parallel blocks, no orphan markers, no manual cleanup needed in the normal case.
Optional shared source list: enable skillNinja.useSharedSourcesManifest when you want Skill Ninja and Agent Resources Ninja to reuse the same remote source definitions through ~/.agent-ninja/sources.json. This shares the source list only; each extension still refreshes and stores its own index contents.
Note: resourceNinja.kindsExcluded after uninstalling Skill Ninja
If you have used Resources Ninja with resourceNinja.kindsExcluded containing "skill" (the standalone default) and then uninstall Skill Ninja, Resources Ninja will fall back to its standalone behavior and re-apply that exclusion — i.e. the skill rows will disappear from the shared block. To bring them back:
- Remove
"skill" from resourceNinja.kindsExcluded in your settings, or
- Run
Agent Resources Ninja: Recompute Coexistence Ownership after editing the setting.
While Skill Ninja is active, Resources Ninja ignores kindsExcluded at runtime and writes all kinds (including skill) into the shared block, so this only affects the post-uninstall state.
Set skillNinja.coexistenceMode to independent to opt out and keep the legacy <!-- skill-ninja-* --> block regardless of Resources Ninja (advanced, allows parallel blocks). See .github/instructions/SkillList.instructions.md for the full contract.
Diagnostics: Agent Skills Ninja: Show Coexistence Status / Recompute Coexistence Ownership / Clean Up Orphan Instruction Block.
| Format |
Content |
Best For |
ref |
IMPORTANT + link in instruction file; catalog in a separate file |
Always-loaded context hygiene (Default) |
full |
IMPORTANT + Detailed table (200 chars) |
Complete information in one file |
compact |
IMPORTANT + Compressed index (100 chars) |
Token-efficient prompts in one file |
legacy |
Simple table only (no IMPORTANT) |
Backward compatibility |
When using ref, configure skillNinja.refCatalogPath (where the catalog is written) and skillNinja.refCatalogFormat (full / compact / legacy) to set the detail level inside that catalog file.
How Instruction File Sync Works
When autoUpdateInstruction is enabled:
- Install/Uninstall skill → Instruction file is automatically updated
- Managed SKILL.md detected under each writable root → Included in that root's managed section
- Manual Update Instruction File → Regenerates the managed section for every writable root
The instruction file contains a managed section with IMPORTANT prompt and Description column:
<!-- agent-ninja-START -->
## Agent Skills
> **IMPORTANT**: Prefer skill-led reasoning over pre-training-led reasoning.
> Read the relevant SKILL.md before working on tasks covered by these skills.
### Skills
| Skill | Description |
| ------------------------------------------------ | ------------------------------------ |
| [skill-name](https://github.com/aktsmm/vscode-agent-skill-ninja/blob/HEAD/.github/skills/skill-name/SKILL.md) | Description text \| When to use text |
<!-- agent-ninja-END -->
Description column format: {description:80} | {whenToUse:80} (max 160 chars total)
Instruction File Options
| Value |
File Path |
Use Case |
AGENTS.md |
AGENTS.md (root) |
Recommended: General |
.github/copilot-instructions.md |
.github/copilot-instructions.md |
GitHub Copilot |
.github/instructions/SkillList.instructions.md |
.github/instructions/SkillList.instructions.md |
Copilot Instructions folder |
CLAUDE.md |
CLAUDE.md (root) |
Claude Code |
custom |
Any path (set in customInstructionPath) |
Custom |
🔑 GitHub Token Setup
Important: GitHub Token is required for GitHub Search. Without it, API rate limits (60 requests/hour) will be exhausted quickly and searches will fail.
Set up a GitHub Token to enable full search functionality:
Option 1: VS Code Settings
Find Agent Skills Ninja: GitHub Token in settings and enter your token:
{
"skillNinja.githubToken": "ghp_xxxxxxxxxxxx"
}
👉 Create a GitHub Token (Required scopes: repo, read:org)
Option 2: GitHub CLI (Recommended)
gh auth login
If GitHub CLI is installed, the token is automatically retrieved (no configuration needed)
🛠️ Development
# Install dependencies
npm install
# Compile
npm run compile
# Build in watch mode
npm run watch
# Package
npm run package
# Lint
npm run lint
Debugging
- Press
F5 in VS Code
- Test the extension in a new VS Code window
- Run
Agent Skills Ninja commands from Command Palette (Ctrl+Shift+P)
Contributing
- Fork this repository
- Create a feature branch (
git checkout -b feature/amazing-feature)
- Commit changes (
git commit -m 'Add amazing feature')
- Push to branch (
git push origin feature/amazing-feature)
- Open a Pull Request
📄 License
CC BY-NC-SA 4.0 © yamapan
- Free for non-commercial use, modification, and redistribution
- Commercial use requires permission
- Microsoft employees may use for work purposes
Use of this content for AI/ML training, data mining, or other analytical purposes is prohibited.
👤 Author
yamapan (https://github.com/aktsmm)
