ForgeSkill

Files (48)

• DescriptionOptimization.md.yaml · .provenance/
• EvalLoop.md.yaml · .provenance/
• SKILL.yaml · .provenance/
• ClaudeSkill.md
• CliToolIntegration.md
• CreateWorkflow.md
• DescriptionOptimization.md
• DynamicContextInjection.md
• EvalLoop.md
• MultiProviderRouting.md
• PlatformAgnostic.md
• SKILL.md
• SkillInstallation.md
• SkillStructure.md
• UserConfigSchema.md
• ValidateWorkflow.md
• analyzer.md.yaml · agents/.provenance/
• comparator.md.yaml · agents/.provenance/
• grader.md.yaml · agents/.provenance/
• analyzer.md · agents/
• comparator.md · agents/
• grader.md · agents/
• eval_review.html.yaml · assets/.provenance/
• eval_review.html · assets/
• generate_review.py.yaml · eval-viewer/.provenance/
• viewer.html.yaml · eval-viewer/.provenance/
• generate_review.py · eval-viewer/
• viewer.html · eval-viewer/
• schemas.md.yaml · references/.provenance/
• schemas.md · references/
• __init__.py.yaml · scripts/.provenance/
• aggregate_benchmark.py.yaml · scripts/.provenance/
• generate_report.py.yaml · scripts/.provenance/
• improve_description.py.yaml · scripts/.provenance/
• package_skill.py.yaml · scripts/.provenance/
• quick_validate.py.yaml · scripts/.provenance/
• run_eval.py.yaml · scripts/.provenance/
• run_loop.py.yaml · scripts/.provenance/
• utils.py.yaml · scripts/.provenance/
• __init__.py · scripts/
• aggregate_benchmark.py · scripts/
• generate_report.py · scripts/
• improve_description.py · scripts/
• package_skill.py · scripts/
• quick_validate.py · scripts/
• run_eval.py · scripts/
• run_loop.py · scripts/
• utils.py · scripts/

SKILL.md (first lines)

# ForgeSkill

Create, validate, evaluate, and iterate skills following forge conventions. Skills are markdown files (`SKILL.md`) with YAML frontmatter that teach AI coding tools new capabilities. Load only the companion relevant to the current task.

The evaluation machinery (grader/comparator/analyzer prompts, eval scripts, browser viewer) lives in `agents/`, `scripts/`, `references/`, `eval-viewer/`, and `assets/`. Scripts run with `python -m scripts.<name>` from this skill's directory (`${CLAUDE_SKILL_DIR}` when deployed). The files under `agents/` are worker prompt templates this skill feeds to generic subagents during the eval loop, not standalone agent definitions; harness-discoverable agents belong in the module-level `agents/` directory.

## Workflow Routing

| Workflow           | Trigger                                                      | Companion                                                 |
| ------------------ | ------------------------------------------------------------ | --------------------------------------------------------- |
| Create             | "create a skill", "new skill", "write a skill"               | [@CreateWorkflow.md](CreateWorkflow.md)                     |
| Validate           | "validate skill", "check skill structure"                    | [@ValidateWorkflow.md](ValidateWorkflow.md)                 |
| Evaluate           | "test this skill", "run skill evals", "benchmark the skill"  | [@EvalLoop.md](EvalLoop.md)                                 |
| Optimize triggering | "skill doesn't trigger", "improve the skill description"     | [@DescriptionOptimization.md](DescriptionOptimization.md)  |

## Topics

| Topic                                                       | Companion                                                |
| ----------------------------------------------------------- | -------------------------------------------------------- |
| SKILL.md structure, frontmatter, body layout, naming        | [@SkillStructure.md](SkillStructure.md)                    |
| **Dynamic context injection (`!`): open a Claude skill with live state** | [@DynamicContextInjection.md](DynamicContextInjection.md) |
| Multi-provider routing via `defaults.yaml`                  | [@MultiProviderRouting.md](MultiProviderRouting.md)        |
| Wrapping a CLI tool in a skill                              | [@CliToolIntegration.md](CliToolIntegration.md)            |
| Platform-agnostic writing — no placeholders or `/` prefix   | [@PlatformAgnostic.md](PlatformAgnostic.md)                |
| User-config schema for AI-first artifacts (autoMode mirror) | [@UserConfigSchema.md](UserConfigSchema.md)                |
| Claude-only features: `@` refs, skill discovery, `allowed-tools` | [@ClaudeSkill.md](ClaudeSkill.md)              |
| When to author a per-skill INSTALL.md                       | [@SkillInstallation.md](SkillInstallation.md)              |
| Eval JSON structures (evals.json, grading.json, benchmark.json) | [@references/schemas.md](references/schemas.md)        |

## Red Flags

| Thought                                                  | Reality                                                                              |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| "Put argument-hint in SKILL.md frontmatter"              | Obsidian Linter reformats frontmatter. Provider-specific fields go in SKILL.yaml.     |
| "Use `/SkillName` inside a skill body"                   | Slashes are user-facing invocation syntax, not internal references.                    |
| "Skip the `USE WHEN` clause"                             | Claude uses it to route. Missing trigger = skill never fires.                         |
| "Leave a stub section as a placeholder"                  | Skill bodies are plain prose. Delete empty sections, don't scaffold them.             |
| "Inline every example in the SKILL.md"                   | SKILL.md should stay slim. Move static reference material to companion files.         |
| "Skill directory can have any name"                      | Directory name must match the `name:` frontmatter field exactly.                      |
| "Put a `!` injection in a companion file"                | `!` runs only in the SKILL.md body; in a companion it renders as literal text. See [@ClaudeSkill.md](ClaudeSkill.md). |
| "Inject a secret value with `!` (e.g. `pass show`)"      | Injection lands in the transcript. Inject structure/status (names, vault list), never secret values. |
| "It ran in my sandbox, so the probe is done"             | Your sandbox has tooling (uv, personal paths, aliases) the target machine lacks — resolve interpreters at preflight and assume a clean environment. |
| "I'll write custom HTML to show eval results"            | `eval-viewer/generate_review.py` already renders outputs and benchmarks. Use it.      |
| "The skill passed its three evals, ship it"              | A handful of examples overfits. Generalize the fix; don't patch the skill to the test set. |

## Constraints

- Every skill MUST have `name:` and `description:` in frontmatter
- Description MUST include `USE WHEN` trigger phrases
- PascalCase for multi-word skill names, natural case for single words
- Skill directory name must match the `name:` field
- Prefer one SKILL.md per skill — extract reference material into companion files when body exceeds ~150 lines or contains dense static data
- Eval artifacts land in `<skill-name>-workspace/` as a sibling of the skill directory, never inside the skill

## Sources

- <https://code.claude.com/docs/en/skills>
- <https://github.com/anthropics/skills>

From N4M3Z/forge-core, EUPL-1.2.

More from N4M3Z/forge-core