@runecraft/grimoire 1.0.0

package/skills/skill-forge/SKILL.md

@@ -0,0 +1,291 @@
+---
+name: skill-forge
+description: >
+  Designs, authors, validates, and optimizes new Agent Skills from scratch. Use when creating
+  a new skill, packaging a workflow as a skill, improving a skill's triggering accuracy, or
+  evaluating whether a skill improves output quality. Covers the full lifecycle: DISCOVER,
+  DESIGN, AUTHOR, VALIDATE, OPTIMIZE, DELIVER. Produces skills that follow the open
+  SKILL.md format (YAML frontmatter + Markdown body, progressive disclosure, validation loops).
+  EN triggers: /forge, create a skill, write a skill, build a skill, new skill, author a skill,
+  package this as a skill, validate a skill, improve skill triggering, optimize skill description,
+  evaluate skill quality.
+  PT triggers: /forge, criar uma skill, escrever uma skill, construir uma skill, nova skill,
+  empacotar como skill, validar skill, melhorar disparo, otimizar descrição de skill.
+  Do NOT use for: discovering which existing skill to apply (use a dispatch/meta skill),
+  planning feature implementation, or designing software architecture.
+license: CC-BY-4.0
+metadata:
+  version: 1.0.0
+---
+
+# skill-forge
+
+> Meta-skill for creating new Agent Skills from scratch. Produces publishable, validated, trigger-tested skills that compose with the rest of the catalog.
+
+```
+DISCOVER → DESIGN → AUTHOR → VALIDATE → OPTIMIZE → DELIVER
+```
+
+Each phase has explicit exit criteria. Move sequentially. Do not skip to AUTHOR before completing DISCOVER and DESIGN — bad frontmatter is the most common reason skills misfire.
+
+## Critical rules (read before acting)
+
+- **The open SKILL.md format is the source of truth.** This skill encodes the format rules (frontmatter schema, naming, progressive disclosure, folder layout). When in doubt, follow what this skill's own validator enforces — it is the single reference implementation.
+- **The description field controls triggering.** It is the only thing the agent sees at startup. Write it last but treat it as the most important field. If triggering is wrong, nothing else matters.
+- **Skills are for agents, not humans.** The `SKILL.md` body is agent instructions. Human-facing docs (README, changelogs) belong outside the skill folder.
+- **Never fabricate domain knowledge.** Build skills from real expertise — your own run history, internal docs, runbooks, schemas, code review comments. Generic "best practices" skills have no edge.
+
+---
+
+## Phase 1: DISCOVER
+
+**Goal:** Build a precise mental model of the skill before writing a single line.
+
+Ask one cluster at a time (don't dump). Capture answers in your working memory; you'll reuse them in DESIGN.
+
+### 1.1 What workflow are we packaging?
+
+- What does the user do today, step by step?
+- Where does it go wrong without the skill (inconsistency, forgotten steps, wasted re-explaining)?
+- What is the "good output" they expect (specific, observable)?
+
+### 1.2 Use cases
+
+Nail down 2-3 concrete ones:
+
+```
+Use Case: [Name]
+Trigger phrase: "user would say…"
+Steps: 1. … 2. … 3. …
+Tools: built-in or MCP
+Success: [specific output or state]
+```
+
+If vague, offer examples to react to. Concrete > abstract.
+
+### 1.3 Category
+
+| Category | When to choose |
+|---|---|
+| Document & Asset Creation | Consistent output generation (reports, slides, code, diagrams) |
+| Workflow Automation | Multi-step processes with methodology (planning, onboarding, deploys) |
+| MCP Enhancement | Workflow guidance on top of MCP tool access |
+| Domain Intelligence | Specialized knowledge (compliance, finance rules, security checks) |
+
+### 1.4 Out of scope (explicit)
+
+List adjacent things this skill must NOT do. Add them to the `Do NOT use for…` clause of the description.
+
+**Exit:** 2-3 use cases, category, out-of-scope list.
+
+---
+
+## Phase 2: DESIGN
+
+**Goal:** Structural decisions before any writing.
+
+### 2.1 Pick a pattern
+
+| Pattern | When |
+|---|---|
+| Sequential Workflow | Steps have dependencies, ordering is load-bearing |
+| Multi-MCP Coordination | Spans multiple external services |
+| Iterative Refinement | Quality improves through review-fix cycles |
+| Context-Aware Selection | Best tool depends on input properties |
+| Domain-Specific Intelligence | Expert rules drive correct execution |
+
+Most skills combine. Identify the **primary** pattern.
+
+### 2.2 Folder layout
+
+```
+skill-name/
+├── SKILL.md           # Required. Target <500 lines, <5000 tokens.
+├── scripts/           # Only if deterministic checks needed
+├── references/        # Only if deep content >100 lines
+├── assets/            # Only if templates/static resources are used in output
+└── evals/             # Optional, for output-quality evaluation
+    └── evals.json
+```
+
+Decision rules:
+- Logic that must be deterministic → `scripts/`
+- Reference content >100 lines → `references/`
+- Templates/images reused in output → `assets/`
+- Everything else → keep in SKILL.md
+
+### 2.3 Map progressive disclosure
+
+| Level | What | Token budget |
+|---|---|---|
+| L1 Frontmatter | `name` + `description` | ~100 words |
+| L2 SKILL.md body | Core workflow, steps, examples | <500 lines |
+| L3 Linked files | Deep ref, API docs, large examples | As needed |
+
+SKILL.md must tell the agent **when** to read each linked file. "Read `references/spec.md` if X" beats "see references/".
+
+### 2.4 Draft the description (placeholder, finalize in OPTIMIZE)
+
+Format: `[What] + [Use when, with trigger phrases] + [Do NOT use for]`. ≤1024 chars total.
+
+**Exit:** Pattern, folder layout, L1/L2/L3 map, description draft.
+
+---
+
+## Phase 3: AUTHOR
+
+**Goal:** Write the skill with precision.
+
+### 3.1 Frontmatter hard rules
+
+```yaml
+---
+name: kebab-case-name           # Must match folder. 1-64 chars, [a-z0-9-], no leading/trailing/consecutive hyphens.
+description: >                   # Folded multiline OK; ≤1024 chars; no XML angle brackets.
+  What it does. Use when [triggers]. Do NOT use for [exclusions].
+license: CC-BY-4.0
+metadata:
+  version: 1.0.0
+  author: your-name-or-org
+---
+```
+
+Forbidden:
+- Spaces or capitals in `name` or folder
+- `claude` / `anthropic` reserved terms
+- `SKILL.MD`, `Skill.md`, `skill.md` (must be exactly `SKILL.md`)
+- XML angle brackets `<` `>` in description
+- Description > 1024 characters
+
+### 3.2 Body writing principles
+
+- Imperative form ("Run X", "Check Y"). Specific > verbose.
+- Critical rules at the top, not buried in the middle.
+- 2-3 concrete examples (input → actions → result).
+- Reference files with explicit load conditions.
+- For deterministic checks, prefer scripts over prose.
+- Do not wrap prose at arbitrary column widths; let sentences flow.
+- Code blocks may wrap for readability.
+
+### 3.3 Supporting files
+
+For each `references/*.md` or `scripts/*`:
+- Reference it from SKILL.md with a clear WHEN clause.
+- For files >300 lines, add a Table of Contents.
+- Scripts: see [scripts-guide](references/scripts-guide.md) for PEP 723, agentic design, --help, exit codes.
+
+**Exit:** SKILL.md drafted, all hard rules satisfied, supporting files written.
+
+---
+
+## Phase 4: VALIDATE
+
+**Goal:** Catch structural and spec errors before delivery.
+
+### 4.1 Run the bundled validator
+
+```bash
+python3 scripts/validate.py <skill-folder>
+# or, with PEP 723 inline dependencies via uv:
+uv run --no-project scripts/validate.py <skill-folder>
+```
+
+The validator checks: folder kebab-case, SKILL.md exists, frontmatter YAML valid, `name` rules, `description` rules, body line count, examples present, references linked, no XML in description.
+
+Pass = exit code 0. Warnings are allowed. Errors are not.
+
+### 4.2 Spec re-check
+
+Confirm against the full format spec (see [references/spec.md](references/spec.md)):
+- `compatibility` field if the skill needs specific environment
+- `allowed-tools` field if you want to pre-approve specific tools
+- File references are relative to the skill root, one level deep preferred
+
+### 4.3 Trigger sanity
+
+Mentally run 5-10 short prompts. Should trigger; should NOT trigger (near-misses). If the description is too narrow, broaden it; if too broad, add exclusions. Save these prompts — they seed the eval in OPTIMIZE.
+
+For the full eval-driven optimization, proceed to OPTIMIZE.
+
+**Exit:** Validator PASS + spec check + trigger sanity.
+
+---
+
+## Phase 5: OPTIMIZE
+
+**Goal:** Make the skill trigger reliably and prove it improves output quality.
+
+Two eval loops, run in this order:
+
+### 5.1 Description triggering eval
+
+Open [description-optimization](references/description-optimization.md).
+
+Write ~20 eval queries (8-10 should-trigger, 8-10 should-NOT-trigger), emphasizing near-misses. Split 60/40 into `train_queries.json` and `validation_queries.json`. Run the trigger script 3x per query. Iterate on the description (using only the train set) until stable. Select the best iteration by validation pass rate.
+
+### 5.2 Output-quality eval (optional, recommended for workflow skills)
+
+Open [output-evaluation](references/output-evaluation.md).
+
+Build `evals/evals.json` with 2-3 test cases. Run each twice (with-skill, without-skill) into `iteration-1/`. Add assertions, grade, aggregate to `benchmark.json`. Iterate the skill body based on failed assertions and human review. Stop when pass rate plateaus or feedback is empty.
+
+**Exit:** Description eval pass rate ≥0.5 on validation set; output eval (if run) shows skill adds value.
+
+---
+
+## Phase 6: DELIVER
+
+**Goal:** Install + register.
+
+### 6.1 Local install
+
+Drop the skill into the right skills directory for the target agent:
+
+| Agent | Path |
+|---|---|
+| VS Code + Copilot | `.agents/skills/` |
+| Claude Code | `.claude/skills/` |
+| Cursor | `.cursor/skills/` |
+| OpenCode | `.opencode/skill/` |
+
+Optionally add a slash command to the agent's command file (e.g. `/forge`) so the trigger works without typing a long phrase.
+
+### 6.2 For catalog publication
+
+1. Add a row to the catalog's index (package README) with version, description, main trigger, and link to the skill's README.
+2. Create a release note in whatever format the catalog uses (changeset, changelog entry, release tag, etc.).
+3. Bump the skill's own `metadata.version` to match the release.
+4. Publish through whatever distribution mechanism the catalog uses (npm package, git tag, registry upload).
+
+### 6.3 For distribution elsewhere
+
+Keep the skill self-contained. Make sure the skill folder is at a path the target agent scans. Include a top-level human-facing README alongside the skill folder (not inside it).
+
+**Exit:** Skill installed, registered, and a test prompt verifies triggering in the target agent.
+
+---
+
+## Bundled resources
+
+- **[references/spec.md](references/spec.md)** — the open SKILL.md format reference.
+- **[references/authoring-patterns.md](references/authoring-patterns.md)** — best practices: gotchas, templates, checklists, validation loops, plan-validate-execute, calibrating control.
+- **[references/description-optimization.md](references/description-optimization.md)** — trigger eval methodology with train/val split.
+- **[references/output-evaluation.md](references/output-evaluation.md)** — output-quality eval: with-skill vs without-skill, assertions, benchmark.
+- **[references/scripts-guide.md](references/scripts-guide.md)** — using scripts in skills: PEP 723, agentic script design, --help, exit codes.
+- **[scripts/validate.py](scripts/validate.py)** — stdlib-only validator; `--json-out` for agentic consumption.
+- **[assets/SKILL.template.md](assets/SKILL.template.md)** — blank template for new skills.
+
+## Anti-patterns to avoid
+
+- ❌ Vague description: "Helps with documents."
+- ❌ Verbose body the agent will skim.
+- ❌ No examples.
+- ❌ Wrong `SKILL.md` casing.
+- ❌ Spaces or capitals in folder or name.
+- ❌ `claude` or `anthropic` in the name.
+- ❌ XML angle brackets in description.
+- ❌ SKILL.md > 500 lines (move detail to references/).
+- ❌ Description > 1024 chars.
+- ❌ Claiming to be the only skill loaded (skills compose).
+- ❌ Re-explaining what the agent already knows (PDFs, HTTP, etc.).
+- ❌ Referencing internal projects, packages, or repos by name in the skill body.

package/skills/skill-forge/assets/SKILL.template.md

@@ -0,0 +1,73 @@
+---
+name: <skill-name>
+description: >
+  <What it does — one short sentence>. Use when <trigger conditions, including
+  EN and PT trigger phrases if your audience is bilingual>. Do NOT use for
+  <explicit exclusions to prevent misfiring>.
+license: CC-BY-4.0
+metadata:
+  author: <your-name-or-org>
+  version: 0.1.0
+---
+
+# <Skill Name>
+
+> One-line tagline that captures the value proposition.
+
+## Overview
+
+[2-3 sentences. What this skill does, who it is for, and what kind of output
+the user can expect.]
+
+## When to use
+
+- Trigger situation 1
+- Trigger situation 2
+- Trigger situation 3
+
+**When NOT to use:**
+
+- Adjacent task better served by another skill
+- One-off tweak that doesn't need a workflow
+- Task the agent already handles well without this skill
+
+## Workflow
+
+### Step 1: <Action>
+
+[Specific, imperative instructions.]
+
+Expected output: [what success looks like]
+
+### Step 2: <Action>
+
+[Specific, imperative instructions.]
+
+### Step 3: <Action>
+
+[Specific, imperative instructions.]
+
+## Examples
+
+### Example 1: <Common scenario>
+
+User says: "..."
+
+Steps:
+1. ...
+2. ...
+
+Result: [specific output]
+
+## Gotchas
+
+- Environment-specific fact that defies assumptions
+- Project convention the agent won't know
+- API/library quirk to watch for
+
+## References
+
+Load these only when the relevant step is reached:
+
+- [references/spec.md](references/spec.md) — domain spec
+- [references/api.md](references/api.md) — API reference (load when step 2 fails)

package/skills/skill-forge/references/authoring-patterns.md

@@ -0,0 +1,249 @@
+# Authoring Patterns
+
+> Best practices for writing skill bodies. Read this when drafting a new skill and deciding between flexible guidance and prescriptive steps.
+
+## Start from real expertise
+
+A common pitfall: asking an LLM to generate a skill without providing domain-specific context. The result is vague, generic procedures ("handle errors appropriately", "follow best practices for authentication") rather than the specific API patterns, edge cases, and project conventions that make a skill valuable.
+
+Effective skills are grounded in real expertise. Two ways to feed it in:
+
+**Extract from a hands-on task.** Do the real work in a session with the agent, providing context, corrections, and preferences. Then extract the reusable pattern. Capture:
+
+- Steps that worked (the successful sequence)
+- Corrections you made ("use library X instead of Y", "check for edge case Z")
+- Input/output formats (what data went in, what came out)
+- Context you provided (project facts, conventions, constraints)
+
+**Synthesize from existing project artifacts.** Feed the LLM the actual material, not generic articles. A data-pipeline skill built from your team's incident reports and runbooks will outperform one built from "data engineering best practices" because it captures your schemas, failure modes, and recovery procedures. Good sources:
+
+- Internal documentation, runbooks, style guides
+- API specifications, schemas, configuration files
+- Code review comments and issue trackers
+- Version control history, especially patches and fixes
+- Real-world failure cases and their resolutions
+
+## Refine with real execution
+
+The first draft usually needs refinement. Run the skill against real tasks, then feed all results — not just failures — back into the creation process. Ask: what triggered false positives? What was missed? What could be cut?
+
+Read execution traces, not just final outputs. Common causes of wasted steps:
+
+- Instructions too vague (agent tries several approaches before finding one)
+- Instructions that don't apply to the current task (agent follows them anyway)
+- Too many options without a clear default
+
+Even a single pass of execute-then-revise noticeably improves quality. Complex domains often benefit from several.
+
+## Spending context wisely
+
+Once a skill activates, its full `SKILL.md` body loads into the agent's context window alongside conversation history, system context, and other active skills. Every token in your skill competes for the agent's attention.
+
+### Add what the agent lacks, omit what it knows
+
+Focus on what the agent wouldn't know without your skill: project conventions, domain procedures, non-obvious edge cases, the particular tools or APIs to use. Don't explain what a PDF is, how HTTP works, or what a database migration does.
+
+```markdown
+<!-- Too verbose — the agent already knows what PDFs are -->
+## Extract PDF text
+
+PDF (Portable Document Format) files are a common file format that contains
+text, images, and other content. To extract text from a PDF, you'll need to
+use a library. pdfplumber is recommended because it handles most cases well.
+
+<!-- Better — jumps to what the agent wouldn't know -->
+## Extract PDF text
+
+Use pdfplumber for text extraction. For scanned documents, fall back to
+pdf2image with pytesseract.
+```
+
+Ask: "Would the agent get this wrong without this instruction?" If no, cut it. If unsure, test it. If the agent handles the whole task well without the skill, the skill may not be adding value.
+
+### Design coherent units
+
+Skills are functions: encapsulate a coherent unit of work that composes well with other skills.
+
+- Too narrow → multiple skills must load for one task (overhead, conflicting instructions).
+- Too broad → hard to activate precisely.
+
+A skill for "query a database and format results" is one coherent unit. A skill that also covers database administration is doing too much.
+
+### Aim for moderate detail
+
+Comprehensive skills can hurt — the agent struggles to extract what's relevant, may pursue unproductive paths from instructions that don't apply. Concise, stepwise guidance with a working example outperforms exhaustive documentation. When you find yourself covering every edge case, consider whether most are better handled by the agent's own judgment.
+
+### Structure with progressive disclosure
+
+Keep `SKILL.md` under 500 lines and 5000 tokens — the core the agent needs on every run. When more is legitimately needed, move detail to `references/` and tell the agent **when** to load each file.
+
+> "Read `references/api-errors.md` if the API returns a non-200 status code" is more useful than a generic "see references/ for details."
+
+## Calibrating control
+
+Not every part needs the same level of prescriptiveness. Match specificity to fragility.
+
+### Match specificity to fragility
+
+**Give the agent freedom** when multiple approaches are valid and the task tolerates variation. Explaining *why* often beats rigid directives.
+
+```markdown
+## Code review process
+
+1. Check all database queries for SQL injection (use parameterized queries)
+2. Verify authentication checks on every endpoint
+3. Look for race conditions in concurrent code paths
+4. Confirm error messages don't leak internal details
+```
+
+**Be prescriptive** when operations are fragile, consistency matters, or a specific sequence must be followed.
+
+```markdown
+## Database migration
+
+Run exactly this sequence:
+
+```bash
+python scripts/migrate.py --verify --backup
+```
+
+Do not modify the command or add additional flags.
+```
+
+Most skills have a mix. Calibrate each part independently.
+
+### Provide defaults, not menus
+
+When multiple tools or approaches could work, pick a default and mention alternatives briefly.
+
+```markdown
+<!-- Too many options -->
+You can use pypdf, pdfplumber, PyMuPDF, or pdf2image...
+
+<!-- Clear default with escape hatch -->
+Use pdfplumber for text extraction:
+
+```python
+import pdfplumber
+```
+
+For scanned PDFs requiring OCR, use pdf2image with pytesseract instead.
+```
+
+### Favor procedures over declarations
+
+A skill should teach the agent *how to approach* a class of problems, not *what to produce* for a specific instance.
+
+```markdown
+<!-- Specific answer — only useful for this exact task -->
+Join the `orders` table to `customers` on `customer_id`, filter where
+`region = 'EMEA'`, and sum the `amount` column.
+
+<!-- Reusable method — works for any analytical query -->
+1. Read the schema from `references/schema.yaml` to find relevant tables
+2. Join tables using the `_id` foreign key convention
+3. Apply any filters from the user's request as WHERE clauses
+4. Aggregate numeric columns as needed and format as a markdown table
+```
+
+Specific details (output templates, hard constraints like "never output PII", tool-specific instructions) are valuable. The point: the *approach* should generalize even when individual details are specific.
+
+## Patterns for effective instructions
+
+### Gotchas sections
+
+The highest-value content in many skills is a list of gotchas — environment-specific facts that defy reasonable assumptions. These aren't general advice; they're concrete corrections to mistakes the agent will make without being told.
+
+```markdown
+## Gotchas
+
+- The `users` table uses soft deletes. Queries must include
+  `WHERE deleted_at IS NULL` or results will include deactivated accounts.
+- The user ID is `user_id` in the database, `uid` in the auth service,
+  and `accountId` in the billing API. All three refer to the same value.
+- The `/health` endpoint returns 200 as long as the web server is running,
+  even if the database connection is down. Use `/ready` to check full
+  service health.
+```
+
+Keep gotchas in `SKILL.md` where the agent reads them before encountering the situation. A reference file works if you tell the agent when to load it, but for non-obvious issues, the agent may not recognize the trigger.
+
+When the agent makes a mistake you have to correct, add the correction to the gotchas section. This is one of the most direct ways to improve a skill iteratively.
+
+### Templates for output format
+
+When the agent must produce output in a specific format, provide a template. Agents pattern-match well against concrete structures. Short templates can live inline; longer ones go in `assets/`.
+
+```markdown
+## Report structure
+
+Use this template, adapting sections as needed:
+
+```markdown
+# [Analysis Title]
+
+## Executive summary
+[One-paragraph overview of key findings]
+
+## Key findings
+- Finding 1 with supporting data
+- Finding 2 with supporting data
+
+## Recommendations
+1. Specific actionable recommendation
+2. Specific actionable recommendation
+```
+```
+
+### Checklists for multi-step workflows
+
+An explicit checklist helps the agent track progress and avoid skipping steps, especially when steps have dependencies or validation gates.
+
+```markdown
+## Form processing workflow
+
+Progress:
+- [ ] Step 1: Analyze the form (run `scripts/analyze_form.py`)
+- [ ] Step 2: Create field mapping (edit `fields.json`)
+- [ ] Step 3: Validate mapping (run `scripts/validate_fields.py`)
+- [ ] Step 4: Fill the form (run `scripts/fill_form.py`)
+- [ ] Step 5: Verify output (run `scripts/verify_output.py`)
+```
+
+### Validation loops
+
+Instruct the agent to validate its own work before moving on: do, validate, fix, repeat.
+
+```markdown
+## Editing workflow
+
+1. Make your edits
+2. Run validation: `python scripts/validate.py output/`
+3. If validation fails:
+   - Review the error message
+   - Fix the issues
+   - Run validation again
+4. Only proceed when validation passes
+```
+
+A reference document can also be the "validator" — instruct the agent to check its work against the reference before finalizing.
+
+### Plan-validate-execute
+
+For batch or destructive operations: create an intermediate plan, validate it against a source of truth, then execute.
+
+```markdown
+## PDF form filling
+
+1. Extract form fields: `python scripts/analyze_form.py input.pdf` → `form_fields.json`
+2. Create `field_values.json` mapping each field to its intended value
+3. Validate: `python scripts/validate_fields.py form_fields.json field_values.json`
+4. If validation fails, revise `field_values.json` and re-validate
+5. Fill the form: `python scripts/fill_form.py input.pdf field_values.json output.pdf`
+```
+
+The key ingredient is step 3: a validation script that checks the plan against the source of truth. Errors like "Field 'signature_date' not found — available fields: customer_name, order_total, signature_date_signed" give the agent enough information to self-correct.
+
+### Bundling reusable scripts
+
+When iterating on a skill, compare execution traces across test cases. If the agent independently reinvents the same logic each run (building charts, parsing a format, validating output), that's the signal to write a tested script once and bundle it. See [scripts-guide.md](scripts-guide.md).