@nano-step/skill-manager 5.0.1 → 5.2.0

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

package/skills/skill-creator/references/token-efficiency-criteria.md

@@ -0,0 +1,74 @@
+# Token Efficiency Criteria
+
+Skills use progressive disclosure to minimize context window usage.
+
+## Three-Level Loading
+
+1. **Metadata** - Always loaded (~200 chars)
+2. **SKILL.md body** - Loaded when skill triggers (<150 lines)
+3. **Bundled resources** - Loaded as needed (unlimited for scripts)
+
+## Size Limits
+
+| Resource | Limit | Notes |
+|----------|-------|-------|
+| Description | <200 chars | In YAML frontmatter |
+| SKILL.md | <150 lines | Core instructions only |
+| Each reference file | <150 lines | Split if larger |
+| Scripts | No limit | Executed, not loaded into context |
+
+## SKILL.md Content Strategy
+
+**Include in SKILL.md:**
+- Purpose (2-3 sentences)
+- When to use (trigger conditions)
+- Quick reference for common workflows
+- Pointers to resources (scripts, references, assets)
+
+**Move to references/:**
+- Detailed documentation
+- Database schemas
+- API specs
+- Step-by-step guides
+- Examples and templates
+- Best practices
+
+## No Duplication Rule
+
+Information lives in ONE place:
+- Either in SKILL.md
+- Or in references/
+
+**Bad:** Schema overview in SKILL.md + detailed schema in references/schema.md
+**Good:** Brief mention in SKILL.md + full schema only in references/schema.md
+
+## Splitting Large Files
+
+If reference exceeds 150 lines, split by logical boundaries:
+
+```
+references/
+├── api-endpoints-auth.md      # Auth endpoints
+├── api-endpoints-users.md     # User endpoints
+├── api-endpoints-payments.md  # Payment endpoints
+```
+
+Include grep patterns in SKILL.md for discoverability:
+
+```markdown
+## API Documentation
+- Auth: `references/api-endpoints-auth.md`
+- Users: `references/api-endpoints-users.md`
+- Payments: `references/api-endpoints-payments.md`
+```
+
+## Scripts: Best Token Efficiency
+
+Scripts execute without loading into context.
+
+**When to use scripts:**
+- Repetitive code patterns
+- Deterministic operations
+- Complex transformations
+
+**Example:** PDF rotation via `scripts/rotate_pdf.py` vs rewriting rotation code each time.

package/skills/skill-creator/references/validation-checklist.md

@@ -0,0 +1,83 @@
+# Skill Validation Checklist
+
+Quick validation before packaging. Run `scripts/package_skill.py` for automated checks.
+
+## Critical (Must Pass)
+
+### Metadata
+- [ ] `name`: kebab-case, descriptive
+- [ ] `description`: under 200 characters, specific triggers, not generic
+
+### Size Limits
+- [ ] SKILL.md: under 150 lines
+- [ ] Each reference file: under 150 lines
+- [ ] No info duplication between SKILL.md and references
+
+### Structure
+- [ ] SKILL.md exists with valid YAML frontmatter
+- [ ] Unused example files deleted
+- [ ] File names: kebab-case, self-documenting
+
+## Scripts (If Applicable)
+
+- [ ] Tests exist and pass
+- [ ] Cross-platform (Node.js/Python preferred)
+- [ ] Env vars: respects hierarchy `process.env` > `$HOME/.claude/skills/${SKILL}/.env` (global) > `$HOME/.claude/skills/.env` (global) > `$HOME/.claude/.env` (global) > `./.claude/skills/${SKILL}/.env` (cwd) > `./.claude/skills/.env` (cwd) > `./.claude/.env` (cwd)
+- [ ] Dependencies documented (requirements.txt, .env.example)
+- [ ] Manually tested with real use cases
+
+## Quality
+
+### Writing Style
+- [ ] Imperative form: "To accomplish X, do Y"
+- [ ] Third-person metadata: "This skill should be used when..."
+- [ ] Concise, no fluff
+
+### Practical Utility
+- [ ] Teaches *how* to do tasks, not *what* tools are
+- [ ] Based on real workflows
+- [ ] Includes concrete trigger phrases/examples
+
+## Integration
+
+- [ ] No duplication with existing skills
+- [ ] Related topics consolidated (e.g., cloudflare + docker → devops)
+- [ ] Composable with other skills
+
+## Automated Validation
+
+Run packaging script to validate:
+
+```bash
+scripts/package_skill.py <path/to/skill-folder>
+```
+
+Checks performed:
+- YAML frontmatter format
+- Required fields present
+- Description length (<200 chars)
+- Directory structure
+- File organization
+
+Fix all errors before distributing.
+
+## Subagent Delegation Enforcement
+
+When a skill requires subagent delegation (via Task tool):
+
+1. **Use MUST language** - "Use subagent" is weak; "MUST spawn subagent" is enforceable
+2. **Include Task pattern** - Show exact syntax: `Task(subagent_type="X", prompt="Y", description="Z")`
+3. **Add validation rule** - "If Task tool calls = 0 at end, workflow is INCOMPLETE"
+4. **Mark requirements clearly** - Use table with "MUST spawn" column
+5. **Forbid direct implementation** - "DO NOT implement X yourself - DELEGATE to subagent"
+
+**Anti-pattern (weak):**
+```
+- Use `tester` agent for testing
+```
+
+**Correct pattern (enforceable):**
+```
+- **MUST** spawn `tester` subagent: `Task(subagent_type="tester", prompt="Run tests", description="Test")`
+- DO NOT run tests yourself - DELEGATE
+```

package/skills/skill-creator/scripts/encoding_utils.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+"""
+Cross-platform encoding utilities for Windows compatibility.
+
+Fixes UnicodeEncodeError on Windows by reconfiguring stdout/stderr to UTF-8
+and providing encoding-aware file I/O helpers.
+"""
+
+import sys
+from pathlib import Path
+
+
+def configure_utf8_console():
+    """
+    Reconfigure stdout/stderr for UTF-8 on Windows.
+
+    Windows uses cp1252 by default which cannot encode Unicode emojis.
+    This function switches to UTF-8 with 'replace' error handling to
+    prevent crashes on truly incompatible terminals.
+    """
+    if sys.platform == 'win32':
+        try:
+            sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+            sys.stderr.reconfigure(encoding='utf-8', errors='replace')
+        except AttributeError:
+            pass  # Python < 3.7
+
+
+def read_text_utf8(path: Path) -> str:
+    """Read file with explicit UTF-8 encoding."""
+    return path.read_text(encoding='utf-8')
+
+
+def write_text_utf8(path: Path, content: str) -> None:
+    """Write file with explicit UTF-8 encoding."""
+    path.write_text(content, encoding='utf-8')