@meyverick/agentic 5.0.2

package/skills/create-skill/evals/trigger-queries.json

@@ -0,0 +1,80 @@
+{
+  "skill_name": "create-skill",
+  "queries": [
+    {
+      "id": 1,
+      "query": "Build me a skill that processes PDFs and extracts text.",
+      "should_trigger": true
+    },
+    {
+      "id": 2,
+      "query": "I need a new agent skill for database queries.",
+      "should_trigger": true
+    },
+    {
+      "id": 3,
+      "query": "Create a skill that helps build other skills.",
+      "should_trigger": true
+    },
+    {
+      "id": 4,
+      "query": "Help me extract a reusable pattern from this workflow into a skill.",
+      "should_trigger": true
+    },
+    {
+      "id": 5,
+      "query": "Set up evaluation for my existing skill.",
+      "should_trigger": true
+    },
+    {
+      "id": 6,
+      "query": "Write a Python script to analyze data.",
+      "should_trigger": false
+    },
+    {
+      "id": 7,
+      "query": "Review this code for bugs.",
+      "should_trigger": false
+    },
+    {
+      "id": 8,
+      "query": "Create a bash script that automates deployment.",
+      "should_trigger": false
+    },
+    {
+      "id": 9,
+      "query": "Help me write documentation for my API.",
+      "should_trigger": false
+    },
+    {
+      "id": 10,
+      "query": "Fix the bug in my authentication middleware.",
+      "should_trigger": false
+    },
+    {
+      "id": 11,
+      "query": "I want to build something that helps with file processing.",
+      "should_trigger": true
+    },
+    {
+      "id": 12,
+      "query": "Make a tool for converting JSON to YAML.",
+      "should_trigger": false
+    },
+    {
+      "id": 13,
+      "query": "Design a skill for handling webhook integrations.",
+      "should_trigger": true
+    },
+    {
+      "id": 14,
+      "query": "Write unit tests for my function.",
+      "should_trigger": false
+    },
+    {
+      "id": 15,
+      "query": "Create a reusable skill from this task I just did.",
+      "should_trigger": true
+    }
+  ]
+}

package/skills/create-skill/references/antipatterns.md

@@ -0,0 +1,123 @@
+# Antipatterns
+
+16 audited failure modes from agent builds. Self-audit checklist.
+
+## A1: Phantom Tool Reference
+
+**Pattern**: Prompt mentions tool agent can't call.
+
+**BAD**: `call action_user_consumeFood` while agent tags exclude that gate.
+**GOOD**: Prompt names only tools agent actually has; cross-role requests go via delegation.
+
+## A2: Duplicated Invariant
+
+**Pattern**: Same rule copy-pasted across files AND injected at runtime.
+
+**BAD**: 24-char ID rule in 3 prompts + auto-injected.
+**GOOD**: Single source — global rules injected once; role-specific rules in one file only.
+
+## A3: Passive-Voice Triggers
+
+**Pattern**: Role-job description instead of imperative trigger.
+
+**BAD**: "You are the Mercenary. Evaluate auctions."
+**GOOD**: "When `activeAuction != null AND payout_per_damage > market_avg` → call `bid_contract`."
+
+## A4: Copy-Pasted Cheat-Sheet
+
+**Pattern**: Shared lookup list duplicated per file, each copy drifting.
+
+**BAD**: Orchestrator lists 6 procedures, analyst lists 1 — same access, different coverage.
+**GOOD**: One canonical `procedures.md`, linked/injected by both.
+
+## A5: Prose Bloat in Trigger Prompts
+
+**Pattern**: Injecting prose-style rules into a tool-gate trigger prompt.
+
+**BAD**: 21-rule style pack pasted into role file (role emits no human prose).
+**GOOD**: Style pack injected only for prose-emitting roles.
+
+## A6: Mismatched Delegation in Prompt
+
+**Pattern**: Prompt asserts delegation path runtime forbids.
+
+**BAD**: "assigned by Orchestrator OR Economist" when only orchestrator delegates.
+**GOOD**: "I receive tasks from the Orchestrator"; runtime enforces constraints.
+
+## A7: Stale-Data Trade
+
+**Pattern**: Agent acts on memory past its `stale_after` without refetching.
+
+**BAD**: Trades on a market note fetched 3h ago.
+**GOOD**: Stale flag → refetch upstream before directive.
+
+## A8: Trust-Without-Freshness
+
+**Pattern**: Verified fact trusted regardless of age.
+
+**BAD**: "It's verified, so trust the 6h-old price."
+**GOOD**: Stale overrides verified; un-staled-but-unverified still needs confirmation.
+
+## A9: Naive Context Truncation
+
+**Pattern**: `slice(last N)` discards oldest messages, including relevant tool results.
+
+**BAD**: 50-msg context → last 10.
+**GOOD**: Summarize-older + preserve recents; or move settled facts to bundles.
+
+## A10: Silent Upstream Failure
+
+**Pattern**: Upstream errors extract `data ?? body` blindly; agent acts on `null`.
+
+**BAD**: Gateway returns `{}` on 500 → bot reports success.
+**GOOD**: Schema validate; circuit breaker; skip + log + escalate.
+
+## A11: Hardcoded Fallback Credential
+
+**Pattern**: When live auth fails, code substitutes leaked session id.
+
+**BAD**: `vid` falls back to captured session token in source.
+**GOOD**: Surface auth failure; never silently substitute; never commit credentials.
+
+## A12: Infinite Delegation
+
+**Pattern**: Two agents ping-pong without depth cap.
+
+**BAD**: No recursion bound → tokens → runaway.
+**GOOD**: Depth cap on handoff (e.g., ≤3); force back to hub.
+
+## A13: One-Size-Fits-All Fragility
+
+**Pattern**: Same gating strictness for creative writer and money transfer.
+
+**BAD**: Article publisher gated like market sale.
+**GOOD**: Tier guardrails by fragility class.
+
+## A14: Single File Omnibus
+
+**Pattern**: 4000-line system prompt mixing everything.
+
+**BAD**: One omnibus per agent, copy-paste everywhere.
+**GOOD**: Persona / instructions / templates / data as separate files, loaded on demand.
+
+## A15: Vague "Professional" Success Bar
+
+**Pattern**: Quality judged by adjectives, not scores.
+
+**BAD**: Ship when prompts "look right."
+**GOOD**: Trigger pass-rate + near-miss rate + output-lint violations.
+
+## A16: Promises vs Runtime Lint Missing
+
+**Pattern**: No build-time check that prompt-named tools exist.
+
+**BAD**: Phantom tool ships to production.
+**GOOD**: Lint: every tool name in prompt ∈ runtime toolset for that agent.
+
+## Self-Audit Protocol
+
+Before declaring skill complete:
+1. Read every file
+2. For each antipattern, confirm no file exhibits it
+3. Confirm: single-source invariants, no vendor installs, no phantom tools
+4. If any violation found, fix before shipping

package/skills/create-skill/references/component-decomposition.md

@@ -0,0 +1,130 @@
+# Component Decomposition
+
+Gem-factory pattern for skill structure.
+
+## The Problem
+
+Single omnibus files (4000+ lines) mix persona, instructions, templates, and data. This creates:
+- High churn surface (everything changes together)
+- Copy-paste drift (same rule in multiple places)
+- Context bloat (agent loads everything, uses little)
+
+## The Solution
+
+Decompose into discrete components:
+
+| Component | Holds | File Shape | Churn Rate |
+|-----------|-------|------------|------------|
+| **Persona** | Identity, guiding principles | Short, stable | Low |
+| **Instructions** | Workflows, decision trees | Markdown | Medium |
+| **Templates** | Output shapes | Markdown with placeholders | High |
+| **Data** | Factual reference, config | CSV/structured | High |
+
+## Component Types
+
+### Persona (Identity)
+
+Who the skill is. Stable, rarely changes.
+
+```markdown
+# persona.md
+
+You are a data analyst specializing in CSV processing.
+Your goal is to help users understand their tabular data.
+You prefer clarity over cleverness.
+```
+
+### Instructions (Workflows)
+
+How the skill works. Changes when process changes.
+
+```markdown
+# instructions.md
+
+## Workflow
+
+1. Load data file
+2. Validate schema
+3. Compute statistics
+4. Generate output
+```
+
+### Templates (Output Shapes)
+
+What the skill produces. Changes when format changes.
+
+```markdown
+# templates/report.md
+
+# Analysis Report
+
+## Summary
+{{summary}}
+
+## Key Findings
+{{findings}}
+
+## Recommendations
+{{recommendations}}
+```
+
+### Data (Reference Material)
+
+Factual reference. Changes when facts change.
+
+```csv
+# data/schema.csv
+column,type,required
+id,integer,yes
+name,string,yes
+email,string,no
+created_at,timestamp,yes
+```
+
+## File Structure
+
+```
+skill-name/
+├── SKILL.md              # Entry point, links to components
+├── persona.md            # Identity (optional, can be in SKILL.md)
+├── instructions/         # Workflows
+│   ├── workflow.md
+│   └── decision-tree.md
+├── templates/            # Output shapes
+│   ├── report.md
+│   └── email.md
+├── data/                 # Reference material
+│   ├── schema.csv
+│   └── examples.json
+├── scripts/              # Executable logic
+│   └── process.mjs
+└── references/           # Detailed docs
+    └── api-reference.md
+```
+
+## Single Source Per Invariant
+
+**Rule**: Define each rule ONCE, reference it everywhere else.
+
+Bad:
+- `workflow.md`: "User IDs are 24-char hex"
+- `validation.md`: "User IDs are 24-char hex"
+- `api-rules.md`: "User IDs are 24-char hex"
+
+Good:
+- `api-rules.md`: "User IDs are 24-char hex"
+- `workflow.md`: "See api-rules.md for ID format"
+- `validation.md`: "See api-rules.md for ID format"
+
+## When to Decompose
+
+Decompose when:
+- File exceeds 500 lines
+- Multiple concerns in one file
+- Same content appears in multiple places
+- Different parts change at different rates
+
+Don't decompose when:
+- Skill is simple (<100 lines total)
+- All content changes together
+- Decomposition adds more overhead than it saves

package/skills/create-skill/references/content-quality-criteria.md

@@ -0,0 +1,61 @@
+# Content Quality Criteria
+
+What makes good skill instructions.
+
+## Clarity
+
+- **One interpretation**: Instructions should have exactly one meaning
+- **Concrete, not abstract**: "Run `./scripts/validate.sh`" not "validate the output"
+- **Sequential steps**: Number steps when order matters
+- **Active voice**: "Check X" not "X should be checked"
+
+## Actionability
+
+- **Agent can follow without guessing**: Every step is executable
+- **Tools specified**: Name the exact tool/command to use
+- **Inputs/outputs defined**: What goes in, what comes out
+- **Error handling**: What to do when things fail
+
+## Edge Cases
+
+- **Document non-obvious behaviors**: Things the agent would get wrong without being told
+- **Input validation**: What happens with malformed input
+- **Boundary conditions**: Empty inputs, large inputs, special characters
+- **Failure modes**: Network errors, permission denied, missing files
+
+## Examples
+
+- **One canonical example**: Show the happy path clearly
+- **BAD/GOOD pairs**: Show what to avoid and what to do
+- **Real-world context**: Use realistic inputs, not "foo" and "bar"
+- **Input → Output**: Show the transformation
+
+## Gotchas
+
+- **Environment-specific facts**: Things that defy reasonable assumptions
+- **Naming inconsistencies**: Same concept, different names across systems
+- **Hidden preconditions**: What must be true before running
+- **Non-obvious side effects**: What happens beyond the obvious
+
+## Progressive Disclosure
+
+- **SKILL.md**: Core instructions, always loaded (<500 lines)
+- **references/**: Detailed docs, loaded on-demand
+- **scripts/**: Executable logic, invoked when needed
+- **assets/**: Templates and static resources
+
+## Fragility Matching
+
+| Task Type | Specificity Level | Example |
+|-----------|-------------------|---------|
+| Mutation (create/delete/modify) | Strict, step-by-step | "Run exactly this command. Do not add flags." |
+| Read-only (query/analyze) | Loose, latitude | "Query the database. Format as you see fit." |
+| Creative (prose/design) | Low specificity | "Write a summary. Follow the style guide." |
+
+## Antipatterns to Avoid
+
+- **Vague instructions**: "Handle errors appropriately"
+- **Over-specification**: "Use exactly 3 spaces for indentation"
+- **Missing context**: "Run the script" (which script?)
+- **Assumed knowledge**: "Use the standard approach" (what standard?)
+- **Copy-paste**: Same rule in multiple places (drift risk)

package/skills/create-skill/references/description-optimization.md

@@ -0,0 +1,90 @@
+# Description Optimization
+
+How to improve skill triggering through description tuning.
+
+## How Triggering Works
+
+1. **Discovery**: Agent loads `name` and `description` of all skills
+2. **Activation**: When task matches description, agent loads full SKILL.md
+3. **Execution**: Agent follows instructions
+
+Description carries the entire burden of triggering.
+
+## Writing Effective Descriptions
+
+### Principles
+
+- **Imperative phrasing**: "Use this skill when..." not "This skill does..."
+- **Focus on user intent**: What the user is trying to achieve
+- **Err on pushy**: Explicitly list contexts where skill applies
+- **Concise**: A few sentences to short paragraph
+
+### Good vs Bad
+
+Good:
+```yaml
+description: >
+  Analyze CSV and tabular data files — compute summary statistics,
+  add derived columns, generate charts, and clean messy data. Use this
+  skill when the user has a CSV, TSV, or Excel file and wants to
+  explore, transform, or visualize the data, even if they don't
+  explicitly mention "CSV" or "analysis."
+```
+
+Bad:
+```yaml
+description: Process CSV files.
+```
+
+## Trigger Test Queries
+
+Create 10-20 queries: mix of should-trigger and shouldn't-trigger.
+
+### Should-Trigger Queries
+
+- Vary phrasing (formal, casual, terse)
+- Vary explicitness (direct naming vs describing need)
+- Vary detail (terse vs context-heavy)
+- Include cases where skill helps but connection isn't obvious
+
+### Should-Not-Trigger Queries (Near-Misses)
+
+Strong negative examples share keywords but need different handling:
+- "Write a Python script that reads a CSV and uploads to Postgres" (involves CSV, but task is database ETL, not analysis)
+- "Update the formulas in my Excel budget spreadsheet" (shares spreadsheet concept, but needs Excel editing, not CSV analysis)
+
+Weak negatives (don't test anything):
+- "Write a fibonacci function" (obviously irrelevant)
+- "What's the weather today?" (no keyword overlap)
+
+## Optimization Loop
+
+1. **Evaluate** current description on train + validation sets
+2. **Identify failures** in train set only
+3. **Revise description**:
+   - Should-trigger failing → broaden scope
+   - Should-not-trigger failing → add specificity
+   - Avoid keyword overfitting → find general category
+4. **Repeat** until train set passes or plateau
+5. **Select best** by validation pass rate
+
+## Train/Validation Split
+
+- **Train set (~60%)**: Guides changes
+- **Validation set (~40%)**: Checks generalization
+
+Keep split fixed across iterations. Both sets need proportional mix of positive/negative queries.
+
+## Avoiding Overfitting
+
+- Don't add specific keywords from failed queries
+- Find the general category those queries represent
+- Try structurally different approaches when stuck
+- Stay under 1024 chars
+
+## Applying the Result
+
+1. Update `description` field in SKILL.md
+2. Verify under 1024-char limit
+3. Manual sanity check with a few prompts
+4. Optional: 5-10 fresh queries for rigorous verification

package/skills/create-skill/references/eval-methodology.md

@@ -0,0 +1,100 @@
+# Evaluation Methodology
+
+Full eval framework for skill quality assurance.
+
+## Two Eval Halves
+
+```
+┌─ TRIGGER evals ─────────────────────────────┐
+│  Does the right skill fire at the right time?│
+│  Positive cases + near-miss negatives        │
+└──────────────────────────────────────────────┘
+┌─ OUTPUT evals ───────────────────────────────┐
+│  Does the output satisfy quality rules?      │
+│  Deterministic + semantic judgment           │
+└──────────────────────────────────────────────┘
+```
+
+## Test Case Design
+
+### Positive Cases
+
+Prompts that SHOULD trigger the skill:
+- Varied phrasing (formal, casual, terse)
+- Different levels of detail
+- Realistic context (file paths, names, specifics)
+
+### Near-Miss Negatives (Critical)
+
+Prompts that should NOT trigger the skill:
+- Share keywords but need different handling
+- Similar domain but different task
+- Without these, over-firing passes silently
+
+Example for CSV analysis skill:
+- ✅ "Analyze my sales CSV and make a chart" (should trigger)
+- ❌ "Write a Python script that reads a CSV and uploads to Postgres" (near-miss: involves CSV but different task)
+
+### Assertion Writing
+
+Good assertions:
+- `"The output file is valid JSON"` — programmatically verifiable
+- `"The chart has labeled axes"` — specific and observable
+- `"The report includes at least 3 recommendations"` — countable
+
+Bad assertions:
+- `"The output is good"` — too vague
+- `"Uses exactly the phrase 'Total Revenue: $X'"` — too brittle
+
+## Grading Principles
+
+- **Require concrete evidence for PASS**: Don't give benefit of the doubt
+- **Review assertions themselves**: Are they too easy, too hard, or unverifiable?
+- **Blind comparison**: Compare outputs without revealing which version
+
+## Benchmark Computation
+
+```json
+{
+  "run_summary": {
+    "with_skill": {
+      "pass_rate": { "mean": 0.83, "stddev": 0.06 },
+      "time_seconds": { "mean": 45.0, "stddev": 12.0 },
+      "tokens": { "mean": 3800, "stddev": 400 }
+    },
+    "without_skill": {
+      "pass_rate": { "mean": 0.33, "stddev": 0.10 },
+      "time_seconds": { "mean": 32.0, "stddev": 8.0 },
+      "tokens": { "mean": 2100, "stddev": 300 }
+    },
+    "delta": {
+      "pass_rate": 0.50,
+      "time_seconds": 13.0,
+      "tokens": 1700
+    }
+  }
+}
+```
+
+## Calibration Loop
+
+```
+write prompt → run evals → analyze failures → edit prompt → re-run
+    ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
+stop when pass-rate ≥ target AND near-miss rate = 0
+```
+
+## Analysis Patterns
+
+- **Remove assertions that always pass**: They don't test anything
+- **Investigate assertions that always fail**: Are they broken?
+- **Study assertions that pass with skill but fail without**: This is where skill adds value
+- **Check outliers**: If one eval takes 3x longer, find why
+
+## Tiered Enforcement
+
+| Tier | Action | When |
+|------|--------|------|
+| deny | Block outright | Zero expected false positives |
+| warn | Flag, allow | Minor issues |
+| ask | Pause for confirmation | Ambiguous cases |

package/skills/create-skill/references/fragility-matching.md

@@ -0,0 +1,88 @@
+# Fragility Matching
+
+Match instruction specificity to task fragility.
+
+## Fragility Classification
+
+| Class | Description | Example | Specificity |
+|-------|-------------|---------|-------------|
+| **Mutation** | Creates, deletes, or modifies data | Place order, delete account, update record | Strict, step-by-step, precondition gates |
+| **Read-only** | Queries or analyzes data | Search database, generate report, analyze CSV | Loose triggers, latitude for formatting |
+| **Creative** | Prose, design, creative output | Write summary, design layout, draft email | Low specificity, examples over rules |
+
+## Mutation Tasks (Strict)
+
+When skill involves creating, deleting, or modifying data:
+
+- **Precondition gates**: Check before acting
+- **Exact commands**: "Run exactly this command. Do not add flags."
+- **Validation loops**: Verify before proceeding
+- **Rollback paths**: What to do if something fails
+- **Idempotency**: Safe to retry
+
+Example:
+```markdown
+## Place Order
+
+1. Verify inventory: `./scripts/check-inventory.sh <item-id>`
+2. ONLY if in stock: `./scripts/place-order.sh <item-id> <quantity>`
+3. Verify order: `./scripts/verify-order.sh <order-id>`
+4. NEVER skip step 1. NEVER add flags to step 2.
+```
+
+## Read-Only Tasks (Loose)
+
+When skill involves querying or analyzing data:
+
+- **Flexible triggers**: "When user asks about X"
+- **Format latitude**: "Format as you see fit"
+- **Optional steps**: "Optionally include Y"
+- **Error handling**: "If query fails, report error"
+
+Example:
+```markdown
+## Analyze Data
+
+1. Load the data file
+2. Compute summary statistics
+3. Generate visualizations as appropriate
+4. Present findings in a clear format
+```
+
+## Creative Tasks (Low Specificity)
+
+When skill involves prose, design, or creative output:
+
+- **Style guidelines**: "Follow the style guide"
+- **Examples**: Show BAD/GOOD pairs
+- **Constraints**: "Don't include X"
+- **Latitude**: Let agent decide approach
+
+Example:
+```markdown
+## Write Summary
+
+- One paragraph overview
+- Include key findings
+- Use clear, concise language
+- See references/style-guide.md for tone
+```
+
+## Fragility Matrix
+
+```
+   mutation (create/delete/modify)  ─▶ strict preconditions, gating, deterrents
+   read-only (query/analyze)        ─▶ loose triggers, free text
+   creative (prose/design)          ─▶ low specificity, examples
+
+   ⚠️ Same skill should never treat a buy-button with the looseness of a weather check
+```
+
+## Decision Guide
+
+Ask:
+1. Does this skill change state? → Mutation → Strict
+2. Does this skill only read state? → Read-only → Loose
+3. Does this skill produce creative output? → Creative → Low specificity
+
+When uncertain, default to stricter. Can always loosen later.