@nano-step/skill-manager 5.1.0 → 5.2.0

package/skills/skill-creator/references/plugin-marketplace-hosting.md

@@ -0,0 +1,101 @@
+# Plugin Marketplace Hosting & Distribution
+
+## GitHub (Recommended)
+
+1. Create repository for marketplace
+2. Add `.claude-plugin/marketplace.json` with plugin definitions
+3. Share: users add with `/plugin marketplace add owner/repo`
+
+**Benefits:** Built-in version control, issue tracking, team collaboration.
+
+## Other Git Services
+
+GitLab, Bitbucket, self-hosted servers all work:
+
+```shell
+/plugin marketplace add https://gitlab.com/company/plugins.git
+```
+
+## Private Repositories
+
+### Manual Installation/Updates
+
+Claude Code uses existing git credential helpers. If `git clone` works in terminal, it works in Claude Code.
+
+Common credential helpers:
+- `gh auth login` for GitHub
+- macOS Keychain
+- `git-credential-store`
+
+### Background Auto-Updates
+
+Set authentication token in environment:
+
+| Provider  | Environment Variables        | Notes                        |
+|-----------|------------------------------|------------------------------|
+| GitHub    | `GITHUB_TOKEN` or `GH_TOKEN` | Personal or GitHub App token |
+| GitLab    | `GITLAB_TOKEN` or `GL_TOKEN` | Personal or project token    |
+| Bitbucket | `BITBUCKET_TOKEN`            | App password or repo token   |
+
+```bash
+export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
+```
+
+## Require Marketplaces for Team
+
+Add to `.claude/settings.json`:
+
+```json
+{
+  "extraKnownMarketplaces": {
+    "company-tools": {
+      "source": {
+        "source": "github",
+        "repo": "your-org/claude-plugins"
+      }
+    }
+  },
+  "enabledPlugins": {
+    "code-formatter@company-tools": true,
+    "deployment-tools@company-tools": true
+  }
+}
+```
+
+## Managed Marketplace Restrictions
+
+Admins use `strictKnownMarketplaces` in managed settings:
+
+| Value               | Behavior                                    |
+|---------------------|---------------------------------------------|
+| Undefined (default) | No restrictions, users can add any          |
+| Empty array `[]`    | Complete lockdown, no new marketplaces      |
+| List of sources     | Users can only add from allowlist           |
+
+### Allow Specific Marketplaces Only
+
+```json
+{
+  "strictKnownMarketplaces": [
+    { "source": "github", "repo": "acme-corp/approved-plugins" },
+    { "source": "url", "url": "https://plugins.example.com/marketplace.json" }
+  ]
+}
+```
+
+### Allow All from Internal Server (Regex)
+
+```json
+{
+  "strictKnownMarketplaces": [
+    { "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }
+  ]
+}
+```
+
+## Test Locally Before Distribution
+
+```shell
+/plugin marketplace add ./my-local-marketplace
+/plugin install test-plugin@my-local-marketplace
+```

package/skills/skill-creator/references/plugin-marketplace-overview.md

@@ -0,0 +1,55 @@
+# Plugin Marketplace Overview
+
+Build and host plugin marketplaces to distribute Claude Code extensions across teams and communities.
+
+## What is a Plugin Marketplace
+
+A plugin marketplace is a catalog that lets you distribute plugins to others. Marketplaces provide:
+- Centralized discovery
+- Version tracking
+- Automatic updates
+- Support for multiple source types (git repositories, local paths, etc.)
+
+## Creating & Distributing a Marketplace
+
+1. **Create plugins**: Build plugins with commands, agents, hooks, MCP servers, or LSP servers
+2. **Create marketplace file**: Define `marketplace.json` listing plugins and sources
+3. **Host the marketplace**: Push to GitHub, GitLab, or another git host
+4. **Share with users**: Users add with `/plugin marketplace add` and install individual plugins
+
+## Directory Structure
+
+```
+my-marketplace/
+├── .claude-plugin/
+│   └── marketplace.json       # Required: marketplace catalog
+└── plugins/
+    └── my-plugin/
+        ├── .claude-plugin/
+        │   └── plugin.json    # Plugin manifest
+        └── skills/
+            └── my-skill/
+                └── SKILL.md
+```
+
+## Marketplace File Location
+
+Create `.claude-plugin/marketplace.json` in repository root.
+
+## User Commands
+
+- Add marketplace: `/plugin marketplace add owner/repo` or `/plugin marketplace add ./local-path`
+- Install plugin: `/plugin install plugin-name@marketplace-name`
+- Update marketplace: `/plugin marketplace update`
+- Validate: `/plugin validate .` or `claude plugin validate .`
+
+## Related References
+
+- Schema details: `references/plugin-marketplace-schema.md`
+- Plugin sources: `references/plugin-marketplace-sources.md`
+- Hosting & distribution: `references/plugin-marketplace-hosting.md`
+- Troubleshooting: `references/plugin-marketplace-troubleshooting.md`
+
+## Official Documentation
+
+https://code.claude.com/docs/en/plugin-marketplaces.md

package/skills/skill-creator/references/plugin-marketplace-schema.md

@@ -0,0 +1,88 @@
+# Plugin Marketplace Schema
+
+## Marketplace JSON Structure
+
+```json
+{
+  "name": "company-tools",
+  "owner": {
+    "name": "DevTools Team",
+    "email": "devtools@example.com"
+  },
+  "metadata": {
+    "description": "Brief marketplace description",
+    "version": "1.0.0",
+    "pluginRoot": "./plugins"
+  },
+  "plugins": [...]
+}
+```
+
+## Required Fields
+
+| Field     | Type   | Description                              | Example        |
+|-----------|--------|------------------------------------------|----------------|
+| `name`    | string | Marketplace identifier (kebab-case)      | `"acme-tools"` |
+| `owner`   | object | Maintainer info (name required, email optional) |         |
+| `plugins` | array  | List of available plugins                |                |
+
+## Reserved Names
+
+Cannot use: `claude-code-marketplace`, `claude-code-plugins`, `claude-plugins-official`, `anthropic-marketplace`, `anthropic-plugins`, `agent-skills`, `life-sciences`. Names impersonating official marketplaces also blocked.
+
+## Optional Metadata
+
+| Field                  | Type   | Description                                    |
+|------------------------|--------|------------------------------------------------|
+| `metadata.description` | string | Brief marketplace description                  |
+| `metadata.version`     | string | Marketplace version                            |
+| `metadata.pluginRoot`  | string | Base directory for relative plugin source paths|
+
+## Plugin Entry Schema
+
+### Required Plugin Fields
+
+| Field    | Type           | Description                                    |
+|----------|----------------|------------------------------------------------|
+| `name`   | string         | Plugin identifier (kebab-case)                 |
+| `source` | string\|object | Where to fetch plugin (path, github, url)      |
+
+### Optional Plugin Fields
+
+| Field         | Type    | Description                                         |
+|---------------|---------|-----------------------------------------------------|
+| `description` | string  | Brief plugin description                            |
+| `version`     | string  | Plugin version                                      |
+| `author`      | object  | Plugin author (name required, email optional)       |
+| `homepage`    | string  | Plugin homepage or docs URL                         |
+| `repository`  | string  | Source code repository URL                          |
+| `license`     | string  | SPDX license identifier (MIT, Apache-2.0, etc.)     |
+| `keywords`    | array   | Tags for discovery and categorization               |
+| `category`    | string  | Plugin category for organization                    |
+| `tags`        | array   | Tags for searchability                              |
+| `strict`      | boolean | If true (default), plugin needs own plugin.json     |
+
+### Component Configuration Fields
+
+| Field        | Type           | Description                            |
+|--------------|----------------|----------------------------------------|
+| `commands`   | string\|array  | Custom paths to command files/dirs     |
+| `agents`     | string\|array  | Custom paths to agent files            |
+| `hooks`      | string\|object | Hooks configuration or path            |
+| `mcpServers` | string\|object | MCP server configurations or path      |
+| `lspServers` | string\|object | LSP server configurations or path      |
+
+## Example Plugin Entry
+
+```json
+{
+  "name": "code-formatter",
+  "source": "./plugins/formatter",
+  "description": "Automatic code formatting on save",
+  "version": "2.1.0",
+  "author": { "name": "DevTools Team" },
+  "license": "MIT",
+  "keywords": ["formatting", "linting"],
+  "strict": false
+}
+```

package/skills/skill-creator/references/plugin-marketplace-sources.md

@@ -0,0 +1,103 @@
+# Plugin Marketplace Sources
+
+## Source Types
+
+### Relative Paths (Local)
+
+For plugins in same repository:
+
+```json
+{
+  "name": "my-plugin",
+  "source": "./plugins/my-plugin"
+}
+```
+
+**Note:** Relative paths only work when users add marketplace via Git. For URL-based distribution, use GitHub, npm, or git URL sources.
+
+### GitHub Repositories
+
+```json
+{
+  "name": "github-plugin",
+  "source": {
+    "source": "github",
+    "repo": "owner/plugin-repo"
+  }
+}
+```
+
+Pin to specific branch, tag, or commit:
+
+```json
+{
+  "name": "github-plugin",
+  "source": {
+    "source": "github",
+    "repo": "owner/plugin-repo",
+    "ref": "v2.0.0",
+    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
+  }
+}
+```
+
+| Field  | Type   | Description                                          |
+|--------|--------|------------------------------------------------------|
+| `repo` | string | Required. GitHub repo in `owner/repo` format         |
+| `ref`  | string | Optional. Git branch or tag                          |
+| `sha`  | string | Optional. Full 40-char git commit SHA                |
+
+### Git Repositories (GitLab, Bitbucket, etc.)
+
+```json
+{
+  "name": "git-plugin",
+  "source": {
+    "source": "url",
+    "url": "https://gitlab.com/team/plugin.git"
+  }
+}
+```
+
+| Field | Type   | Description                                 |
+|-------|--------|---------------------------------------------|
+| `url` | string | Required. Full git URL (must end with .git) |
+| `ref` | string | Optional. Git branch or tag                 |
+| `sha` | string | Optional. Full 40-char git commit SHA       |
+
+## Advanced Plugin Entry Example
+
+```json
+{
+  "name": "enterprise-tools",
+  "source": {
+    "source": "github",
+    "repo": "company/enterprise-plugin"
+  },
+  "description": "Enterprise workflow automation tools",
+  "version": "2.1.0",
+  "commands": [
+    "./commands/core/",
+    "./commands/enterprise/"
+  ],
+  "agents": ["./agents/security-reviewer.md"],
+  "hooks": {
+    "PostToolUse": [{
+      "matcher": "Write|Edit",
+      "hooks": [{
+        "type": "command",
+        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
+      }]
+    }]
+  },
+  "mcpServers": {
+    "enterprise-db": {
+      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
+      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
+    }
+  },
+  "strict": false
+}
+```
+
+**Key variable:** `${CLAUDE_PLUGIN_ROOT}` - Use in hooks and MCP configs to reference files within plugin's installation directory (plugins are copied to cache when installed).

package/skills/skill-creator/references/plugin-marketplace-troubleshooting.md

@@ -0,0 +1,80 @@
+# Plugin Marketplace Troubleshooting
+
+## Marketplace Not Loading
+
+**Symptoms:** Can't add marketplace or see plugins
+
+**Solutions:**
+- Verify marketplace URL is accessible
+- Check `.claude-plugin/marketplace.json` exists at specified path
+- Validate JSON syntax: `claude plugin validate .` or `/plugin validate .`
+- For private repos, confirm access permissions
+
+## Marketplace Validation Errors
+
+Run `claude plugin validate .` or `/plugin validate .` from marketplace directory.
+
+### Common Errors
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `File not found: .claude-plugin/marketplace.json` | Missing manifest | Create `.claude-plugin/marketplace.json` with required fields |
+| `Invalid JSON syntax: Unexpected token...` | JSON syntax error | Check for missing/extra commas, unquoted strings |
+| `Duplicate plugin name "x" found` | Two plugins share same name | Give each plugin unique `name` value |
+| `plugins[0].source: Path traversal not allowed` | Source path contains `..` | Use paths relative to marketplace root without `..` |
+
+### Warnings (Non-blocking)
+
+- `Marketplace has no plugins defined`: Add at least one plugin to `plugins` array
+- `No marketplace description provided`: Add `metadata.description`
+- `Plugin "x" uses npm source...`: Use `github` or local path sources instead
+
+## Plugin Installation Failures
+
+**Symptoms:** Marketplace appears but installation fails
+
+**Solutions:**
+- Verify plugin source URLs are accessible
+- Check plugin directories contain required files
+- For GitHub sources, ensure repos are public or you have access
+- Test plugin sources manually by cloning/downloading
+
+## Private Repository Authentication Fails
+
+### Manual Installation
+
+- Verify authentication: `gh auth status` for GitHub
+- Check credential helper: `git config --global credential.helper`
+- Try cloning repository manually
+
+### Background Auto-Updates
+
+- Verify token set: `echo $GITHUB_TOKEN`
+- Check token permissions (read access to repository)
+- GitHub: ensure `repo` scope for private repos
+- GitLab: ensure at least `read_repository` scope
+- Verify token not expired
+
+## Relative Paths Fail in URL-based Marketplaces
+
+**Symptoms:** Added via URL (like `https://example.com/marketplace.json`), plugins with `"./plugins/my-plugin"` fail with "path not found"
+
+**Cause:** URL-based marketplaces only download `marketplace.json` file, not plugin files.
+
+**Solutions:**
+- Use external sources (GitHub, npm, git URL) instead of relative paths:
+  ```json
+  { "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }
+  ```
+- Use Git-based marketplace (clones entire repo, relative paths work)
+
+## Files Not Found After Installation
+
+**Symptoms:** Plugin installs but references to files fail, especially files outside plugin directory
+
+**Cause:** Plugins copied to cache directory. Paths like `../shared-utils` won't work.
+
+**Solutions:**
+- Use symlinks (followed during copying)
+- Restructure so shared directory is inside plugin source path
+- Reference: Plugin caching and file resolution docs

package/skills/skill-creator/references/script-quality-criteria.md

@@ -0,0 +1,106 @@
+# Script Quality Criteria
+
+Scripts provide deterministic reliability and token efficiency.
+
+## When to Include Scripts
+
+- Same code rewritten repeatedly
+- Deterministic operations needed
+- Complex transformations
+- External tool integrations
+
+## Cross-Platform Requirements
+
+**Prefer:** Node.js or Python
+**Avoid:** Bash scripts (not well-supported on Windows)
+
+If bash required, provide Node.js/Python alternative.
+
+## Testing Requirements
+
+**Mandatory:** All scripts must have tests
+
+```bash
+# Run tests before packaging
+python -m pytest scripts/tests/
+# or
+npm test
+```
+
+Tests must pass. No skipping failed tests.
+
+## Environment Variables
+
+Respect hierarchy (first found wins):
+
+1. `process.env` (runtime)
+2. `$HOME/.claude/skills/<skill-name>/.env` (skill-specific)
+3. `$HOME/.claude/skills/.env` (shared skills)
+4. `$HOME/.claude/.env` (global)
+5. `./.claude/skills/${SKILL}/.env` (cwd)
+6. `./.claude/skills/.env` (cwd)
+7. `./.claude/.env` (cwd)
+
+**Implementation pattern (Python):**
+
+```python
+from dotenv import load_dotenv
+import os
+
+# Load in reverse order (last loaded wins if not set)
+load_dotenv('$HOME/.claude/.env')
+load_dotenv('$HOME/.claude/skills/.env')
+load_dotenv('$HOME/.claude/skills/my-skill/.env')
+load_dotenv('./.claude/skills/my-skill/.env')
+load_dotenv('./.claude/skills/.env')
+load_dotenv('./.claude/.env')
+# process.env already takes precedence
+```
+
+## Documentation Requirements
+
+### .env.example
+Show required variables without values:
+
+```
+API_KEY=
+DATABASE_URL=
+DEBUG=false
+```
+
+### requirements.txt (Python)
+Pin major versions:
+
+```
+requests>=2.28.0
+python-dotenv>=1.0.0
+```
+
+### package.json (Node.js)
+Include scripts:
+
+```json
+{
+  "scripts": {
+    "test": "jest"
+  }
+}
+```
+
+## Manual Testing
+
+Before packaging, test with real use cases:
+
+```bash
+# Example: PDF rotation script
+python scripts/rotate_pdf.py input.pdf 90 output.pdf
+```
+
+Verify output matches expectations.
+
+## Error Handling
+
+- Clear error messages
+- Graceful failures
+- No silent errors
+- Exit codes: 0 success, non-zero failure

package/skills/skill-creator/references/structure-organization-criteria.md

@@ -0,0 +1,114 @@
+# Structure & Organization Criteria
+
+Proper structure enables discovery and maintainability.
+
+## Required Directory Layout
+
+```
+.claude/skills/
+└── skill-name/
+    ├── SKILL.md          # Required, uppercase
+    ├── scripts/          # Optional: executable code
+    ├── references/       # Optional: documentation
+    └── assets/           # Optional: output resources
+```
+
+## SKILL.md Requirements
+
+**File name:** Exactly `SKILL.md` (uppercase)
+
+**YAML Frontmatter:** Required at top
+
+```yaml
+---
+name: skill-name
+description: Under 200 chars, specific triggers
+license: Optional
+version: Optional
+---
+```
+
+## Resource Directories
+
+### scripts/
+Executable code for deterministic tasks.
+
+```
+scripts/
+├── main_operation.py
+├── helper_utils.py
+├── requirements.txt
+├── .env.example
+└── tests/
+    └── test_main_operation.py
+```
+
+### references/
+Documentation loaded into context as needed.
+
+```
+references/
+├── api-documentation.md
+├── schema-definitions.md
+└── workflow-guides.md
+```
+
+### assets/
+Files used in output, not loaded into context.
+
+```
+assets/
+├── templates/
+├── images/
+└── boilerplate/
+```
+
+## File Naming
+
+**Format:** kebab-case, descriptive
+
+**Good:**
+- `api-endpoints-authentication.md`
+- `database-schema-users.md`
+- `rotate-pdf-script.py`
+
+**Bad:**
+- `docs.md` - not descriptive
+- `apiEndpoints.md` - wrong case
+- `1.md` - meaningless
+
+## Cleanup
+
+After initialization, delete unused example files:
+
+```bash
+# Remove if not needed
+rm -rf scripts/example_script.py
+rm -rf references/example_reference.md
+rm -rf assets/example_asset.txt
+```
+
+## Scope Consolidation
+
+Related topics should be combined into single skill:
+
+**Consolidate:**
+- `cloudflare` + `cloudflare-r2` + `cloudflare-workers` → `devops`
+- `mongodb` + `postgresql` → `databases`
+
+**Keep separate:**
+- Unrelated domains
+- Different tech stacks with no overlap
+
+## Validation
+
+Run packaging script to check structure:
+
+```bash
+scripts/package_skill.py <skill-path>
+```
+
+Checks:
+- SKILL.md exists
+- Valid frontmatter
+- Proper directory structure