@aegis-scan/skills 0.2.1 → 0.4.0

package/skills/foundation/aegis-native/aegis-skill-creator/SKILL.md

@@ -0,0 +1,223 @@
+<!-- aegis-local: AEGIS-native skill, MIT-licensed; Meta-skill that builds new skills via SkillForge methodology + AEGIS HARD-CONSTRAINT-format. Triage (USE_EXISTING / IMPROVE / CREATE_NEW / COMPOSE) -> Scaffold via init_skill.py -> 11-Lens-Analysis -> Validate (auto-iterate to 16/17+) -> Commit. NO skill-creation without validate-pass + 3+ references + Anti-Patterns + Extension-Points sections. References to SkillForge methodology with attribution. -->
+---
+name: aegis-skill-creator
+description: Meta-skill that builds new skills via SkillForge methodology (tripleyak/SkillForge MIT) + AEGIS HARD-CONSTRAINT-format. Pipeline - Triage / Scaffold / 11-Lens-Iterate / Validate (16/17+) / Commit. Trigger keywords - neuer skill, skill erstellen, skill verbessern, skill audit, meta-skill, skillforge.
+model: opus
+license: MIT
+metadata:
+  required_tools: "shell-ops,file-ops,task-tracking"
+  required_audit_passes: "2"
+  enforced_quality_gates: "1"
+  pre_done_audit: "true"
+---
+
+# aegis-skill-creator — Meta-Skill (Skills That Build Skills)
+
+The Foundation's meta-skill. Creates / improves / audits other skills via the SkillForge methodology (tripleyak/SkillForge, MIT) wrapped in AEGIS HARD-CONSTRAINT-format. Either produces a SKILL.md that validates 16/17+ with all required sections, or returns INCOMPLETE with the missing-checks list.
+
+---
+
+## HARD-CONSTRAINT — Reference-Loading + Validate-Gate
+
+This skill MUST:
+
+1. **Load `references/skillforge-methodology.md`** before producing any skill-output. The SkillForge methodology (11-Lens-Analysis, iteration-guide, multi-lens-framework) is the canonical authoring-method.
+2. **Load `references/hard-constraint-template.md`** for the AEGIS HARD-CONSTRAINT-block structure. Every new skill carries this block.
+3. **Validate-gate is non-skippable.** Every output skill must pass `validate-skill.py` at 16/17+ before commit. Iterate up to 5 times; if not at 16/17 after 5 iterations → return INCOMPLETE with missing-check list.
+4. **Triage-first, not create-first.** Phase 1 evaluates USE_EXISTING / IMPROVE / CREATE_NEW / COMPOSE. Many "I need a new skill" requests are actually "improve this existing one"; jumping to create wastes effort.
+5. **No skill ships without:** ≥ 3 references (when complex enough to warrant), `## Anti-Patterns`, `## Extension Points`, HARD-CONSTRAINT-block in body, all-fields-populated frontmatter (model + license + metadata.required_tools + metadata.pre_done_audit).
+6. **Attribution is mandatory.** Skills derived from SkillForge methodology carry attribution-comment + reference SkillForge in `references/skillforge-methodology.md`. No silent-port.
+
+If any of (1)-(6) cannot be satisfied → STOP, report the gap. Don't produce a partial skill.
+
+---
+
+## Mission
+
+Eliminate the failure-mode where a coding-agent, asked to "build a skill", produces a 50-line SKILL.md that fails validate, has no references, no Anti-Patterns, and no clear extension-path. Provide an industrial-grade meta-pipeline that:
+
+- Triages first (don't create when improve / use-existing applies)
+- Uses SkillForge methodology (11 lenses)
+- Wraps in AEGIS HARD-CONSTRAINT-format
+- Validates auto-iteratively to 16/17+
+- Returns DONE-with-validate-proof or INCOMPLETE-with-list
+
+---
+
+## Triggers
+
+### Slash-commands
+
+- `/skill-creator` — create / improve / audit a skill
+- `/new-skill` — alias for create
+- `/skill-audit` — run audit on existing skill
+
+### Auto-trigger keywords
+
+- neuer skill, skill erstellen, skill verbessern, skill audit, meta-skill, skill creator, skillforge
+
+### Required-input
+
+- For CREATE: skill-name + 1-paragraph mission-statement + intended trigger-keywords + complexity-estimate (single-file vs multi-file with N references)
+- For IMPROVE: existing skill-path + specific gaps to address
+- For AUDIT: existing skill-path
+
+---
+
+## Process
+
+| Phase | Time | Output |
+|---|---|---|
+| 1. Triage | ~5 min | decision: USE_EXISTING / IMPROVE / CREATE_NEW / COMPOSE |
+| 2. Scaffold | ~5 min | folder + SKILL.md skeleton via init_skill.py-style |
+| 3. Iterate (11-Lens) | ~30-60 min | full SKILL.md + references |
+| 4. Validate (auto-iterate) | ~10 min | 16/17+ validation pass |
+| 5. Commit | ~5 min | atomic commit + handover-update |
+
+### Phase 1: Triage
+
+Evaluate the request against existing skill-pool:
+
+```
+1. List skills in target category (or full pool):
+   ls /tmp/a.e.g.i.s/packages/skills/skills/<category>/
+
+2. For each existing skill, read SKILL.md description:
+   grep "^description:" */SKILL.md
+
+3. Decide:
+   - USE_EXISTING — an existing skill already does this; route there.
+   - IMPROVE — an existing skill is close; extend it (new section / new reference / new triggers).
+   - CREATE_NEW — no existing skill covers this; new skill needed.
+   - COMPOSE — solve via 2+ existing skills + a coordinating wrapper.
+```
+
+Triage decision MUST be explicit + recorded. Don't silent-create when use-existing applies.
+
+### Phase 2: Scaffold
+
+For CREATE_NEW or COMPOSE:
+
+```bash
+# Use init_skill.py (SkillForge tool) or manual scaffold
+SKILL_DIR=/tmp/a.e.g.i.s/packages/skills/skills/<category>/<source>/<name>
+mkdir -p "$SKILL_DIR/references"
+
+# Write SKILL.md skeleton with:
+# - Frontmatter (name, description, model, license, metadata block)
+# - HARD-CONSTRAINT block placeholder
+# - All required sections as headers (Mission, Triggers, Process, Verification, Anti-Patterns, Extension Points)
+```
+
+For IMPROVE:
+
+- Read existing SKILL.md
+- Write existing-state-snapshot to `improvement-plan.md` (in skill-folder, removed before commit)
+- Identify specific gaps (sections missing, references thin, frontmatter incomplete)
+
+### Phase 3: Iterate (11-Lens-Analysis)
+
+Apply each lens from `references/skillforge-methodology.md`:
+
+| Lens | Question |
+|---|---|
+| 1. User-Intent | What does the user actually want when they invoke this skill? |
+| 2. Trigger-Keywords | What words / contexts cause this skill to fire? |
+| 3. Inputs / Outputs | What does the skill take in? What does it produce? |
+| 4. Process / Workflow | What's the step-by-step? |
+| 5. Verification | How do you know the output is correct? |
+| 6. Anti-Patterns | What goes wrong without this skill? |
+| 7. Extension Points | How can future projects extend this? |
+| 8. Model-Selection | Opus / Sonnet / Haiku — which fits the cognitive load? |
+| 9. Tool-Categories | Which tools (shell-ops / file-ops / task-tracking / subagent-dispatch / ...) does the skill need? |
+| 10. References-Set | Which external sources / patterns / templates inform this skill? |
+| 11. Validate-Compliance | Will this pass `validate-skill.py` at 16/17+? |
+
+For each lens, write a paragraph in the SKILL.md (not all in one place; lens-output maps to specific sections per `references/skillforge-methodology.md`).
+
+### Phase 4: Validate (auto-iterate)
+
+```bash
+python3 /tmp/SkillForge/scripts/validate-skill.py "$SKILL_DIR"
+# Note: aegis-native skills with leading <!-- aegis-local --> comment need stripping first.
+# A wrapper script handles this — see CONTRIBUTING.md "Validate aegis-native skills" section.
+```
+
+Read output. For each failing check:
+
+- Missing section → add it
+- Wrong frontmatter field → fix it
+- Description too short / too long → adjust
+- No tables / no examples → add them
+- > 3 phases when 1-3 recommended → either consolidate or accept as advisory (per Fallstricke)
+
+Re-run validate. Iterate up to 5 times. If still red after 5 — return INCOMPLETE with the failing-check list.
+
+### Phase 5: Commit
+
+```bash
+git add "$SKILL_DIR"
+git commit -m "$(cat <<EOF
+feat(<category>): add <skill-name> — <one-line-purpose>
+
+- Frontmatter with HARD-CONSTRAINT-fields (metadata.required_tools, etc.)
+- Body sections per validate-skill.py contract (Mission, Triggers, Process, Verification, Anti-Patterns, Extension Points)
+- N references (when multi-file)
+- validate-skill.py: <N>/<M> passing
+
+Closes <issue or skill-request reference>
+EOF
+)"
+```
+
+Update aegis-native/_INDEX.md (or appropriate category-_INDEX.md) with the new skill's trigger-table row.
+
+Update master AGENTS.md if a new use-case is introduced.
+
+Update manifest.test EXPECTED_TOTAL + EXPECTED_NAMES_BY_CATEGORY.
+
+---
+
+## Verification / Success Criteria
+
+Before declaring the skill-creation complete:
+
+- [ ] Phase 1 Triage decision explicit (USE_EXISTING / IMPROVE / CREATE_NEW / COMPOSE) + recorded
+- [ ] If CREATE_NEW or COMPOSE: scaffold via init_skill.py-style, all required sections present
+- [ ] 11-Lens-Analysis applied (each lens-output maps to a SKILL.md section)
+- [ ] `validate-skill.py` at 16/17+ (auto-iterate up to 5; if not, INCOMPLETE)
+- [ ] HARD-CONSTRAINT-block in body (not just frontmatter)
+- [ ] References (when multi-file): 2+ for simple, 3+ for moderate, 7+ for complex (e.g., aegis-customer-build has 7 phase-refs)
+- [ ] Anti-Patterns + Extension Points sections both populated (≥ 5 items each)
+- [ ] Attribution (when derived from external pattern: SkillForge / Spec-Author / etc.)
+- [ ] manifest.test + attribution.test + scrub.test all green
+- [ ] Atomic commit + index-updates committed together
+
+---
+
+## Anti-Patterns
+
+- ❌ Skipping Triage Phase 1 — many "create new" requests are actually "improve existing"; triage first.
+- ❌ Inventing a category for a skill that fits an existing one — use the existing category structure.
+- ❌ Frontmatter-only HARD-CONSTRAINT — body needs a HARD-CONSTRAINT-section too (frontmatter signals to loader, body signals to agent).
+- ❌ References that are stubs — every reference has actual content (≥ 50 lines for simple, 100+ for complex).
+- ❌ No Anti-Patterns section — validate flags this; also weakens skill (no "what NOT to do" guidance).
+- ❌ Validate-pass without re-checking semantics — passing 16/17 with bad content is worse than failing with good content. Read the SKILL.md after validate.
+- ❌ Multi-file skill where SKILL.md exceeds 300 lines + has 0 references — split into references.
+- ❌ Single-file skill with 100 lines but missing sections — add missing sections; don't claim "single-file" as excuse to skip.
+- ❌ Hardcoding tool-names like "Bash" in skill body — use tool-categories ("shell-ops") per AGENTS.md tool-mapping table.
+- ❌ Skipping attribution when porting from another methodology — credit + license-mention.
+- ❌ Committing skill without updating manifest.test EXPECTED_TOTAL — breaks CI.
+
+---
+
+## Extension Points
+
+- **New methodology**: SkillForge is the canonical methodology. Other methodologies (Anthropic skill-spec, custom org-spec) can be added as `references/<methodology>-methodology.md`. Phase 3 lens-table extends per methodology.
+- **Auto-iteration limit**: default 5 iterations in Phase 4. Increase via `--max-iterations N` for complex new skills; decrease via `--max-iterations 2` for low-stakes auto-fixups.
+- **Per-category templates**: a category (e.g., `defensive/`) might have a more specific HARD-CONSTRAINT-block-template than the generic one. Add `references/hard-constraint-template-<category>.md`.
+- **Different validators**: SkillForge `validate-skill.py` is canonical. Anthropic skill-spec validator (when available) can be added as `--validator=anthropic-spec`.
+- **Bulk-mode**: for migration of many existing skills to v0.3.0+ HARD-CONSTRAINT-format, add `--bulk` flag that iterates a list of skills + applies the upgrade-pattern in batch.
+- **Audit-mode**: `--audit` runs validate + 11-Lens review without modifying. Returns a structured report for operator-review. Useful before bumping a skill to a new major-version.
+- **Custom severity-thresholds**: a project might require 17/17 (all green, no advisory). Override via `aegis.config.json` `skill_creator.min_validate_score` (default 16).
+- **Multi-skill compose-mode**: `--mode=compose` builds 2+ skills as a cluster (e.g., a domain-specific bundle with orchestrator + 3 specialist + 1 audit). Phase 4 validates each individually + the bundle's _INDEX.md.

package/skills/foundation/aegis-native/aegis-skill-creator/references/hard-constraint-template.md

@@ -0,0 +1,213 @@
+# HARD-CONSTRAINT-Block Template
+
+The HARD-CONSTRAINT-block is the AEGIS-native discipline-marker that turns a SKILL.md into an enforceable contract. It's parameterized per skill-type (orchestrator / builder / auditor / writer / meta).
+
+---
+
+## Why HARD-CONSTRAINT?
+
+Without HARD-CONSTRAINT, a skill is a description. With HARD-CONSTRAINT, a skill is a precondition-checked contract:
+
+- **Frontmatter HARD-CONSTRAINT** (under `metadata:`) — signals to the loader (`parseHardConstraintFrontmatter()`) that this skill has enforced quality-gates, a required tool-set, and a mandatory pre-done audit. The loader can refuse to dispatch the skill if the harness lacks the required tools.
+
+- **Body HARD-CONSTRAINT-block** (after Mission) — signals to the agent that certain conditions MUST be satisfied before the skill begins work. The skill author enforces this; the agent is expected to read + obey.
+
+Example: `aegis-customer-build` HARD-CONSTRAINT requires loading 7 phase-references + the project's component-library inventory + the configurator-briefing BEFORE Phase 1 starts. Skipping any of these guarantees a quality-regression.
+
+---
+
+## Frontmatter Template (canonical v0.3.0+)
+
+```yaml
+---
+name: <skill-name>                    # kebab-case, [a-z][a-z0-9-]{2,40}
+description: <one-sentence-purpose plus trigger-keywords>   # 50-280 chars
+model: opus | sonnet | haiku           # per Lens 8
+license: MIT                            # AEGIS-native default
+metadata:
+  required_tools: "<csv-of-tool-categories>"   # per Lens 9 + AGENTS.md tool-mapping
+  required_audit_passes: "<N>"                # how many audit-passes the skill requires
+  enforced_quality_gates: "<N>"               # how many of the 9 gates this skill enforces
+  pre_done_audit: "true" | "false"            # whether this skill blocks DONE-claim until audited
+---
+```
+
+`metadata.required_tools` examples per skill-type:
+
+| Skill-type | required_tools |
+|---|---|
+| orchestrator (session-entry) | "shell-ops,file-ops,task-tracking" |
+| customer-build | "shell-ops,file-ops,task-tracking,subagent-dispatch,library-engine,aegis-scan,brutaler-anwalt,lighthouse" |
+| audit | "shell-ops,file-ops,curl,playwright,aegis-scan" |
+| module-builder | "shell-ops,file-ops,task-tracking" |
+| handover-writer | "file-ops,shell-ops" |
+| quality-gates | "shell-ops,file-ops" |
+| skill-creator | "shell-ops,file-ops,task-tracking" |
+| compliance / dsgvo | "shell-ops,file-ops" |
+
+---
+
+## Body HARD-CONSTRAINT-Block — Per Skill-Type
+
+The body block follows a fixed template. Header always `## HARD-CONSTRAINT — <discipline-name>`.
+
+### Pattern A: Orchestrator (session-entry skills)
+
+```markdown
+## HARD-CONSTRAINT — Bootstrap-Discipline
+
+Before responding to ANY user request, this skill MUST:
+
+1. Read `<bootstrap-file-1>`.
+2. Read `<bootstrap-file-2>`.
+3. Read `<bootstrap-file-3>`.
+4. Print `Tool-inventory: [...], Skills available: [...], Project-state: ...`.
+5. THEN process the user's request.
+
+If any of (1)-(N) is missing — STOP, report the gap. Don't improvise.
+```
+
+Example: `aegis-orchestrator`.
+
+### Pattern B: Builder (customer-build / module-builder)
+
+```markdown
+## HARD-CONSTRAINT — Anti-Halbherzig-Discipline
+
+Before <pipeline-start>, this skill MUST:
+
+1. Load all <N> phase-references in `references/`.
+2. Load <project-inventory>.
+3. Load <input-contract> (e.g., briefing, feature-spec).
+4. Validate <pages-count | feature-acceptance-criteria | etc.> commitment.
+5. <pipeline> is non-skippable.
+6. Per-phase checkpoint to `.aegis/state.json`.
+7. Final-Verify-Loop: <N> gates green OR repair-attempt OR INCOMPLETE-Status.
+
+If any of (1)-(N) cannot be satisfied — STOP and report which precondition is missing.
+```
+
+Example: `aegis-customer-build`.
+
+### Pattern C: Auditor (audit / brutaler-anwalt)
+
+```markdown
+## HARD-CONSTRAINT — Layer-Order, Reference-Loading, No Mocks
+
+This skill MUST:
+
+1. Load all <N> layer-references BEFORE producing any finding.
+2. Execute layers in fixed order (1 → N).
+3. No mocks. Every layer hits the real target.
+4. Cross-check with <sibling-skill> at <shared-layers>.
+5. Output the canonical <N>-section format.
+6. Include <severity-classification> per layer's defined criteria.
+
+If any layer cannot run — STOP, report which layer + why. Don't silent-skip.
+```
+
+Example: `aegis-audit`, `brutaler-anwalt`.
+
+### Pattern D: Writer (handover-writer / report-writer)
+
+```markdown
+## HARD-CONSTRAINT — <Output>-Completeness
+
+The <output-artifact> MUST include all <N> sections listed under `## Verification / Success Criteria`.
+
+Skipping a section breaks <downstream-consumer>. If a section legitimately has nothing to report, write `(none this session)` rather than omitting the header.
+
+References to <source-doc> belong in `## Recommendations` if they affect the operator's next decisions, not buried elsewhere.
+```
+
+Example: `aegis-handover-writer`.
+
+### Pattern E: Verifier (quality-gates)
+
+```markdown
+## HARD-CONSTRAINT — Fail-Closed, No Mocks
+
+This skill is the safety-net for <consumer>. It MUST:
+
+1. Run real commands against the real artifact (no mocks).
+2. Fail-closed: if even one <thing> is red, return exit-non-zero.
+3. Not be silenced via <bypass-mechanism> (`--no-verify`, etc.).
+4. Emit a structured report (JSON + markdown) downstream tooling can parse.
+
+If <bypass> is invoked → that's a violation per spec hard-NICHTs. Document the override in <SECURITY-EXCEPTION.md>.
+```
+
+Example: `aegis-quality-gates`.
+
+### Pattern F: Meta (skill-creator / framework-tooling)
+
+```markdown
+## HARD-CONSTRAINT — Reference-Loading + Validate-Gate
+
+This skill MUST:
+
+1. Load `<methodology-reference>` before producing any output.
+2. Load `<format-template>` for the <format> structure.
+3. Validate-gate is non-skippable. Iterate up to <N> times; if not at <threshold> → INCOMPLETE.
+4. <Triage-or-similar>-first, not <action>-first.
+5. No <output> ships without: <required-fields>.
+6. Attribution is mandatory when derived from <external>.
+
+If any of (1)-(N) cannot be satisfied → STOP, report the gap.
+```
+
+Example: `aegis-skill-creator`.
+
+---
+
+## Block-Length Guidelines
+
+- **Numbered list:** 4-8 items. Fewer = under-specified; more = either splitting into a sub-block or consolidating items.
+- **Final escape clause:** every HARD-CONSTRAINT-block ends with "If any of (1)-(N) cannot be satisfied — STOP and report which precondition is missing. Don't improvise; the foundation depends on these guarantees." (or domain-equivalent).
+- **No optional items.** If a step is "should" — move it out of HARD-CONSTRAINT. HARD-CONSTRAINT is "MUST" only.
+
+---
+
+## Cross-references to other Skills
+
+When a HARD-CONSTRAINT requires another skill, format as:
+
+```
+4. Load `compliance/aegis-native/brutaler-anwalt/SKILL.md` for the spot-check passes in Phase 6 + final pass in Phase 7.
+```
+
+The path is canonical (relative to skill-pool root) so any harness can resolve it.
+
+---
+
+## Anti-Patterns for HARD-CONSTRAINT-blocks
+
+- ❌ Aspirational items ("ideally we should...") — HARD-CONSTRAINT is non-negotiable; aspirations belong in Mission.
+- ❌ Items that aren't actually enforceable ("be thorough", "do good work") — replace with verifiable preconditions.
+- ❌ More than 10 items — block becomes a wall-of-text; split into 2 sub-blocks if domain-genuinely-complex.
+- ❌ Reusing the same block across all skills verbatim — each skill's preconditions are domain-specific; copy-paste-then-adapt.
+- ❌ Missing the final escape-clause — without it, agents may try to silent-skip a missing precondition.
+- ❌ HARD-CONSTRAINT-block before Mission — Mission first (so the reader knows context); HARD-CONSTRAINT after Mission (preconditions for the mission).
+- ❌ HARD-CONSTRAINT in frontmatter only — the body block IS the discipline-marker for the agent. Both are needed.
+
+---
+
+## Migration: Adding HARD-CONSTRAINT to an Existing Skill
+
+If upgrading a v0.2.x skill to v0.3.0+ HARD-CONSTRAINT-format:
+
+```
+1. Add metadata: block to frontmatter with required_tools, required_audit_passes, enforced_quality_gates, pre_done_audit.
+2. Add `## HARD-CONSTRAINT — <discipline>` section after Mission.
+3. List 4-8 numbered preconditions.
+4. End with the escape-clause.
+5. Re-run validate-skill.py.
+6. If validate score drops because of new content — review and fix.
+7. Commit with `feat(<skill-name>): HARD-CONSTRAINT-frontmatter + <N> missing sections`.
+```
+
+Reference: brutaler-anwalt (commit `4fdd1e0`) is the canonical migration-example. 9/16 → 17/17 after migration.
+
+---
+
+License: MIT. Template-content used per AEGIS-foundation public-OSS license; adapt freely for your skill-authoring.

package/skills/foundation/aegis-native/aegis-skill-creator/references/skillforge-methodology.md

@@ -0,0 +1,220 @@
+# SkillForge Methodology Reference
+
+**Source:** tripleyak/SkillForge — MIT-licensed. https://github.com/tripleyak/SkillForge
+**Attribution:** This reference adapts SkillForge's iteration-guide + multi-lens-framework methodology for AEGIS-native skills. Original methodology by SkillForge contributors; this reference summarizes the parts directly applicable to AEGIS skill-authoring.
+
+---
+
+## What SkillForge Provides
+
+SkillForge is a methodology + tooling for building Claude Code skills (or any AGENTS.md-aware skill-system) at industrial-grade quality.
+
+Three principal artifacts:
+
+- `init_skill.py` — scaffolds a skill-folder with the canonical layout
+- `validate-skill.py` — validates SKILL.md against the spec (frontmatter + sections + complexity-thresholds)
+- `references/multi-lens-framework.md` + `references/iteration-guide.md` — methodology
+
+The validate-skill.py output (e.g., `16/17 passed, 1 warning`) is the canonical pass-criterion for AEGIS-native skills.
+
+---
+
+## The 11-Lens Analysis
+
+When authoring or auditing a skill, apply each lens. Each lens-output lands in a specific SKILL.md section.
+
+### Lens 1: User-Intent
+
+**Question:** What does the user *actually* want when they invoke this skill?
+
+**Method:** Imagine the user typing `/<skill-name>` (or saying the trigger-keyword). What's the underlying need? Often the surface-request is misleading — "I need a script" might be "I need a workflow" or "I need a checklist".
+
+**Lands in:** `## Mission` section + `description:` frontmatter.
+
+### Lens 2: Trigger-Keywords
+
+**Question:** What words / contexts cause this skill to fire?
+
+**Method:** Think of 5-10 distinct user-utterances. Distill the keywords. Verify keywords don't collide with sibling skills (e.g., two skills both triggered by "audit" would race).
+
+**Lands in:** `## Triggers` section + `description:` keywords-list.
+
+### Lens 3: Inputs / Outputs
+
+**Question:** What does the skill take in? What does it produce?
+
+**Method:** Define the contract. Inputs = files / args / context the skill expects. Outputs = files / state / messages the skill produces. Be specific: "produces a markdown report at <path>" beats "writes some output".
+
+**Lands in:** `## Mission` (high-level) + `## Process` (per-phase inputs/outputs).
+
+### Lens 4: Process / Workflow
+
+**Question:** What's the step-by-step?
+
+**Method:** Decompose into 3-7 phases (more = over-engineered per validator advisory). Each phase has a clear inputs → output → checkpoint pattern.
+
+**Lands in:** `## Process` section.
+
+### Lens 5: Verification
+
+**Question:** How do you know the output is correct?
+
+**Method:** Define checkbox-list of success-criteria. Each item is independently testable.
+
+**Lands in:** `## Verification / Success Criteria` section.
+
+### Lens 6: Anti-Patterns
+
+**Question:** What goes wrong without this skill?
+
+**Method:** Brainstorm failure-modes. The skill exists because these failure-modes are common; document them.
+
+**Lands in:** `## Anti-Patterns` section.
+
+### Lens 7: Extension Points
+
+**Question:** How can future projects extend this?
+
+**Method:** Identify variation-axes (different stack / different industry / different threshold). Document where extensions go (which file / which config-key).
+
+**Lands in:** `## Extension Points` section.
+
+### Lens 8: Model-Selection
+
+**Question:** Opus / Sonnet / Haiku — which fits the cognitive load?
+
+**Decision Matrix:**
+
+| Skill type | Model |
+|---|---|
+| Strategic planning, multi-step orchestration, ambiguity-handling | opus |
+| Routine execution with clear contract, single-flow | sonnet |
+| Pattern-matching, simple lookups | haiku |
+
+**Lands in:** `model:` frontmatter field.
+
+### Lens 9: Tool-Categories
+
+**Question:** Which tools does the skill need?
+
+**Method:** List per AGENTS.md tool-mapping table:
+
+- shell-ops (Bash equivalent)
+- file-ops (Read / Write / Edit equivalent)
+- task-tracking (TodoWrite / update_plan equivalent)
+- subagent-dispatch (Task / spawn_agent equivalent)
+- domain-specific (aegis-scan / brutaler-anwalt / lighthouse / playwright / curl / library-engine)
+
+**Lands in:** `metadata.required_tools` frontmatter field.
+
+### Lens 10: References-Set
+
+**Question:** Which external sources / patterns / templates inform this skill?
+
+**Method:** Identify methodologies, court-decisions, standards, prior art. Each becomes a reference under `references/`.
+
+**Lands in:** `references/` folder + cross-mentions in body.
+
+### Lens 11: Validate-Compliance
+
+**Question:** Will this pass `validate-skill.py` at 16/17+?
+
+**Method:** Run validate. Read output. Address each failing check. Re-run.
+
+**Lands in:** none directly — but failing this means re-iterating other lenses.
+
+---
+
+## Iteration Guide
+
+Skills are not one-shot. Plan for ≥ 3 iterations:
+
+### Iteration 1: Skeleton
+
+- Frontmatter complete (all fields populated, even with placeholder values)
+- All required section-headers present (Mission / Triggers / Process / Verification / Anti-Patterns / Extension Points)
+- Each section has ≥ 1 paragraph or 3 bullet-points
+
+Validate target: 12-14/17 (most checks pass; some "thin content" warnings).
+
+### Iteration 2: Content-Fill
+
+- Apply 11-Lens-Analysis to each section
+- Add tables for structured information (validate likes tables)
+- Add references/ folder if complexity > 200 lines (validate flags this)
+- Populate Anti-Patterns + Extension Points (≥ 5 items each)
+
+Validate target: 15-16/17.
+
+### Iteration 3: Polish
+
+- Re-read SKILL.md as if you've never seen it. Does each section flow?
+- Cross-check examples and code-blocks compile / make sense
+- Verify trigger-keywords don't collide with other skills
+- Add missing sections if validate flags any
+
+Validate target: 16/17 (with the 1 advisory warning typically being "5+ phases — consolidate to 1-3").
+
+### Iteration 4-5 (if needed)
+
+If still < 16/17:
+
+- Re-read each failing check's exact requirement
+- Read 2-3 existing 17/17 skills as canonical examples
+- Apply structural fixes (sometimes adding a single ## subsection lifts 2 checks)
+
+If after 5 iterations still < 16/17 → INCOMPLETE-Status. Don't ship sub-bar skills.
+
+---
+
+## Common Pitfalls (per Fallstricke)
+
+1. **Validator regex anchor** — leading `<!-- aegis-local -->` HTML comments break frontmatter detection. Strip the comment before validating (or use the wrapper script in CONTRIBUTING.md).
+2. **Frontmatter allowlist** — `validate-skill.py` rejects unknown top-level YAML fields. Custom HARD-CONSTRAINT fields nest under `metadata:`. Top-level allowed: `name`, `description`, `model`, `license`, `metadata`, `agent`, `allowed-tools`, `context`, `hooks`, `user-invocable`.
+3. **5-phase advisory** — a `## Process` section with > 3 sub-phases triggers an advisory warning ("Recommend 1-3 phases, not over-engineered"). Acceptable for genuinely-complex pipelines (customer-build has 7 phases by design); not acceptable for skills that could consolidate.
+4. **Tables warning** — "Should use tables for structured information" — triggers when complex skill has only bullets. Add 1-2 tables to lift the warning.
+5. **References warning** — "Complex skill (>200 lines) should have references/ directory" — triggers on monolithic SKILL.md. Either split into references/ or shrink SKILL.md.
+
+---
+
+## Cross-skill Authoring Pattern
+
+When a new skill relates to existing skills:
+
+- **Cross-mention** — body explicitly references sibling skills (e.g., aegis-audit body mentions brutaler-anwalt for cross-validation).
+- **Routing-table updates** — `_INDEX.md` files in the category get the new skill's row.
+- **Master AGENTS.md updates** — if a new use-case is introduced, master router gets a row.
+- **manifest.test updates** — EXPECTED_TOTAL increments + EXPECTED_NAMES_BY_CATEGORY adds the new name.
+
+These cross-skill updates land in the SAME commit as the new skill, not in a follow-up commit.
+
+---
+
+## Checklist Before Commit
+
+- [ ] `validate-skill.py` ≥ 16/17
+- [ ] 11-Lens-Analysis output mapped to sections
+- [ ] HARD-CONSTRAINT-block in body (not just frontmatter)
+- [ ] All required sections present + populated
+- [ ] References (when multi-file) each ≥ 50 lines (simple) or 100+ lines (complex)
+- [ ] Anti-Patterns + Extension Points each ≥ 5 items
+- [ ] Attribution (when derived)
+- [ ] _INDEX.md updated
+- [ ] manifest.test EXPECTED_TOTAL incremented
+- [ ] No leading `<!-- aegis-local -->` comment leaks into body (only line 1)
+- [ ] Scrub-clean (no forbidden codenames)
+
+---
+
+## Reference: Original SkillForge Materials
+
+For the original SkillForge methodology (more detail than this summary), see:
+
+- `https://github.com/tripleyak/SkillForge/blob/main/references/multi-lens-framework.md`
+- `https://github.com/tripleyak/SkillForge/blob/main/references/iteration-guide.md`
+- `https://github.com/tripleyak/SkillForge/blob/main/scripts/init_skill.py`
+- `https://github.com/tripleyak/SkillForge/blob/main/scripts/validate-skill.py`
+
+This AEGIS reference adapts the relevant patterns for AEGIS-native skills with HARD-CONSTRAINT-block + foundation-quality-gates. AEGIS-specific extensions (HARD-CONSTRAINT-frontmatter under `metadata:`, the 9-gate quality-gates, the 4-section audit-output) are AEGIS-specific; SkillForge does not require them.
+
+License: MIT. SkillForge methodology used per its MIT-license terms; this AEGIS adaptation is also MIT.