@hienlh/ppm 0.9.80 → 0.9.81

package/.opencode/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/.opencode/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/.opencode/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/.opencode/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)

package/.opencode/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/.opencode/skills/<skill-name>/.env` (skill-specific)
+3. `$HOME/.opencode/skills/.env` (shared skills)
+4. `$HOME/.opencode/.env` (global)
+5. `./.opencode/skills/${SKILL}/.env` (cwd)
+6. `./.opencode/skills/.env` (cwd)
+7. `./.opencode/.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/.opencode/.env')
+load_dotenv('$HOME/.opencode/skills/.env')
+load_dotenv('$HOME/.opencode/skills/my-skill/.env')
+load_dotenv('./.opencode/skills/my-skill/.env')
+load_dotenv('./.opencode/skills/.env')
+load_dotenv('./.opencode/.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/.opencode/skills/skill-creator/references/skill-anatomy-and-requirements.md

@@ -0,0 +1,76 @@
+# Skill Anatomy & Requirements
+
+## Directory Structure
+
+```
+.opencode/skills/
+└── skill-name/
+    ├── SKILL.md          (required, <150 lines)
+    │   ├── YAML frontmatter (name, description required)
+    │   └── Markdown instructions
+    └── Bundled Resources (optional)
+        ├── scripts/      Executable code (Python/Node.js)
+        ├── references/   Docs loaded into context as needed
+        └── assets/       Files used in output (templates, etc.)
+```
+
+## Core Requirements
+
+- **SKILL.md:** <150 lines. Concise quick-reference guide.
+- **References:** <150 lines each. Split by logical boundaries.
+- **Scripts:** No length limit. Must have tests. Must work cross-platform.
+- **Description:** <200 chars. Specific triggers, not generic.
+- **Consolidation:** Related topics combined (e.g., cloudflare+docker → devops)
+- **No duplication:** Info lives in ONE place (SKILL.md OR references, not both)
+
+## SKILL.md Frontmatter
+
+```yaml
+---
+name: kebab-case-name
+description: Under 200 chars, specific triggers and use cases
+license: Optional
+version: Optional
+---
+```
+
+**Metadata quality** determines auto-activation. See `references/metadata-quality-criteria.md`.
+
+## Scripts (`scripts/`)
+
+- Deterministic code for repeated tasks
+- **Prefer:** Python or Node.js (Windows-compatible)
+- **Avoid:** Bash scripts
+- **Required:** Tests that pass, `.env.example`, `requirements.txt`/`package.json`
+- **Env hierarchy:** `process.env` > skill `.env` > shared `.env` > global `.env`
+- Token-efficient: executed without loading into context
+
+See `references/script-quality-criteria.md` for full criteria.
+
+## References (`references/`)
+
+- Documentation loaded as-needed into context
+- Use cases: schemas, APIs, workflows, cheatsheets, domain knowledge
+- **Best practice:** Split >150 lines into multiple files
+- Include grep patterns in SKILL.md for discoverability
+- Practical instructions, not educational documentation
+
+## Assets (`assets/`)
+
+- Files used in output, NOT loaded into context
+- Use cases: templates, images, icons, boilerplate, fonts
+- Separates output resources from documentation
+
+## Progressive Disclosure
+
+Three-level loading for context efficiency:
+1. **Metadata** (~200 chars) — always in context
+2. **SKILL.md body** (<150 lines) — when skill triggers
+3. **Bundled resources** — as needed (scripts: unlimited, execute without loading)
+
+## Writing Style
+
+- **Imperative form:** "To accomplish X, do Y"
+- **Third-person metadata:** "This skill should be used when..."
+- **Concise:** Sacrifice grammar for brevity in references
+- **Practical:** Teach *how* to do tasks, not *what* tools are

package/.opencode/skills/skill-creator/references/skill-creation-workflow.md

@@ -0,0 +1,95 @@
+# Skill Creation Workflow
+
+7-step process. Follow in order; skip only with clear justification.
+
+## Step 1: Understand with Concrete Examples
+
+Gather real usage patterns via `AskUserQuestion` tool:
+- "What tasks should this skill handle?"
+- "Give examples of how it would be used?"
+- "What phrases should trigger this skill?"
+
+Conclude when functionality scope is clear.
+
+## Step 2: Research
+
+Activate `/docs-seeker` and `/research` skills. Research:
+- Best practices & industry standards
+- Existing CLI tools (`npx`, `bunx`, `pipx`) for reuse
+- Workflows & case studies
+- Edge cases & pitfalls
+
+Use parallel `WebFetch` + `Explore` subagents for multiple URLs.
+Write reports for next step.
+
+## Step 3: Plan Reusable Contents
+
+Analyze each example:
+1. How to execute from scratch?
+2. Prefer existing CLI tools over custom code
+3. What scripts/references/assets enable repeated execution?
+4. Check skills catalog — avoid duplication, reuse existing
+
+**Patterns:**
+- Repeated code → `scripts/` (Python/Node.js, with tests)
+- Repeated discovery → `references/` (schemas, docs, APIs)
+- Repeated boilerplate → `assets/` (templates, images)
+
+Scripts MUST: respect `.env` hierarchy, have tests, pass all tests.
+
+## Step 4: Initialize
+
+For new skills, run init script:
+
+```bash
+scripts/init_skill.py <skill-name> --path <output-directory>
+```
+
+Creates: SKILL.md template, `scripts/`, `references/`, `assets/` with examples.
+Skip if skill already exists (go to Step 5).
+
+## Step 5: Edit the Skill
+
+### 5a: Implement Resources
+Start with `scripts/`, `references/`, `assets/` identified in Step 3.
+Delete unused example files from initialization.
+May require user input (brand assets, configs, etc.).
+
+### 5b: Write SKILL.md
+
+**Writing style:** Imperative/infinitive form. "To accomplish X, do Y."
+**Size:** Under 150 lines. Move details to `references/`.
+
+Answer these in SKILL.md:
+1. Purpose (2-3 sentences)
+2. When to use (trigger conditions)
+3. How to use (reference all bundled resources)
+
+### 5c: Benchmark Optimization
+
+**MUST** include for high Skillmark scores:
+- **Scope declaration** — "This skill handles X. Does NOT handle Y."
+- **Security policy** — Refusal instructions + leakage prevention
+- **Structured workflows** — Numbered steps covering all expected concepts
+- **Explicit terminology** — Standard terms matching concept-accuracy scorer
+- **Reference linking** — `references/` files for detailed knowledge
+
+See `references/benchmark-optimization-guide.md` for detailed patterns.
+
+## Step 6: Package & Validate
+
+```bash
+scripts/package_skill.py <path/to/skill-folder>
+```
+
+Validates: frontmatter, naming, description (<200 chars), structure.
+Fix all errors, re-run until clean.
+
+## Step 7: Iterate
+
+1. Test skill on real tasks
+2. Note struggles, token usage, accuracy gaps
+3. Update SKILL.md or resources
+4. Re-test and re-package
+
+**Benchmark iteration:** Run `skillmark` CLI against skill, review per-concept accuracy, fix gaps in instructions that cause missed concepts.