thanh-kit 2.5.0 → 2.5.2

package/templates/skills/skill-creator/references/distribution-guide.md

@@ -0,0 +1,79 @@
+# Distribution Guide
+
+## Current Distribution Model
+
+### Individual Users
+1. Download skill folder
+2. Zip the folder
+3. Upload to Claude.ai: Settings > Capabilities > Skills
+4. Or place in Claude Code skills directory: `.claude/skills/`
+
+### Organization-Level
+- Admins deploy skills workspace-wide
+- Automatic updates, centralized management
+
+### Via API
+- `/v1/skills` endpoint for managing skills programmatically
+- Add to Messages API via `container.skills` parameter
+- Version control through Claude Console
+- Works with Claude Agent SDK for custom agents
+
+| Use Case | Best Surface |
+|---|---|
+| End users interacting directly | Claude.ai / Claude Code |
+| Manual testing during development | Claude.ai / Claude Code |
+| Applications using skills programmatically | API |
+| Production deployments at scale | API |
+| Automated pipelines and agent systems | API |
+
+## Recommended Approach
+
+### 1. Host on GitHub
+- Public repo for open-source skills
+- Clear README with installation instructions (repo-level, NOT inside skill folder)
+- Example usage and screenshots
+
+### 2. Document in MCP Repo (if applicable)
+- Link to skills from MCP documentation
+- Explain value of using both together
+- Provide quick-start guide
+
+### 3. Create Installation Guide
+
+```markdown
+## Installing the [Service] Skill
+1. Download: `git clone https://github.com/company/skills`
+   Or download ZIP from Releases
+2. Install: Claude.ai > Settings > Skills > Upload skill (zipped)
+3. Enable: Toggle on the skill, ensure MCP server connected
+4. Test: Ask Claude "[trigger phrase from description]"
+```
+
+## Packaging for Distribution
+
+Run packaging script to validate and zip:
+
+```bash
+scripts/package_skill.py <path/to/skill-folder>
+scripts/package_skill.py <path/to/skill-folder> ./dist  # custom output dir
+```
+
+Validates: frontmatter, naming, description (<200 chars), structure.
+Creates: `skill-name.zip` with proper directory structure.
+
+## Plugin Marketplaces
+
+For marketplace distribution, see:
+- `plugin-marketplace-overview.md` — Concepts and workflow
+- `plugin-marketplace-schema.md` — JSON schema for marketplace.json
+- `plugin-marketplace-sources.md` — Source types (path, GitHub, git)
+- `plugin-marketplace-hosting.md` — Hosting options and auto-updates
+- `plugin-marketplace-troubleshooting.md` — Common issues
+
+## Positioning Your Skill
+
+**Focus on outcomes:**
+> "Enables teams to set up complete project workspaces in seconds instead of 30-minute manual setup."
+
+**Include MCP story (if applicable):**
+> "Our MCP server gives Claude access to your Linear projects. Our skills teach Claude your sprint planning workflow. Together: AI-powered project management."

package/templates/skills/skill-creator/references/mcp-skills-integration.md

@@ -0,0 +1,71 @@
+# MCP + Skills Integration
+
+## The Kitchen Analogy
+
+- **MCP** provides the professional kitchen: access to tools, ingredients, equipment
+- **Skills** provide the recipes: step-by-step instructions to create something valuable
+
+Together, they enable users to accomplish complex tasks without figuring out every step.
+
+## How They Work Together
+
+| MCP (Connectivity) | Skills (Knowledge) |
+|---|---|
+| Connects Claude to services (Notion, Asana, Linear) | Teaches Claude how to use services effectively |
+| Provides real-time data access and tool invocation | Captures workflows and best practices |
+| What Claude *can* do | How Claude *should* do it |
+
+## Without Skills (MCP only)
+
+- Users connect MCP but don't know what to do next
+- Support tickets: "how do I do X with your integration?"
+- Each conversation starts from scratch
+- Inconsistent results (users prompt differently)
+- Users blame connector when issue is workflow guidance
+
+## With Skills (MCP + Skills)
+
+- Pre-built workflows activate automatically
+- Consistent, reliable tool usage
+- Best practices embedded in every interaction
+- Lower learning curve for integration
+
+## Building MCP-Enhanced Skills
+
+### Key Techniques
+
+1. **Reference correct MCP tool names** — tool names are case-sensitive
+2. **Include error handling** for common MCP issues (connection refused, auth expired)
+3. **Embed domain expertise** users would otherwise need to specify each time
+4. **Coordinate multiple MCP calls** in sequence with data passing between steps
+5. **Add fallback instructions** when MCP is unavailable
+
+### Example: MCP Enhancement Skill Structure
+
+```markdown
+## Prerequisites
+- [Service] MCP server must be connected (Settings > Extensions)
+- Valid API key with [specific scopes]
+
+## Workflow: [Task Name]
+### Step 1: Fetch Context
+Call `mcp_tool_name` with parameters from user input
+### Step 2: Process
+Apply domain rules to MCP response
+### Step 3: Execute
+Call `mcp_action_tool` with processed data
+### Step 4: Verify
+Confirm action completed, report results
+
+## Troubleshooting
+If "Connection refused": verify MCP server running
+If auth error: check API key in Settings > Extensions
+```
+
+## Positioning MCP + Skills
+
+**Focus on outcomes:**
+> "The ProjectHub skill enables teams to set up complete project workspaces in seconds — instead of 30 minutes on manual setup."
+
+**Not features:**
+> ~~"The ProjectHub skill is a folder containing YAML frontmatter that calls our MCP server tools."~~

package/templates/skills/skill-creator/references/metadata-quality-criteria.md

@@ -0,0 +1,76 @@
+# Metadata Quality Criteria
+
+Metadata determines when Claude activates the skill. Poor metadata = wrong activation or missed activation.
+
+## Name Field
+
+**Format:** kebab-case, lowercase
+
+**Good Examples:**
+- `pdf-editor` - clear domain
+- `bigquery-analyst` - tool + role
+- `frontend-webapp-builder` - specific function
+
+**Bad Examples:**
+- `helper` - too generic
+- `mySkill` - wrong case
+- `pdf` - too short, unclear purpose
+
+## Description Field
+
+**Constraint:** Under 200 characters
+
+**Purpose:** Trigger automatic activation during implementation
+
+### Good Descriptions
+
+Specific, action-oriented, includes use cases:
+
+```yaml
+description: Build React/TypeScript frontends with modern patterns. Use for components, Suspense, lazy loading, performance optimization.
+```
+
+```yaml
+description: Process PDFs with rotation, splitting, merging. Use for document manipulation, page extraction, PDF conversion.
+```
+
+### Bad Descriptions
+
+Too generic or educational:
+
+```yaml
+description: A skill for working with databases.  # Too vague
+```
+
+```yaml
+description: This skill helps you understand how React works.  # Educational, not actionable
+```
+
+## Trigger Precision
+
+Description should answer: "What phrases would a user say that should trigger this skill?"
+
+**Example for `image-editor` skill:**
+- "Remove red-eye from this image"
+- "Rotate this photo 90 degrees"
+- "Crop the background out"
+
+Include these trigger phrases/actions in description.
+
+## Third-Person Style
+
+**Correct:** "This skill should be used when..."
+**Wrong:** "Use this skill when..." or "You should use this..."
+
+## Validation
+
+Check with packaging script:
+
+```bash
+scripts/package_skill.py <skill-path>
+```
+
+Fails if:
+- Missing name or description
+- Description exceeds 200 characters
+- Invalid YAML syntax

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

@@ -0,0 +1,104 @@
+# Plugin Marketplace Hosting & Distribution
+
+## GitHub (Recommended)
+
+1. Create repository for marketplace
+2. Add `.claude-plugin/marketplace.json` with plugin definitions
+3. Share: users add via `/plugin marketplace add owner/repo`
+
+Benefits: version control, issue tracking, team collaboration.
+
+## Other Git Services (GitLab, Bitbucket, Self-Hosted)
+
+```shell
+/plugin marketplace add https://gitlab.com/company/plugins.git
+```
+
+## Private Repositories
+
+### Manual Install/Update
+Uses existing git credential helpers. If `git clone` works in terminal, it works in Claude Code.
+Common helpers: `gh auth login` (GitHub), macOS Keychain, `git-credential-store`.
+
+### Background Auto-Updates
+Runs at startup without credential helpers. Set auth tokens in environment:
+
+| Provider | Env Variables | Notes |
+|----------|--------------|-------|
+| GitHub | `GITHUB_TOKEN` or `GH_TOKEN` | PAT or GitHub App token |
+| GitLab | `GITLAB_TOKEN` or `GL_TOKEN` | PAT or project token |
+| Bitbucket | `BITBUCKET_TOKEN` | App password or repo token |
+
+```bash
+export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
+```
+
+CI/CD: configure as secret env variable. GitHub Actions auto-provides `GITHUB_TOKEN`.
+
+## Team Configuration
+
+### Auto-Prompt Marketplace Install
+
+Add to `.claude/settings.json` in your repo:
+
+```json
+{
+  "extraKnownMarketplaces": {
+    "company-tools": {
+      "source": { "source": "github", "repo": "your-org/claude-plugins" }
+    }
+  }
+}
+```
+
+### Default-Enabled Plugins
+
+```json
+{
+  "enabledPlugins": {
+    "code-formatter@company-tools": true,
+    "deployment-tools@company-tools": true
+  }
+}
+```
+
+## Managed Marketplace Restrictions
+
+Admins restrict allowed marketplaces via `strictKnownMarketplaces` in managed settings:
+
+| Value | Behavior |
+|-------|----------|
+| Undefined | No restrictions, users add any marketplace |
+| Empty `[]` | Complete lockdown, no new marketplaces |
+| List of sources | Users can only add matching marketplaces |
+
+### Allow Specific Only
+
+```json
+{
+  "strictKnownMarketplaces": [
+    { "source": "github", "repo": "acme-corp/approved-plugins" },
+    { "source": "github", "repo": "acme-corp/security-tools", "ref": "v2.0" },
+    { "source": "url", "url": "https://plugins.example.com/marketplace.json" }
+  ]
+}
+```
+
+### Allow All from Internal Server (Regex)
+
+```json
+{
+  "strictKnownMarketplaces": [
+    { "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }
+  ]
+}
+```
+
+**Matching rules:** Exact match for most types. GitHub: `repo` required, `ref`/`path` must match if specified. URL: full URL exact match. `hostPattern`: regex against host. Validated before any network/filesystem ops. Cannot be overridden by user/project settings.
+
+## Local Testing
+
+```shell
+/plugin marketplace add ./my-local-marketplace
+/plugin install test-plugin@my-local-marketplace
+```

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

@@ -0,0 +1,89 @@
+# Plugin Marketplaces Overview
+
+Plugin marketplace = catalog distributing Claude Code extensions across teams/communities.
+Provides centralized discovery, version tracking, automatic updates, multiple source types.
+
+## Creation & Distribution Flow
+
+1. **Create plugins** — commands, agents, hooks, MCP servers, LSP servers (see [Plugins docs](https://code.claude.com/docs/en/plugins.md))
+2. **Create marketplace file** — `.claude-plugin/marketplace.json` listing plugins + sources
+3. **Host marketplace** — push to GitHub/GitLab/git host
+4. **Share** — users add via `/plugin marketplace add`, install via `/plugin install`
+
+Updates: push changes to repo → users refresh via `/plugin marketplace update`.
+
+## Directory Structure
+
+```
+my-marketplace/
+├── .claude-plugin/
+│   └── marketplace.json        # Marketplace catalog (required)
+└── plugins/
+    └── review-plugin/
+        ├── .claude-plugin/
+        │   └── plugin.json     # Plugin manifest
+        └── skills/
+            └── review/
+                └── SKILL.md    # Skill definition
+```
+
+## Walkthrough: Local Marketplace
+
+```bash
+# 1. Create structure
+mkdir -p my-marketplace/.claude-plugin
+mkdir -p my-marketplace/plugins/review-plugin/.claude-plugin
+mkdir -p my-marketplace/plugins/review-plugin/skills/review
+
+# 2. Create skill (SKILL.md), plugin manifest (plugin.json), marketplace catalog (marketplace.json)
+
+# 3. Add and install
+/plugin marketplace add ./my-marketplace
+/plugin install review-plugin@my-plugins
+
+# 4. Test
+/review
+```
+
+## Plugin Installation Behavior
+
+Plugins copied to cache location on install. Cannot reference files outside plugin directory with `../`.
+Workarounds: symlinks (followed during copying) or restructure so shared files are inside plugin source path.
+
+## User Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/plugin marketplace add <source>` | Add marketplace |
+| `/plugin marketplace update` | Refresh marketplace |
+| `/plugin install <name>@<marketplace>` | Install plugin |
+| `/plugin validate .` | Validate marketplace JSON |
+| `claude plugin validate .` | CLI validation |
+
+## Validation & Testing
+
+```bash
+# Validate marketplace JSON
+claude plugin validate .
+# or within Claude Code:
+/plugin validate .
+
+# Test locally before distribution
+/plugin marketplace add ./my-local-marketplace
+/plugin install test-plugin@my-local-marketplace
+```
+
+## Related References
+
+- **Schema:** `references/plugin-marketplace-schema.md`
+- **Sources:** `references/plugin-marketplace-sources.md`
+- **Hosting:** `references/plugin-marketplace-hosting.md`
+- **Troubleshooting:** `references/plugin-marketplace-troubleshooting.md`
+
+## Official Documentation
+
+- [Plugin Marketplaces](https://code.claude.com/docs/en/plugin-marketplaces.md)
+- [Discover Plugins](https://code.claude.com/docs/en/discover-plugins.md)
+- [Create Plugins](https://code.claude.com/docs/en/plugins.md)
+- [Plugins Reference](https://code.claude.com/docs/en/plugins-reference.md)
+- [Plugin Settings](https://code.claude.com/docs/en/settings.md#plugin-settings)

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

@@ -0,0 +1,93 @@
+# Plugin Marketplace Schema
+
+Full JSON schema for `.claude-plugin/marketplace.json`.
+
+## Required Top-Level Fields
+
+| Field | Type | Description | Example |
+|-------|------|-------------|---------|
+| `name` | string | Marketplace ID (kebab-case, no spaces). Users see: `/plugin install tool@name` | `"acme-tools"` |
+| `owner` | object | Maintainer info (`name` required, `email` optional) | |
+| `plugins` | array | List of plugin entries | |
+
+### 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 dir prepended to relative source paths (e.g., `"./plugins"`) |
+
+## Plugin Entry — Required Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Plugin ID (kebab-case). Users see: `/plugin install name@marketplace` |
+| `source` | string\|object | Where to fetch plugin (see `plugin-marketplace-sources.md`) |
+
+## Plugin Entry — Optional Metadata
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `description` | string | Brief plugin description |
+| `version` | string | Plugin version |
+| `author` | object | Author info (`name` required, `email` optional) |
+| `homepage` | string | Plugin docs URL |
+| `repository` | string | Source code URL |
+| `license` | string | SPDX license ID (MIT, Apache-2.0) |
+| `keywords` | array | Discovery/categorization tags |
+| `category` | string | Plugin category |
+| `tags` | array | Searchability tags |
+| `strict` | boolean | Default `true`: merges with plugin.json. `false`: marketplace entry defines plugin entirely |
+
+## Plugin Entry — Component Configuration
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `commands` | string\|array | Custom paths to command files/dirs |
+| `agents` | string\|array | Custom paths to agent files |
+| `hooks` | string\|object | Hooks config or path to hooks file |
+| `mcpServers` | string\|object | MCP server configs or path |
+| `lspServers` | string\|object | LSP server configs or path |
+
+## Minimal Example
+
+```json
+{
+  "name": "my-plugins",
+  "owner": { "name": "Your Name" },
+  "plugins": [{
+    "name": "review-plugin",
+    "source": "./plugins/review-plugin",
+    "description": "Adds a /review skill for quick code reviews"
+  }]
+}
+```
+
+## Full Example
+
+```json
+{
+  "name": "company-tools",
+  "owner": { "name": "DevTools Team", "email": "devtools@example.com" },
+  "metadata": { "description": "Internal dev tools", "version": "1.0.0", "pluginRoot": "./plugins" },
+  "plugins": [
+    {
+      "name": "code-formatter",
+      "source": "./plugins/formatter",
+      "description": "Automatic code formatting on save",
+      "version": "2.1.0",
+      "author": { "name": "DevTools Team" }
+    },
+    {
+      "name": "deployment-tools",
+      "source": { "source": "github", "repo": "company/deploy-plugin" },
+      "description": "Deployment automation tools"
+    }
+  ]
+}
+```

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

@@ -0,0 +1,103 @@
+# Plugin Marketplace Sources
+
+Plugin source types for `marketplace.json` plugin entries.
+
+## Relative Paths (Same Repo)
+
+```json
+{ "name": "my-plugin", "source": "./plugins/my-plugin" }
+```
+
+**Note:** Only works when marketplace added via Git (GitHub/GitLab/git URL). URL-based marketplaces only download `marketplace.json`, not plugin files. Use GitHub/git sources for URL-based distribution.
+
+## GitHub Repositories
+
+```json
+{
+  "name": "github-plugin",
+  "source": { "source": "github", "repo": "owner/plugin-repo" }
+}
+```
+
+Pin to specific version:
+```json
+{
+  "name": "github-plugin",
+  "source": {
+    "source": "github",
+    "repo": "owner/plugin-repo",
+    "ref": "v2.0.0",
+    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
+  }
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `repo` | string | Required. `owner/repo` format |
+| `ref` | string | Optional. Branch or tag (defaults to repo default) |
+| `sha` | string | Optional. Full 40-char commit SHA for exact pinning |
+
+## Git Repositories (GitLab, Bitbucket, etc.)
+
+```json
+{
+  "name": "git-plugin",
+  "source": { "source": "url", "url": "https://gitlab.com/team/plugin.git" }
+}
+```
+
+Pin to specific version:
+```json
+{
+  "name": "git-plugin",
+  "source": {
+    "source": "url",
+    "url": "https://gitlab.com/team/plugin.git",
+    "ref": "main",
+    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
+  }
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `url` | string | Required. Full git URL (must end `.git`) |
+| `ref` | string | Optional. Branch or tag |
+| `sha` | string | Optional. Full 40-char commit SHA |
+
+## Advanced Example (All Features)
+
+```json
+{
+  "name": "enterprise-tools",
+  "source": { "source": "github", "repo": "company/enterprise-plugin" },
+  "description": "Enterprise workflow automation tools",
+  "version": "2.1.0",
+  "author": { "name": "Enterprise Team", "email": "enterprise@example.com" },
+  "homepage": "https://docs.example.com/plugins/enterprise-tools",
+  "license": "MIT",
+  "keywords": ["enterprise", "workflow", "automation"],
+  "category": "productivity",
+  "commands": ["./commands/core/", "./commands/enterprise/"],
+  "agents": ["./agents/security-reviewer.md", "./agents/compliance-checker.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 notes:**
+- `${CLAUDE_PLUGIN_ROOT}` — references files within plugin's installation cache directory
+- `strict: false` — marketplace entry defines plugin entirely, no `plugin.json` needed
+- `commands`/`agents` — multiple directories or individual files, paths relative to plugin root

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

@@ -0,0 +1,76 @@
+# Plugin Marketplace Troubleshooting
+
+## Marketplace Not Loading
+
+**Symptoms:** Can't add marketplace or see plugins.
+
+**Checklist:**
+- Marketplace URL accessible?
+- `.claude-plugin/marketplace.json` exists at specified path?
+- JSON syntax valid? Run `claude plugin validate .` or `/plugin validate .`
+- Private repo — do you have access permissions?
+
+## Validation Errors
+
+Run `claude plugin validate .` from marketplace directory. Common errors:
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `File not found: .claude-plugin/marketplace.json` | Missing manifest | Create with required fields |
+| `Invalid JSON syntax: Unexpected token...` | JSON syntax error | Fix commas, quotes, brackets |
+| `Duplicate plugin name "x"` | Two plugins share name | Give unique `name` values |
+| `plugins[0].source: Path traversal not allowed` | Source contains `..` | Use paths relative to root, no `..` |
+
+**Warnings (non-blocking):**
+- `Marketplace has no plugins defined` — add plugins to array
+- `No marketplace description provided` — add `metadata.description`
+- `Plugin "x" uses npm source` — npm not fully implemented, use github/local
+
+## Plugin Installation Failures
+
+**Symptoms:** Marketplace appears but install fails.
+
+**Checklist:**
+- Plugin source URLs accessible?
+- Plugin directories contain required files?
+- GitHub sources — repos public or you have access?
+- Test manually by cloning/downloading source
+
+## Private Repository Auth Fails
+
+### Manual Install/Update
+- Authenticated with git provider? `gh auth status` for GitHub
+- Credential helper configured? `git config --global credential.helper`
+- Can you clone repo manually?
+
+### Background Auto-Updates
+- Token set in environment? `echo $GITHUB_TOKEN`
+- Token has required permissions?
+  - GitHub: `repo` scope for private repos
+  - GitLab: `read_repository` scope minimum
+- Token not expired?
+
+## Relative Paths Fail in URL-Based Marketplaces
+
+**Symptoms:** Added marketplace via URL, plugins with `"./plugins/my-plugin"` source fail.
+
+**Cause:** URL-based marketplaces only download `marketplace.json`, not plugin files. Relative paths reference files on remote server that weren't downloaded.
+
+**Fixes:**
+1. **Use external sources:**
+   ```json
+   { "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }
+   ```
+2. **Use Git-based marketplace:** Host in Git repo, add via git URL. Clones entire repo, relative paths work.
+
+## Files Not Found After Installation
+
+**Symptoms:** Plugin installs but file references fail, especially outside plugin directory.
+
+**Cause:** Plugins copied to cache directory, not used in-place. Paths like `../shared-utils` won't work.
+
+**Fixes:**
+- Use symlinks (followed during copying)
+- Restructure so shared directory is inside plugin source path
+- Use `${CLAUDE_PLUGIN_ROOT}` in hooks/MCP configs for cache-aware paths
+- See [Plugin caching docs](https://code.claude.com/docs/en/plugins-reference.md#plugin-caching-and-file-resolution)