@phuc1403/musketeer 0.7.0 → 0.9.0

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

@@ -1,74 +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 (<300 lines)
-3. **Bundled resources** - Loaded as needed (unlimited for scripts)
-
-## Size Limits
-
-| Resource | Limit | Notes |
-|----------|-------|-------|
-| Description | <200 chars | In YAML frontmatter |
-| SKILL.md | <300 lines | Core instructions only |
-| Each reference file | <300 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 300 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.
+# 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 (<300 lines)
+3. **Bundled resources** - Loaded as needed (unlimited for scripts)
+
+## Size Limits
+
+| Resource | Limit | Notes |
+|----------|-------|-------|
+| Description | <200 chars | In YAML frontmatter |
+| SKILL.md | <300 lines | Core instructions only |
+| Each reference file | <300 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 300 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/template/.claude/skills/skill-creator/references/troubleshooting-guide.md

@@ -1,81 +1,81 @@
-# Troubleshooting Guide
-
-## Skill Won't Upload
-
-**Error: "Could not find SKILL.md in uploaded folder"**
-- Rename to exactly `SKILL.md` (case-sensitive). Verify with `ls -la`.
-
-**Error: "Invalid frontmatter"**
-- Ensure `---` delimiters on both sides
-- Check for unclosed quotes in YAML
-- Validate YAML syntax
-
-**Error: "Invalid skill name"**
-- Use either `skill-name` or `namespace:skill-name`
-- Namespace and skill id must be kebab-case (no spaces, no capitals)
-- Wrong: `My Cool Skill` → Correct: `ck:my-cool-skill`
-
-## Skill Doesn't Trigger
-
-**Symptom:** Skill never loads automatically.
-
-**Checklist:**
-- Is description too generic? ("Helps with projects" won't work)
-- Does it include trigger phrases users would actually say?
-- Does it mention relevant file types if applicable?
-
-**Debug:** Ask Claude "When would you use the [skill-name] skill?" — adjust description based on response.
-
-## Skill Triggers Too Often
-
-**Solutions:**
-
-1. **Add negative triggers:**
-   ```yaml
-   description: Advanced data analysis for CSV files. Use for statistical
-     modeling, regression. Do NOT use for simple data exploration.
-   ```
-
-2. **Be more specific:**
-   ```yaml
-   # Bad: "Processes documents"
-   # Good: "Processes PDF legal documents for contract review"
-   ```
-
-3. **Clarify scope:**
-   ```yaml
-   description: PayFlow payment processing for e-commerce. Use specifically
-     for online payment workflows, not general financial queries.
-   ```
-
-## MCP Connection Issues
-
-**Symptom:** Skill loads but MCP calls fail.
-
-1. Verify MCP server is connected (Settings > Extensions)
-2. Check API keys valid and not expired
-3. Test MCP independently: "Use [Service] MCP to fetch my projects"
-4. Verify skill references correct MCP tool names (case-sensitive)
-
-## Instructions Not Followed
-
-**Common causes and fixes:**
-
-| Cause | Fix |
-|---|---|
-| Instructions too verbose | Use bullet points, move details to references/ |
-| Critical info buried | Put at top, use `## CRITICAL` headers |
-| Ambiguous language | Replace "validate properly" with specific checklist |
-| Model skipping steps | Add "Do not skip validation steps" explicitly |
-
-**Advanced:** For critical validations, bundle a script that performs checks programmatically. Code is deterministic; language interpretation isn't.
-
-## Large Context Issues
-
-**Symptom:** Skill seems slow or responses degraded.
-
-**Solutions:**
-1. Move detailed docs to `references/` — keep SKILL.md under 300 lines
-2. Link to references instead of inlining content
-3. Evaluate if too many skills enabled simultaneously (>20-50 may degrade)
-4. Consider skill "packs" for related capabilities
+# Troubleshooting Guide
+
+## Skill Won't Upload
+
+**Error: "Could not find SKILL.md in uploaded folder"**
+- Rename to exactly `SKILL.md` (case-sensitive). Verify with `ls -la`.
+
+**Error: "Invalid frontmatter"**
+- Ensure `---` delimiters on both sides
+- Check for unclosed quotes in YAML
+- Validate YAML syntax
+
+**Error: "Invalid skill name"**
+- Use either `skill-name` or `namespace:skill-name`
+- Namespace and skill id must be kebab-case (no spaces, no capitals)
+- Wrong: `My Cool Skill` → Correct: `ck:my-cool-skill`
+
+## Skill Doesn't Trigger
+
+**Symptom:** Skill never loads automatically.
+
+**Checklist:**
+- Is description too generic? ("Helps with projects" won't work)
+- Does it include trigger phrases users would actually say?
+- Does it mention relevant file types if applicable?
+
+**Debug:** Ask Claude "When would you use the [skill-name] skill?" — adjust description based on response.
+
+## Skill Triggers Too Often
+
+**Solutions:**
+
+1. **Add negative triggers:**
+   ```yaml
+   description: Advanced data analysis for CSV files. Use for statistical
+     modeling, regression. Do NOT use for simple data exploration.
+   ```
+
+2. **Be more specific:**
+   ```yaml
+   # Bad: "Processes documents"
+   # Good: "Processes PDF legal documents for contract review"
+   ```
+
+3. **Clarify scope:**
+   ```yaml
+   description: PayFlow payment processing for e-commerce. Use specifically
+     for online payment workflows, not general financial queries.
+   ```
+
+## MCP Connection Issues
+
+**Symptom:** Skill loads but MCP calls fail.
+
+1. Verify MCP server is connected (Settings > Extensions)
+2. Check API keys valid and not expired
+3. Test MCP independently: "Use [Service] MCP to fetch my projects"
+4. Verify skill references correct MCP tool names (case-sensitive)
+
+## Instructions Not Followed
+
+**Common causes and fixes:**
+
+| Cause | Fix |
+|---|---|
+| Instructions too verbose | Use bullet points, move details to references/ |
+| Critical info buried | Put at top, use `## CRITICAL` headers |
+| Ambiguous language | Replace "validate properly" with specific checklist |
+| Model skipping steps | Add "Do not skip validation steps" explicitly |
+
+**Advanced:** For critical validations, bundle a script that performs checks programmatically. Code is deterministic; language interpretation isn't.
+
+## Large Context Issues
+
+**Symptom:** Skill seems slow or responses degraded.
+
+**Solutions:**
+1. Move detailed docs to `references/` — keep SKILL.md under 300 lines
+2. Link to references instead of inlining content
+3. Evaluate if too many skills enabled simultaneously (>20-50 may degrade)
+4. Consider skill "packs" for related capabilities

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

@@ -1,83 +1,83 @@
-# Skill Validation Checklist
-
-Quick validation before packaging. Run `scripts/package_skill.py` for automated checks.
-
-## Critical (Must Pass)
-
-### Metadata
-- [ ] `name`: namespaced `namespace:skill-name` (or `skill-name` for legacy), descriptive
-- [ ] `description`: under 200 characters, specific triggers, not generic
-
-### Size Limits
-- [ ] SKILL.md: under 300 lines
-- [ ] Each reference file: under 300 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
-```
+# Skill Validation Checklist
+
+Quick validation before packaging. Run `scripts/package_skill.py` for automated checks.
+
+## Critical (Must Pass)
+
+### Metadata
+- [ ] `name`: namespaced `namespace:skill-name` (or `skill-name` for legacy), descriptive
+- [ ] `description`: under 200 characters, specific triggers, not generic
+
+### Size Limits
+- [ ] SKILL.md: under 300 lines
+- [ ] Each reference file: under 300 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 `code-reviewer` agent for review
+```
+
+**Correct pattern (enforceable):**
+```
+- **MUST** spawn `code-reviewer` subagent: `Task(subagent_type="code-reviewer", prompt="Review the diff", description="Review")`
+- DO NOT review it yourself - DELEGATE
+```

package/template/.claude/skills/skill-creator/references/writing-effective-instructions.md

@@ -1,88 +1,88 @@
-# Writing Effective Instructions
-
-## Writing Style
-
-Write entirely in **imperative/infinitive form** (verb-first). Use objective, instructional language.
-
-- **Good:** "To accomplish X, do Y" / "Run `script.py` to validate"
-- **Bad:** "You should do X" / "If you need to do X"
-
-## Recommended SKILL.md Structure
-
-```markdown
----
-name: your-skill  # optional namespace: ck:your-skill
-description: [What + When + Key capabilities]
----
-# Skill Name
-## Instructions
-### Step 1: [First Major Step]
-Clear explanation. Example with expected output.
-### Step 2: [Next Step]
-(Continue as needed)
-## Examples
-### Example 1: [Common scenario]
-**User says:** "[trigger phrase]"
-**Actions:** 1. Do X  2. Do Y
-**Result:** [Expected outcome]
-## Troubleshooting
-**Error:** [Message] → **Solution:** [Fix]
-```
-
-## Be Specific and Actionable
-
-**Good:**
-```markdown
-Run `python scripts/validate.py --input {filename}` to check format.
-If validation fails, common issues:
-- Missing required fields (add to CSV)
-- Invalid date formats (use YYYY-MM-DD)
-```
-
-**Bad:**
-```markdown
-Validate the data before proceeding.
-```
-
-## Include Error Handling
-
-```markdown
-## Common Issues
-### MCP Connection Failed
-If "Connection refused":
-1. Verify MCP server running: Settings > Extensions
-2. Confirm API key valid
-3. Reconnect: Settings > Extensions > [Service] > Reconnect
-```
-
-## Reference Bundled Resources Clearly
-
-```markdown
-Before writing queries, consult `references/api-patterns.md` for:
-- Rate limiting guidance
-- Pagination patterns
-- Error codes and handling
-```
-
-## Use Progressive Disclosure
-
-Keep SKILL.md focused on core instructions (<300 lines). Move to `references/`:
-- Detailed API documentation
-- Database schemas
-- Extended examples
-- Domain-specific rules
-- Troubleshooting guides
-
-## Critical Instructions
-
-Put at the top of SKILL.md. Use headers like `## CRITICAL` or `## IMPORTANT`.
-Repeat key points if they're frequently missed.
-
-**Advanced technique:** For critical validations, bundle a script that performs checks programmatically rather than relying on language instructions alone. Code is deterministic; language interpretation isn't.
-
-## What NOT to Include
-
-- General knowledge Claude already has
-- Tool documentation (teach workflows, not what tools do)
-- Verbose explanations (sacrifice grammar for concision)
-- Duplicated content between SKILL.md and references
+# Writing Effective Instructions
+
+## Writing Style
+
+Write entirely in **imperative/infinitive form** (verb-first). Use objective, instructional language.
+
+- **Good:** "To accomplish X, do Y" / "Run `script.py` to validate"
+- **Bad:** "You should do X" / "If you need to do X"
+
+## Recommended SKILL.md Structure
+
+```markdown
+---
+name: your-skill  # optional namespace: ck:your-skill
+description: [What + When + Key capabilities]
+---
+# Skill Name
+## Instructions
+### Step 1: [First Major Step]
+Clear explanation. Example with expected output.
+### Step 2: [Next Step]
+(Continue as needed)
+## Examples
+### Example 1: [Common scenario]
+**User says:** "[trigger phrase]"
+**Actions:** 1. Do X  2. Do Y
+**Result:** [Expected outcome]
+## Troubleshooting
+**Error:** [Message] → **Solution:** [Fix]
+```
+
+## Be Specific and Actionable
+
+**Good:**
+```markdown
+Run `python scripts/validate.py --input {filename}` to check format.
+If validation fails, common issues:
+- Missing required fields (add to CSV)
+- Invalid date formats (use YYYY-MM-DD)
+```
+
+**Bad:**
+```markdown
+Validate the data before proceeding.
+```
+
+## Include Error Handling
+
+```markdown
+## Common Issues
+### MCP Connection Failed
+If "Connection refused":
+1. Verify MCP server running: Settings > Extensions
+2. Confirm API key valid
+3. Reconnect: Settings > Extensions > [Service] > Reconnect
+```
+
+## Reference Bundled Resources Clearly
+
+```markdown
+Before writing queries, consult `references/api-patterns.md` for:
+- Rate limiting guidance
+- Pagination patterns
+- Error codes and handling
+```
+
+## Use Progressive Disclosure
+
+Keep SKILL.md focused on core instructions (<300 lines). Move to `references/`:
+- Detailed API documentation
+- Database schemas
+- Extended examples
+- Domain-specific rules
+- Troubleshooting guides
+
+## Critical Instructions
+
+Put at the top of SKILL.md. Use headers like `## CRITICAL` or `## IMPORTANT`.
+Repeat key points if they're frequently missed.
+
+**Advanced technique:** For critical validations, bundle a script that performs checks programmatically rather than relying on language instructions alone. Code is deterministic; language interpretation isn't.
+
+## What NOT to Include
+
+- General knowledge Claude already has
+- Tool documentation (teach workflows, not what tools do)
+- Verbose explanations (sacrifice grammar for concision)
+- Duplicated content between SKILL.md and references