@phuc1403/musketeer 0.7.0 → 0.9.0

package/template/.claude/skills/skill-creator/references/skill-anatomy-and-requirements.md

@@ -1,77 +1,77 @@
-# Skill Anatomy & Requirements
-
-## Directory Structure
-
-```
-.claude/skills/
-└── skill-name/
-    ├── SKILL.md          (required, <300 lines)
-    │   ├── YAML frontmatter (name, description required)
-    │   └── Markdown instructions
-    └── Bundled Resources (optional)
-        ├── scripts/      Executable code (Python/Node.js)
-        ├── references/   Docs loaded into context as needed
-        ├── agents/       Eval agent templates (grader, comparator, analyzer)
-        └── assets/       Files used in output (templates, etc.)
-```
-
-## Core Requirements
-
-- **SKILL.md:** <300 lines. Concise quick-reference guide.
-- **References:** <300 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  # optional namespace: ck: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 >300 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** (<300 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
+# Skill Anatomy & Requirements
+
+## Directory Structure
+
+```
+.claude/skills/
+└── skill-name/
+    ├── SKILL.md          (required, <300 lines)
+    │   ├── YAML frontmatter (name, description required)
+    │   └── Markdown instructions
+    └── Bundled Resources (optional)
+        ├── scripts/      Executable code (Python/Node.js)
+        ├── references/   Docs loaded into context as needed
+        ├── agents/       Eval agent templates (grader, comparator, analyzer)
+        └── assets/       Files used in output (templates, etc.)
+```
+
+## Core Requirements
+
+- **SKILL.md:** <300 lines. Concise quick-reference guide.
+- **References:** <300 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  # optional namespace: ck: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 >300 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** (<300 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/template/.claude/skills/skill-creator/references/skill-creation-workflow.md

@@ -1,151 +1,152 @@
-# Skill Creation Workflow
-
-9-step process. Follow in order; skip only with clear justification.
-
-## Step 1: Capture Intent
-
-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?"
-- "What's the expected output format?"
-- "Should we create test cases?" (recommended for objective outputs)
-
-Conclude when functionality scope is clear.
-
-## Step 2: Research
-
-Activate `/ck:docs-seeker` and `/ck: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: Write 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 300 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.
-
-### 5d: Write Pushy Description
-
-Description ≤1024 chars. Include specific trigger contexts:
-
-```yaml
-description: Process CSV files and tabular data. Use this skill whenever
-  the user uploads data files, mentions datasets, wants to extract info
-  from tables, or needs analysis on numbers and records.
-```
-
-See `references/metadata-quality-criteria.md` for examples.
-
-## Step 6: Test & Evaluate
-
-### 6a: Create Test Cases
-
-Write `evals/evals.json` with 2-3 realistic test prompts + assertions.
-See `references/eval-schemas.md` for JSON format.
-
-### 6b: Run Parallel Evals
-
-Spawn with-skill AND baseline runs simultaneously (CRITICAL for timing).
-Draft assertions while runs execute.
-
-### 6c: Grade & Aggregate
-
-- Grade outputs with grader agent (`agents/grader.md`)
-- Aggregate results: `scripts/aggregate_benchmark.py`
-- Launch viewer: `eval-viewer/generate_review.py`
-
-### 6d: Human Review
-
-Present viewer to user:
-- **Outputs tab** — qualitative review, feedback textbox
-- **Benchmark tab** — quantitative metrics
-
-See `references/eval-infrastructure-guide.md` for details.
-
-## Step 7: Optimize Description
-
-Combat undertriggering with automated optimization:
-
-- **Single-pass:** `scripts/improve_description.py` — one iteration
-- **Iterative loop:** `scripts/run_loop.py` — train/test split, convergence detection
-
-## Step 8: Package & Validate
-
-```bash
-scripts/package_skill.py <path/to/skill-folder>
-```
-
-Validates: frontmatter, naming, description, structure.
-Fix all errors, re-run until clean.
-
-## Step 9: Iterate
-
-1. Read `feedback.json` from viewer
-2. Generalize from feedback — don't overfit to test examples
-3. Keep prompts lean — remove ineffective instructions
-4. Update SKILL.md or resources
-5. Re-test (return to Step 6)
-6. Scale test set to 5-10 cases for production skills
-
-**Benchmark iteration:** Run `skillmark` CLI, review per-concept accuracy, fix gaps.
+# Skill Creation Workflow
+
+9-step process. Follow in order; skip only with clear justification.
+
+## Step 1: Capture Intent
+
+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?"
+- "What's the expected output format?"
+- "Should we create test cases?" (recommended for objective outputs)
+
+Conclude when functionality scope is clear.
+
+## Step 2: Research
+
+Activate the `/research` skill. Research:
+
+- Best practices & industry standards
+- Official library/API documentation for anything the skill wraps
+- 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: Write 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 300 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.
+
+### 5d: Write Pushy Description
+
+Description ≤1024 chars. Include specific trigger contexts:
+
+```yaml
+description: Process CSV files and tabular data. Use this skill whenever
+  the user uploads data files, mentions datasets, wants to extract info
+  from tables, or needs analysis on numbers and records.
+```
+
+See `references/metadata-quality-criteria.md` for examples.
+
+## Step 6: Test & Evaluate
+
+### 6a: Create Test Cases
+
+Write `evals/evals.json` with 2-3 realistic test prompts + assertions.
+See `references/eval-schemas.md` for JSON format.
+
+### 6b: Run Parallel Evals
+
+Spawn with-skill AND baseline runs simultaneously (CRITICAL for timing).
+Draft assertions while runs execute.
+
+### 6c: Grade & Aggregate
+
+- Grade outputs with grader agent (`agents/grader.md`)
+- Aggregate results: `scripts/aggregate_benchmark.py`
+- Launch viewer: `eval-viewer/generate_review.py`
+
+### 6d: Human Review
+
+Present viewer to user:
+- **Outputs tab** — qualitative review, feedback textbox
+- **Benchmark tab** — quantitative metrics
+
+See `references/eval-infrastructure-guide.md` for details.
+
+## Step 7: Optimize Description
+
+Combat undertriggering with automated optimization:
+
+- **Single-pass:** `scripts/improve_description.py` — one iteration
+- **Iterative loop:** `scripts/run_loop.py` — train/test split, convergence detection
+
+## Step 8: Package & Validate
+
+```bash
+scripts/package_skill.py <path/to/skill-folder>
+```
+
+Validates: frontmatter, naming, description, structure.
+Fix all errors, re-run until clean.
+
+## Step 9: Iterate
+
+1. Read `feedback.json` from viewer
+2. Generalize from feedback — don't overfit to test examples
+3. Keep prompts lean — remove ineffective instructions
+4. Update SKILL.md or resources
+5. Re-test (return to Step 6)
+6. Scale test set to 5-10 cases for production skills
+
+**Benchmark iteration:** Run `skillmark` CLI, review per-concept accuracy, fix gaps.

package/template/.claude/skills/skill-creator/references/skill-design-patterns.md

@@ -1,75 +1,75 @@
-# Skill Design Patterns
-
-Five proven patterns for structuring skills. Choose based on workflow type.
-
-## Choosing Approach: Problem-First vs Tool-First
-
-- **Problem-first:** "I need to set up a project workspace" → skill orchestrates the right calls in sequence. Users describe outcomes; skill handles tools.
-- **Tool-first:** "I have Notion MCP connected" → skill teaches optimal workflows and best practices. Users have access; skill provides expertise.
-
-## Pattern 1: Sequential Workflow Orchestration
-
-**Use when:** Multi-step processes must happen in specific order.
-
-**Key techniques:**
-- Explicit step ordering with dependencies
-- Validation at each stage
-- Rollback instructions for failures
-
-```markdown
-## Workflow: Onboard New Customer
-### Step 1: Create Account
-Call MCP tool: `create_customer` → Parameters: name, email, company
-### Step 2: Setup Payment
-Call MCP tool: `setup_payment_method` → Wait for verification
-### Step 3: Create Subscription
-Call MCP tool: `create_subscription` → Uses customer_id from Step 1
-```
-
-## Pattern 2: Multi-MCP Coordination
-
-**Use when:** Workflows span multiple services (Figma → Drive → Linear → Slack).
-
-**Key techniques:**
-- Clear phase separation
-- Data passing between MCPs
-- Validation before moving to next phase
-- Centralized error handling
-
-## Pattern 3: Iterative Refinement
-
-**Use when:** Output quality improves with iteration (reports, documents).
-
-**Key techniques:**
-- Generate initial draft → validate with script → refine → re-validate
-- Explicit quality criteria and "stop iterating" conditions
-- Bundled validation scripts for deterministic checks
-
-## Pattern 4: Context-Aware Tool Selection
-
-**Use when:** Same outcome, different tools depending on context.
-
-**Key techniques:**
-- Decision tree based on inputs (file type, size, destination)
-- Fallback options when primary tool unavailable
-- Transparency about why a tool was chosen
-
-## Pattern 5: Domain-Specific Intelligence
-
-**Use when:** Skill adds specialized knowledge beyond tool access (compliance, finance).
-
-**Key techniques:**
-- Domain rules embedded in logic (compliance checks before action)
-- Comprehensive audit trails
-- Clear governance and documentation of decisions
-
-## Use Case Categories
-
-### Category 1: Document & Asset Creation
-Creates consistent output (documents, presentations, apps, designs). Uses embedded style guides, templates, quality checklists. No external tools required.
-
-### Category 2: Workflow Automation
-Multi-step processes with consistent methodology. Uses step-by-step workflows with validation gates, templates, iterative refinement loops.
-
-### Category 3: MCP Enhancement
-Workflow guidance atop MCP tool access. Coordinates multiple MCP calls, embeds domain expertise, handles common MCP errors.
+# Skill Design Patterns
+
+Five proven patterns for structuring skills. Choose based on workflow type.
+
+## Choosing Approach: Problem-First vs Tool-First
+
+- **Problem-first:** "I need to set up a project workspace" → skill orchestrates the right calls in sequence. Users describe outcomes; skill handles tools.
+- **Tool-first:** "I have Notion MCP connected" → skill teaches optimal workflows and best practices. Users have access; skill provides expertise.
+
+## Pattern 1: Sequential Workflow Orchestration
+
+**Use when:** Multi-step processes must happen in specific order.
+
+**Key techniques:**
+- Explicit step ordering with dependencies
+- Validation at each stage
+- Rollback instructions for failures
+
+```markdown
+## Workflow: Onboard New Customer
+### Step 1: Create Account
+Call MCP tool: `create_customer` → Parameters: name, email, company
+### Step 2: Setup Payment
+Call MCP tool: `setup_payment_method` → Wait for verification
+### Step 3: Create Subscription
+Call MCP tool: `create_subscription` → Uses customer_id from Step 1
+```
+
+## Pattern 2: Multi-MCP Coordination
+
+**Use when:** Workflows span multiple services (Figma → Drive → Linear → Slack).
+
+**Key techniques:**
+- Clear phase separation
+- Data passing between MCPs
+- Validation before moving to next phase
+- Centralized error handling
+
+## Pattern 3: Iterative Refinement
+
+**Use when:** Output quality improves with iteration (reports, documents).
+
+**Key techniques:**
+- Generate initial draft → validate with script → refine → re-validate
+- Explicit quality criteria and "stop iterating" conditions
+- Bundled validation scripts for deterministic checks
+
+## Pattern 4: Context-Aware Tool Selection
+
+**Use when:** Same outcome, different tools depending on context.
+
+**Key techniques:**
+- Decision tree based on inputs (file type, size, destination)
+- Fallback options when primary tool unavailable
+- Transparency about why a tool was chosen
+
+## Pattern 5: Domain-Specific Intelligence
+
+**Use when:** Skill adds specialized knowledge beyond tool access (compliance, finance).
+
+**Key techniques:**
+- Domain rules embedded in logic (compliance checks before action)
+- Comprehensive audit trails
+- Clear governance and documentation of decisions
+
+## Use Case Categories
+
+### Category 1: Document & Asset Creation
+Creates consistent output (documents, presentations, apps, designs). Uses embedded style guides, templates, quality checklists. No external tools required.
+
+### Category 2: Workflow Automation
+Multi-step processes with consistent methodology. Uses step-by-step workflows with validation gates, templates, iterative refinement loops.
+
+### Category 3: MCP Enhancement
+Workflow guidance atop MCP tool access. Coordinates multiple MCP calls, embeds domain expertise, handles common MCP errors.