@hienlh/ppm 0.9.81 → 0.9.83

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

@@ -1,89 +0,0 @@
-# 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

@@ -1,93 +0,0 @@
-# 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

@@ -1,103 +0,0 @@
-# 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

@@ -1,76 +0,0 @@
-# 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

@@ -1,106 +0,0 @@
-# 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

@@ -1,76 +0,0 @@
-# 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

@@ -1,95 +0,0 @@
-# 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.