zhongwei/gh-nathanvale-side-quest-marketplace-plugins-plugin-template
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:42:15 +08:00
commit a6aed6b6ce
7 changed files with 768 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,15 @@
{
"name": "plugin-template",
"description": "Generate new plugin scaffolds with configurable components. Commands: /plugin-template:create",
"version": "1.0.0",
"author": {
"name": "Nathan Vale",
"email": "hi@nathanvale.com"
},
"skills": [
"./skills"
],
"commands": [
"./commands"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# plugin-template
Generate new plugin scaffolds with configurable components. Commands: /plugin-template:create

203
commands/create.md Normal file
View File

@@ -0,0 +1,203 @@
---
description: Create a new plugin scaffold with configurable components
argument-hint: [plugin-name]
model: claude-sonnet-4-5-20250929
allowed-tools: Bash, Write, Edit, Read, Glob, AskUserQuestion
---
# Create New Plugin
Generate a new plugin scaffold with configurable components following the SideQuest marketplace patterns.
## Instructions
You are a plugin scaffolding specialist. Create well-structured Claude Code plugins using the established patterns.
### Input
The plugin name is provided as `$1` (or `$ARGUMENTS`).
### Validation
1. **Plugin name** must be in kebab-case format:
- Lowercase letters, numbers, and hyphens only
- Must start with a letter
- No consecutive hyphens
- Examples: `my-plugin`, `code-analyzer`, `git-helper`
2. **Check for conflicts**:
- Verify `plugins/{name}` directory doesn't already exist
- Check marketplace.json for existing plugin with same name
### Step 1: Component Selection
Use `AskUserQuestion` to ask the user which components to include:
**Question**: "Which components should this plugin include?"
| Component | Description |
|-----------|-------------|
| commands | Slash commands (e.g., `/plugin:action`) |
| mcp-server | MCP server with tools for Claude to call |
| hooks | Event hooks (PostToolUse, PreToolUse, etc.) |
| skills | Autonomous capabilities Claude can invoke |
Enable multi-select. Default to all components if user doesn't specify.
### Step 2: Implementation Type Selection
Use `AskUserQuestion` to ask about implementation type:
**Question**: "What implementation type?"
| Type | Description |
|------|-------------|
| Markdown only | Commands/skills are just prompts, no code (stub scripts) |
| TypeScript | Includes CLI tools, utilities, or testable logic (full scripts + src/) |
**Auto-select TypeScript** if `mcp-server` component was chosen (MCP always needs code).
### Directory Structure
Based on selections, create:
```
MARKDOWN ONLY: TYPESCRIPT:
plugins/{name}/ plugins/{name}/
├── .claude-plugin/ ├── .claude-plugin/
│ └── plugin.json │ └── plugin.json
├── package.json ←(stubs) ├── package.json ←(full)
├── commands/ ├── tsconfig.json
│ └── sample.md ├── src/
└── skills/ │ ├── index.ts
└── {name}/ │ └── index.test.ts
└── SKILL.md ├── commands/
│ └── sample.md
└── skills/
└── {name}/
└── SKILL.md
```
### Package.json Differences
**Markdown only (stub scripts):**
```json
{
"scripts": {
"test": "echo 'No tests'",
"typecheck": "echo 'No typecheck'"
}
}
```
**TypeScript (full scripts):**
```json
{
"scripts": {
"test": "bun test --recursive",
"typecheck": "tsc --noEmit",
"format": "biome format --write .",
"lint": "biome lint .",
"check": "biome check --write ."
},
"devDependencies": {
"@types/bun": "latest"
}
}
```
### Author Information
Default to git config:
- Name: `git config user.name`
- Email: `git config user.email`
### File Generation
Use templates from `$PLUGIN_DIR/src/templates.ts`:
1. **package.json**: Use `packageJsonForType()` based on implementation type
2. **plugin.json**: Metadata with name, description, version, author
3. **tsconfig.json**: Only for TypeScript type
4. **src/index.ts**: Only for TypeScript type
5. **src/index.test.ts**: Only for TypeScript type
6. **sample.md**: Command with frontmatter and usage example
7. **index.ts**: MCP server using `mcpez` library
8. **.mcp.json**: Server configuration with `${CLAUDE_PLUGIN_ROOT}`
9. **hooks.json**: Empty hooks structure with comments
10. **SKILL.md**: Skill with frontmatter and instructions
### Marketplace Registration
After generating files, update `.claude-plugin/marketplace.json`:
1. Read current marketplace.json
2. Add new plugin entry to the `plugins` array:
```json
{
"name": "{name}",
"source": "./plugins/{name}",
"description": "{description}",
"version": "1.0.0",
"author": { "name": "{author}" },
"category": "development",
"keywords": ["{name}"]
}
```
3. Write updated marketplace.json
### Post-Generation Steps
After creating the plugin:
1. **Run setup commands** (TypeScript only):
```bash
cd plugins/{name} && bun install
```
2. **Verify generation** (TypeScript only):
```bash
bun test --recursive
```
3. **Output summary**:
- List all created files
- Show implementation type chosen
- Show next steps for the user
- Mention `/plugin-template:strip` if they want to remove TypeScript later
- Mention `/plugin-template:upgrade` if they want to add TypeScript later
### Example Usage
```
User: /plugin-template:create my-awesome-plugin
```
Expected flow:
1. Validate plugin name
2. Ask which components to include (multi-select)
3. Ask implementation type (unless mcp-server forces TypeScript)
4. Create directory structure
5. Generate all files
6. Register in marketplace
7. Run bun install (if TypeScript)
8. Show summary with next steps
### Error Handling
- If plugin name is invalid, explain the format requirements
- If directory already exists, ask user if they want to overwrite
- If marketplace.json update fails, show manual steps
- Always clean up partial generation on failure
### Important Notes
- Follow the @sidequest namespace convention
- Use Biome for formatting (configured in root biome.json)
- MCP servers use mcpez library
- All paths should use `${CLAUDE_PLUGIN_ROOT}` for portability
- Generated code should pass typecheck and lint
- If user chose mcp-server, TypeScript is auto-selected
Now create the plugin scaffold based on the provided name and user preferences.

151
commands/strip.md Normal file
View File

@@ -0,0 +1,151 @@
---
description: Strip TypeScript from a plugin, converting it to markdown-only
argument-hint: [plugin-name]
model: claude-sonnet-4-5-20250929
allowed-tools: Bash, Write, Edit, Read, Glob, AskUserQuestion
---
# Strip TypeScript from Plugin
Remove TypeScript setup from a plugin, converting it to markdown-only mode with stub scripts.
## Instructions
You are a plugin maintenance specialist. Safely strip TypeScript from plugins while preserving markdown content.
### Input
The plugin name is provided as `$1` (or `$ARGUMENTS`).
### Validation
1. **Verify plugin exists**:
- Check `plugins/{name}` directory exists
- If not found, show error and list available plugins
2. **Verify it's a TypeScript plugin**:
- Check for `tsconfig.json` presence
- If already markdown-only, inform user and exit
3. **Check for MCP server**:
- If `mcp-servers/` exists, warn user that MCP requires TypeScript
- Ask if they want to proceed anyway (will break MCP functionality)
### Confirmation Required
**CRITICAL**: Before making any changes, use `AskUserQuestion`:
**Question**: "Are you sure you want to strip TypeScript from '{name}'?"
Show what will be deleted:
- `tsconfig.json`
- `src/` directory (all files)
- `devDependencies` from package.json
Show what will be modified:
- `package.json` scripts will become stubs
Options:
1. **Yes, strip TypeScript** - Proceed with removal
2. **No, cancel** - Abort operation
### Files to Delete
```
plugins/{name}/
├── tsconfig.json ❌ DELETE
└── src/ ❌ DELETE (entire directory)
├── index.ts ❌
├── index.test.ts ❌
└── ... ❌
```
### Files to Modify
**package.json** - Replace scripts with stubs:
Before:
```json
{
"scripts": {
"test": "bun test --recursive",
"typecheck": "tsc --noEmit",
"format": "biome format --write .",
"lint": "biome lint .",
"check": "biome check --write ."
},
"devDependencies": {
"@types/bun": "latest"
}
}
```
After:
```json
{
"scripts": {
"test": "echo 'No tests'",
"typecheck": "echo 'No typecheck'"
}
}
```
### Execution Steps
1. **Confirm with user** (AskUserQuestion)
2. **Delete tsconfig.json**:
```bash
rm plugins/{name}/tsconfig.json
```
3. **Delete src/ directory**:
```bash
rm -rf plugins/{name}/src
```
4. **Update package.json**:
- Read current package.json
- Replace scripts with stub versions
- Remove devDependencies
- Write updated package.json
### Files to Preserve
Do NOT touch these:
- `.claude-plugin/plugin.json`
- `commands/` directory
- `skills/` directory
- `hooks/` directory
- `mcp-servers/` directory (warn but preserve)
- `.mcp.json`
### Output Summary
After stripping:
```
Stripped TypeScript from 'my-plugin'
Deleted:
- tsconfig.json
- src/index.ts
- src/index.test.ts
Modified:
- package.json (scripts now use stubs)
Plugin is now markdown-only.
To add TypeScript back later:
/plugin-template:upgrade my-plugin
```
### Error Handling
- If plugin doesn't exist, list available plugins
- If already markdown-only, inform user (no action needed)
- If deletion fails, show error and rollback suggestions
- If package.json update fails, show manual fix steps
### Example Usage
```
User: /plugin-template:strip my-plugin

166
commands/upgrade.md Normal file
View File

@@ -0,0 +1,166 @@
---
description: Add TypeScript setup to a markdown-only plugin
argument-hint: [plugin-name]
model: claude-sonnet-4-5-20250929
allowed-tools: Bash, Write, Edit, Read, Glob
---
# Upgrade Plugin to TypeScript
Add TypeScript setup to a markdown-only plugin, enabling CLI tools, utilities, and testable logic.
## Instructions
You are a plugin maintenance specialist. Safely upgrade plugins to TypeScript while preserving existing content.
### Input
The plugin name is provided as `$1` (or `$ARGUMENTS`).
### Validation
1. **Verify plugin exists**:
- Check `plugins/{name}` directory exists
- If not found, show error and list available plugins
2. **Verify it's a markdown-only plugin**:
- Check for absence of `tsconfig.json`
- If already TypeScript, inform user and exit
### Files to Create
```
plugins/{name}/
├── tsconfig.json ✨ CREATE
└── src/ ✨ CREATE
├── index.ts ✨ CREATE
└── index.test.ts ✨ CREATE
```
### Files to Modify
**package.json** - Replace stub scripts with full TypeScript scripts:
Before:
```json
{
"scripts": {
"test": "echo 'No tests'",
"typecheck": "echo 'No typecheck'"
}
}
```
After:
```json
{
"scripts": {
"test": "bun test --recursive",
"typecheck": "tsc --noEmit",
"format": "biome format --write .",
"format:check": "biome format .",
"lint": "biome lint .",
"check": "biome check --write ."
},
"devDependencies": {
"@types/bun": "latest"
}
}
```
### Template Content
**tsconfig.json**:
```json
{
"extends": "../../tsconfig.base.json",
"include": ["src/**/*.ts"],
"exclude": ["**/node_modules/**"]
}
```
**src/index.ts** - Use template from `$PLUGIN_DIR/src/templates.ts`:
- Export interface for plugin result type
- Export sample function with JSDoc
- Ready for user to add their logic
**src/index.test.ts** - Use template from `$PLUGIN_DIR/src/templates.ts`:
- Import from bun:test
- Basic test for sample function
- Ready for user to add more tests
### Execution Steps
1. **Create tsconfig.json**
2. **Create src/ directory**
3. **Create src/index.ts** with template
4. **Create src/index.test.ts** with template
5. **Update package.json**:
- Read current package.json
- Add full scripts
- Add devDependencies
- Write updated package.json
6. **Run bun install**
7. **Run tests to verify**
### Files to Preserve
Do NOT touch these:
- `.claude-plugin/plugin.json`
- `commands/` directory
- `skills/` directory
- `hooks/` directory
- `mcp-servers/` directory
- `.mcp.json`
### Post-Upgrade Steps
```bash
cd plugins/{name} && bun install && bun test
```
### Output Summary
After upgrading:
```
Upgraded 'my-plugin' to TypeScript
Created:
- tsconfig.json
- src/index.ts
- src/index.test.ts
Modified:
- package.json (full scripts + devDependencies)
Next steps:
1. Edit src/index.ts to add your logic
2. Add tests to src/index.test.ts
3. Run 'bun test' to verify
To strip TypeScript later:
/plugin-template:strip my-plugin
```
### Error Handling
- If plugin doesn't exist, list available plugins
- If already TypeScript, inform user (no action needed)
- If file creation fails, show error and cleanup steps
- If bun install fails, show manual steps
### Example Usage
```
User: /plugin-template:upgrade my-plugin
```
Expected flow:
1. Validate plugin exists and is markdown-only
2. Create tsconfig.json
3. Create src/index.ts and src/index.test.ts
4. Update package.json with full scripts
5. Run bun install
6. Run bun test to verify
7. Show summary with next steps

57
plugin.lock.json Normal file
View File

@@ -0,0 +1,57 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:nathanvale/side-quest-marketplace:plugins/plugin-template",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "633e9c6d1c9b32fbf46dd888d2c76858c447692c",
"treeHash": "216a26a423515e2e0f10dd9404837e5d9b5740afa19eb759c5b53a30cc5e88b2",
"generatedAt": "2025-11-28T10:27:15.901966Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "plugin-template",
"description": "Generate new plugin scaffolds with configurable components. Commands: /plugin-template:create",
"version": "1.0.0"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "5f94094631cc2780027a969b1ce9057e49fb3a6d8fe54b15aca3b0df88e0a820"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "35d46d04fe66d693910cfa5732d6b2c3adee83047b424f55f673a8f7c68c37d1"
},
{
"path": "commands/strip.md",
"sha256": "7c39453a33a3d5b74ba41d0554e689604ee7986cf8e7c15a84f4947c5350c383"
},
{
"path": "commands/create.md",
"sha256": "146c1bfcac36d316a1d63ccdf2d1cae87598b57059226ddb41af7f8224996d34"
},
{
"path": "commands/upgrade.md",
"sha256": "20367b5c9d55a111e6bf96d76c5fb35f674c236749bc3f89eba5e9effa471bc2"
},
{
"path": "skills/plugin-creator/SKILL.md",
"sha256": "9bd0c4ab9801376f3fb0e505fcf14639be5245aded3e626cddd3bafa893353ff"
}
],
"dirSha256": "216a26a423515e2e0f10dd9404837e5d9b5740afa19eb759c5b53a30cc5e88b2"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

173
skills/plugin-creator/SKILL.md Normal file
View File

@@ -0,0 +1,173 @@
---
name: plugin-creator
description: Generate new Claude Code plugin scaffolds with configurable components. Use when users want to create a new plugin, start a plugin project, or scaffold plugin components.
---
# Plugin Creator
Generate well-structured Claude Code plugins following SideQuest marketplace patterns.
## When to Use This Skill
- User wants to create a new plugin
- User asks about plugin structure or scaffolding
- User mentions "new plugin", "create plugin", "plugin template"
- User wants to add components (commands, MCP server, hooks, skills) to a project
## Plugin Components
| Component | Purpose | Files Created |
|-----------|---------|---------------|
| commands | Slash commands users invoke | `commands/*.md` |
| mcp-server | Tools Claude can call | `mcp-servers/{name}/index.ts` |
| hooks | Event handlers | `hooks/hooks.json` |
| skills | Autonomous capabilities | `skills/{name}/SKILL.md` |
## Implementation Types
| Type | Use Case | Structure |
|------|----------|-----------|
| Markdown only | Commands/skills are just prompts | No src/, stub scripts |
| TypeScript | CLI tools, utilities, testable logic | src/, full scripts |
**Note**: MCP server component auto-selects TypeScript (code required).
## Quick Reference
### Create Plugin
```
/plugin-template:create my-plugin
```
Then select:
1. Components (commands, mcp-server, hooks, skills)
2. Implementation type (markdown or typescript)
### Strip TypeScript
```
/plugin-template:strip my-plugin
```
Converts TypeScript plugin to markdown-only.
### Upgrade to TypeScript
```
/plugin-template:upgrade my-plugin
```
Adds TypeScript setup to markdown-only plugin.
### Plugin Naming
- Use kebab-case: `my-awesome-plugin`
- Lowercase letters, numbers, hyphens
- Must start with a letter
### Standard Structures
**Markdown Only:**
```
plugins/{name}/
├── .claude-plugin/plugin.json
├── package.json ←(stub scripts)
├── commands/
└── skills/{name}/
```
**TypeScript:**
```
plugins/{name}/
├── .claude-plugin/plugin.json
├── package.json ←(full scripts)
├── tsconfig.json
├── src/
│ ├── index.ts
│ └── index.test.ts
├── commands/
├── mcp-servers/{name}/
├── hooks/
└── skills/{name}/
```
## Generation Workflow
1. **Validate** plugin name (kebab-case, no conflicts)
2. **Ask** which components to include
3. **Create** directory structure
4. **Generate** files from templates
5. **Register** in marketplace.json
6. **Install** dependencies with bun
7. **Verify** with tests
## Template Patterns
### package.json
- Namespace: `@sidequest/{name}`
- Scripts: test, typecheck, format, lint, check
- Uses Biome for formatting/linting
### MCP Server
- Uses `mcpez` library
- Export types for testing
- Zod schemas for input validation
### Commands
- YAML frontmatter with description
- argument-hint for usage hints
- allowed-tools for security
### Skills
- YAML frontmatter with name, description
- When to use section
- Quick reference table
## Post-Generation Steps
After generating a plugin:
1. **Navigate**: `cd plugins/{name}`
2. **Install**: `bun install`
3. **Test**: `bun test`
4. **Develop**: Add your logic to the generated files
## Examples
### Example 1: Create Simple Command Plugin
```
User: I want to create a plugin for managing todo lists
Assistant: I'll create a todo-manager plugin for you.
[Uses /plugin-template:create todo-manager]
[Selects commands component]
[Generates scaffold]
```
### Example 2: Create Full Plugin with MCP
```
User: Create a plugin that provides git statistics
Assistant: I'll scaffold a git-stats plugin with an MCP server.
[Uses /plugin-template:create git-stats]
[Selects commands, mcp-server, skills]
[Generates full structure]
```
### Example 3: Add Components to Existing Plugin
```
User: My plugin needs an MCP server now
Assistant: I'll add an MCP server to your existing plugin.
[Creates mcp-servers/{name}/ directory]
[Generates index.ts and package.json]
[Updates .mcp.json]
```
## Troubleshooting
| Issue | Solution |
|-------|----------|
| Name conflict | Choose different name or remove existing |
| Invalid name | Use kebab-case (lowercase, hyphens) |
| Bun install fails | Check network, run manually |
| Tests fail | Check generated code, fix issues |
## Related Commands
- `/plugin-template:create [name]` - Create new plugin
- `/plugin-template:strip [name]` - Remove TypeScript, convert to markdown-only
- `/plugin-template:upgrade [name]` - Add TypeScript to markdown-only plugin
- `/git:commit` - Commit your plugin changes
- `/para-brain:capture` - Document plugin ideas