# Weapon Forge > Phase 2 of the Legion AI Tools Factory pipeline. Takes a completed Command Brief AND a pre-populated `research/` folder authored by `scripture-historian`, names the Weapon (Cursor skill), scaffolds the rest of the skill folder structure under `ai-tools/skills/`, and forges the Cursor-compatible SKILL.md plus its supporting guides, examples, templates, and reports. This skill no longer conducts its own research -- that is `scripture-historian`'s job, and weapon-forge refuses to run until that folder is populated. Use whenever the user says "forge the weapon", "build the skill", "scaffold the weapon folder", "build guides from the research", "the research is in, build the skill", or signals that scripture-historian has just announced its handoff. Also trigger when the user hands you a path to a filled-in `{angel-name}-command-brief.md` plus a non-empty `ai-tools/skills//research/` folder and says to proceed. - Skill: `the-notorious-avengers/weapon-forge` (Agent Skill, multi-file: 7 files) - Install (CLI): `npx skillmds@latest add the-notorious-avengers/weapon-forge` - Raw SKILL.md: https://api.skillmd.com/api/skills/the-notorious-avengers/weapon-forge/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - License: MIT - Author: The-Notorious-Avengers (https://skillmd.com/u/the-notorious-avengers) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/the-notorious-avengers/weapon-forge --- # Weapon Forge You are the blacksmith of the Legion AI Tools Factory. `command-center` has produced a Command Brief (a clear, specific portrait of an Angel and what its Weapon must encode), and `scripture-historian` has pulled the primary sources into the weapon's `research/` folder with a manifest. Your job is to forge the Weapon: the Cursor skill itself -- SKILL.md, guides, examples, templates, and the report shape -- by synthesizing the research that has already been gathered. You do not conduct research. That phase is owned by `scripture-historian` and runs before you. Your raw materials are the brief and the populated `research/` folder. Treat this phase as craftsmanship, not paperwork. --- ## When to use this skill Trigger when BOTH preconditions are met: 1. A completed Command Brief exists at `ai-tools/command-briefs/-command-brief.md`. 2. A populated `research/` folder exists at `ai-tools/skills//research/` with at least a `research-summary.md` and an `index.md` written by `scripture-historian`. Trigger phrases: - "The research is in, forge the weapon" - "Scaffold the skill folder for seo-guardian and build the guides" - "Build the skill from scripture-historian's research" - "scripture-historian just finished -- proceed" - "Here's the brief at `ai-tools/command-briefs/security-guardian-command-brief.md` and the research at `ai-tools/skills/security-weapon/research/`; build it" Do NOT trigger when: - The Command Brief is missing -- redirect to `command-center`. - The `research/` folder is missing or empty -- redirect to `scripture-historian`. Refuse politely; do not silently fall back to running your own research, because that breaks the audit trail and duplicates work. - Only `research-plan.md` exists but no actual research files -- `scripture-historian` started but did not finish. Ask the caller whether to resume `scripture-historian` or accept the gap. --- ## The three-step workflow ### Step 1 -- Scaffold the rest of the Weapon folder The Weapon name mirrors the Angel name with the `-weapon` suffix (e.g., `security-guardian` -> `security-weapon`). See `references/naming.md` for details and edge cases. The name should already match the brief's YAML `weapon_name:` field. `scripture-historian` has already created `ai-tools/skills//research/` and populated it. Your job is to scaffold the SIBLING folders without touching `research/`: ``` / ├── SKILL.md (required, authored in Step 3) ├── README.md (a one-page human overview) ├── examples/ (worked inputs -> outputs showing the skill in action) ├── guides/ (the procedural instruction set, split into focused files) ├── reports/ (outputs the skill produces -- templates and past runs) ├── research/ (DO NOT MODIFY -- owned by scripture-historian) └── templates/ (stubs, schemas, forms the Angel fills in) ``` You may add additional subfolders when a Weapon clearly needs them (e.g., `schema/`, `prompts/`, `scripts/`). Do not remove the six defaults -- even if a folder starts empty, having the slot signals intent and gives future contributors a place to drop work. If `research/` is missing or empty, STOP. Do not scaffold further; redirect the caller to `scripture-historian`. weapon-forge does not run on an empty research foundation. After scaffolding the sibling folders, write a stub `README.md` in the skill root describing the skill's purpose in three sentences, citing both the Command Brief file and the `research/research-summary.md`. ### Step 2 -- Read the Command Brief and the research manifest Open `ai-tools/command-briefs/-command-brief.md`. Read it end to end. Extract: 1. The **YAML frontmatter** -- confirm `angel_name`, `weapon_name`, and `research_depth` match what `scripture-historian` consumed. A mismatch means someone edited the brief after research ran; surface this to the caller before forging. 2. The **ACTION** list -- these verbs determine the guides you need to write. 3. The **EXPECTED OUTPUT** format -- this drives the `templates/` and `reports/` folders. 4. The **SUBAGENT CRITICAL DIRECTIVES** -- these become the guardrails in the skill's introduction. 5. The **REFERENCE MATERIAL** section -- this is your map of which sources `scripture-historian` was told to consult. 6. The **IDEAS, SUGGESTIONS, QUESTIONS** section -- the proposed guide structure starts here. Then open `ai-tools/skills//research/research-summary.md` and `research/index.md`. These are the manifests `scripture-historian` left for you. Read them BEFORE diving into individual research files. The summary tells you: - Depth tier consumed and time window covered - File counts per subfolder - The 5 most influential sources (with annotations) - Open questions that survived research (these are flags for you to escalate to the user, NOT to invent answers for) - Sources flagged for deeper context The index gives you a one-line view of every research file by source type, authority, relevance, and topic. Use it to plan which files each guide will cite, not to read every file in order. If `research-summary.md` lists open questions that block guide authorship, pause and surface them to the user before proceeding. Do not invent answers; that's what the directive against unresearched assertions exists to prevent. ### Step 3 -- Forge the skill: write SKILL.md, guides, examples, templates, reports **Author the skill following Cursor's skill specification.** The authoritative reference is https://cursor.com/docs/skills. Key requirements and patterns are summarized in `references/cursor-skill-spec.md` -- read it before writing SKILL.md. The SKILL.md file sits at the root of the skill folder and contains: - **YAML frontmatter** with at minimum `name` and `description`. The description is the triggering mechanism and must be specific about when the skill activates. - **Body** in markdown -- the primary instruction set the Angel reads. Keep SKILL.md under about 500 lines. When content exceeds that, move detail into `guides/` and reference it from SKILL.md with clear pointers (e.g., "See `guides/02-canonical-tags.md` for the full rule set"). This is Cursor's progressive-disclosure pattern and it matters: a lean SKILL.md triggers reliably and stays in context; bloated SKILL.md files overwhelm the model. **Populate the supporting folders:** - `guides/` -- One focused markdown file per major procedure, numbered (`01-...`, `02-...`) so the ordering is obvious. Each guide is a self-contained instruction set for a single verb or rule. Every factual claim in a guide should cite at least one file from `research/` (by relative path). - `examples/` -- Worked examples showing the skill in action. Include at least two (one happy-path, one edge case) so the Angel has a pattern to imitate. - `templates/` -- Reusable stubs the Angel fills in. Empty skeletons with placeholder text are more useful than fully-written samples, because they force the Angel to do the work. - `reports/` -- A template for the report shape described in EXPECTED OUTPUT, plus a one-line README explaining that this folder collects past runs over time. - `research/` -- DO NOT MODIFY. This folder is the audit trail authored by `scripture-historian`. weapon-forge only reads it. Guides and examples should be mutually referenced -- each example cites the guide(s) it demonstrates, and each guide cites at least one example that puts it into practice. Every guide should also cite the research file(s) it derives from. This three-way linking (guide <-> example <-> research) is what makes the Weapon auditable a year from now. --- ## What "done" looks like The Weapon is ready when: 1. `SKILL.md` exists with a tight, triggering description and a body under ~500 lines. 2. The folder tree has non-empty content in `guides/`, `examples/`, `templates/`, and `reports/`. The `research/` folder is exactly as `scripture-historian` left it. 3. The guides collectively cover every verb in the brief's ACTION section. 4. The directives from the brief's SUBAGENT CRITICAL DIRECTIVES are surfaced somewhere in SKILL.md or a dedicated `guides/00-principles.md` file. 5. Every factual claim in a guide cites at least one file under `research/` by relative path. Unresearched assertions are removed or replaced with research before forging continues. 6. Open questions from `research/research-summary.md` have been resolved (by the user) or explicitly flagged in the relevant guide as `> TODO: open question -- needs human decision before next refresh`. A detailed done checklist lives in `references/done-checklist.md`. --- ## Handoff protocol When the Weapon is forged, end with the handoff line: > "Weapon `` forged at `ai-tools/skills//`. Ready to hand off to **angel-creator**." The next skill (`angel-creator`) will author the subagent file that wields this Weapon. Do not author the subagent yourself -- keep the phases separate so each artifact is attributable to its owner. --- ## Common failure modes to avoid - **Starting before `scripture-historian` finishes.** weapon-forge refuses to run on an empty or missing `research/` folder. Conducting your own research from training data alone defeats the whole pipeline and corrupts the audit trail. - **Modifying `research/`.** That folder is owned by `scripture-historian`. Treat it as read-only. If research is wrong or insufficient, re-invoke `scripture-historian`, do not patch the folder yourself. - **Over-stuffing SKILL.md.** If the guides are short enough to inline, do so -- but resist the urge to inline everything. The progressive-disclosure pattern exists for a reason. - **Generic guides.** "Follow security best practices" is not a guide. "When reviewing a dependency bump, compare the new version's published date to the last known-good version and flag any gap shorter than 14 days as suspicious" is a guide. - **Missing examples.** A guide without at least one example is a guideline. Examples turn guidelines into skills. - **Unresearched assertions.** Everything factual in the guides should trace to a specific file in `research/`. If it does not, either find it in `research/` (via `index.md`), or escalate to the user to re-run `scripture-historian` with a follow-on query. Do not invent. - **Inventing answers to open questions.** `research/research-summary.md` may list questions that survived the literature sweep. Those are flags for the user, not prompts for you to guess.