feat: Calculer automatiquement les moyennes après chaque saisie de notes
Les enseignants ont besoin de moyennes à jour immédiatement après la publication ou modification des notes, sans attendre un batch nocturne. Le système recalcule via Domain Events synchrones : statistiques d'évaluation (min/max/moyenne/médiane), moyennes matières pondérées (normalisation /20), et moyenne générale par élève. Les résultats sont stockés dans des tables dénormalisées avec cache Redis (TTL 5 min). Trois endpoints API exposent les données avec contrôle d'accès par rôle. Une commande console permet le backfill des données historiques au déploiement.
This commit is contained in:
@@ -0,0 +1,63 @@
|
||||
# Workflow Classification Reference
|
||||
|
||||
Classify the skill type based on user requirements. This table is for internal use — DO NOT show to user.
|
||||
|
||||
## 3-Type Taxonomy
|
||||
|
||||
| Type | Description | Structure | When to Use |
|
||||
| -------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------- |
|
||||
| **Simple Utility** | Input/output building block. Headless, composable, often has scripts. | Single SKILL.md + scripts/ | Composable building block with clear input/output, single-purpose |
|
||||
| **Simple Workflow** | Multi-step process contained in a single SKILL.md. Minimal or no prompt files. | SKILL.md + optional references/ | Multi-step process that fits in one file, no progressive disclosure needed |
|
||||
| **Complex Workflow** | Multi-stage with progressive disclosure, numbered prompt files at root, config integration. May support headless mode. | SKILL.md (routing) + prompt stages at root + references/ | Multiple stages, long-running process, progressive disclosure, routing logic |
|
||||
|
||||
## Decision Tree
|
||||
|
||||
```
|
||||
1. Is it a composable building block with clear input/output?
|
||||
└─ YES → Simple Utility
|
||||
└─ NO ↓
|
||||
|
||||
2. Can it fit in a single SKILL.md without progressive disclosure?
|
||||
└─ YES → Simple Workflow
|
||||
└─ NO ↓
|
||||
|
||||
3. Does it need multiple stages, long-running process, or progressive disclosure?
|
||||
└─ YES → Complex Workflow
|
||||
```
|
||||
|
||||
## Classification Signals
|
||||
|
||||
### Simple Utility Signals
|
||||
|
||||
- Clear input → processing → output pattern
|
||||
- No user interaction needed during execution
|
||||
- Other skills/workflows call it
|
||||
- Deterministic or near-deterministic behavior
|
||||
- Could be a script but needs LLM judgment
|
||||
- Examples: JSON validator, schema checker, format converter
|
||||
|
||||
### Simple Workflow Signals
|
||||
|
||||
- 3-8 numbered steps
|
||||
- User interaction at specific points
|
||||
- Uses standard tools (gh, git, npm, etc.)
|
||||
- Produces a single output artifact
|
||||
- No need to track state across compactions
|
||||
- Examples: PR creator, deployment checklist, code review
|
||||
|
||||
### Complex Workflow Signals
|
||||
|
||||
- Multiple distinct phases/stages
|
||||
- Long-running (likely to hit context compaction)
|
||||
- Progressive disclosure needed (too much for one file)
|
||||
- Routing logic in SKILL.md dispatches to stage prompts
|
||||
- Produces multiple artifacts across stages
|
||||
- May support headless/autonomous mode
|
||||
- Examples: agent builder, module builder, project scaffolder
|
||||
|
||||
## Module Context (Orthogonal)
|
||||
|
||||
Module context is asked for ALL types:
|
||||
|
||||
- **Module-based:** Part of a BMad module. Uses `bmad-{modulecode}-{skillname}` naming. Config loading includes a fallback pattern — if config is missing, the skill informs the user that the module setup skill is available and continues with sensible defaults.
|
||||
- **Standalone:** Independent skill. Uses `bmad-{skillname}` naming. Config loading is best-effort — load if available, use defaults if not, no mention of a setup skill.
|
||||
@@ -0,0 +1,123 @@
|
||||
# BMad Module Workflows
|
||||
|
||||
Advanced patterns for BMad module workflows — long-running, multi-stage processes with progressive disclosure, config integration, and compaction survival.
|
||||
|
||||
---
|
||||
|
||||
## Workflow Persona
|
||||
|
||||
BMad workflows treat the human operator as the expert. The agent facilitates — asks clarifying questions, presents options with trade-offs, validates before irreversible actions. The operator knows their domain; the workflow knows the process.
|
||||
|
||||
---
|
||||
|
||||
## Config Reading and Integration
|
||||
|
||||
Workflows read config from `{project-root}/_bmad/config.yaml` and `config.user.yaml`.
|
||||
|
||||
### Config Loading Pattern
|
||||
|
||||
**Module-based skills** — load with fallback and setup skill awareness:
|
||||
|
||||
```
|
||||
Load config from {project-root}/_bmad/config.yaml ({module-code} section) and config.user.yaml.
|
||||
If missing: inform user that {module-setup-skill} is available, continue with sensible defaults.
|
||||
```
|
||||
|
||||
**Standalone skills** — load best-effort:
|
||||
|
||||
```
|
||||
Load config from {project-root}/_bmad/config.yaml and config.user.yaml if available.
|
||||
If missing: continue with defaults — no mention of setup skill.
|
||||
```
|
||||
|
||||
### Required Core Variables
|
||||
|
||||
Load core config (user preferences, language, output locations) with sensible defaults. If the workflow creates documents, include document output language.
|
||||
|
||||
**Example config line for a document-producing workflow:**
|
||||
|
||||
```
|
||||
vars: user_name:BMad,communication_language:English,document_output_language:English,output_folder:{project-root}/_bmad-output,bmad_builder_output_folder:{project-root}/bmad-builder-creations/
|
||||
```
|
||||
|
||||
Config variables used directly in prompts — they already contain `{project-root}` in resolved values.
|
||||
|
||||
---
|
||||
|
||||
## Long-Running Workflows: Compaction Survival
|
||||
|
||||
Workflows that run long may trigger context compaction. Critical state MUST survive in output files.
|
||||
|
||||
### The Document-Itself Pattern
|
||||
|
||||
**The output document is the cache.** Write directly to the file you're creating, updating progressively. The document stores both content and context:
|
||||
|
||||
- **YAML front matter** — paths to input files, current status
|
||||
- **Draft sections** — progressive content as it's built
|
||||
- **Status marker** — which stage is complete
|
||||
|
||||
Each stage after the first reads the output document to recover context. If compacted, re-read input files listed in the YAML front matter.
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: 'Analysis: Research Topic'
|
||||
status: 'analysis'
|
||||
inputs:
|
||||
- '{project_root}/docs/brief.md'
|
||||
created: '2025-03-02T10:00:00Z'
|
||||
updated: '2025-03-02T11:30:00Z'
|
||||
---
|
||||
```
|
||||
|
||||
**When to use:** Guided flows with long documents, yolo flows with multiple turns. Single-pass yolo can wait to write final output.
|
||||
|
||||
**When NOT to use:** Short single-turn outputs, purely conversational workflows, multiple independent artifacts (each gets its own file).
|
||||
|
||||
---
|
||||
|
||||
## Sequential Progressive Disclosure
|
||||
|
||||
Use numbered prompt files at the skill root when:
|
||||
|
||||
- Multi-phase workflow with ordered stages
|
||||
- Input of one phase affects the next
|
||||
- Workflow is long-running and stages shouldn't be visible upfront
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
my-workflow/
|
||||
├── SKILL.md # Routing + entry logic (minimal)
|
||||
├── references/
|
||||
│ ├── 01-discovery.md # Stage 1
|
||||
│ ├── 02-planning.md # Stage 2
|
||||
│ ├── 03-execution.md # Stage 3
|
||||
│ └── templates.md # Supporting reference
|
||||
└── scripts/
|
||||
└── validator.sh
|
||||
```
|
||||
|
||||
Each stage prompt specifies prerequisites, progression conditions, and next destination. SKILL.md is minimal routing logic.
|
||||
|
||||
**Keep inline in SKILL.md when:** Simple skill, well-known domain, single-purpose utility, all stages independent.
|
||||
|
||||
---
|
||||
|
||||
## Module Metadata Reference
|
||||
|
||||
BMad module workflows require extended frontmatter metadata. See `./references/metadata-reference.md` for the metadata template and field explanations.
|
||||
|
||||
---
|
||||
|
||||
## Workflow Architecture Checklist
|
||||
|
||||
Before finalizing a BMad module workflow, verify:
|
||||
|
||||
- [ ] Facilitator persona — treats operator as expert?
|
||||
- [ ] Config integration — language, output locations read and used?
|
||||
- [ ] Portable paths — artifacts use `{project_root}`?
|
||||
- [ ] Compaction survival — each stage writes to output document?
|
||||
- [ ] Document-as-cache — YAML front matter with status and inputs?
|
||||
- [ ] Progressive disclosure — stages in `./references/` with progression conditions?
|
||||
- [ ] Final polish — subagent polish step at the end?
|
||||
- [ ] Recovery — can resume by reading output doc front matter?
|
||||
@@ -0,0 +1,53 @@
|
||||
# Quality Dimensions — Quick Reference
|
||||
|
||||
Seven dimensions to keep in mind when building skills. The quality scanners check these automatically during quality analysis — this is a mental checklist for the build phase.
|
||||
|
||||
## 1. Outcome-Driven Design
|
||||
|
||||
Describe what to achieve, not how to get there step by step. Only add procedural detail when the LLM would genuinely fail without it.
|
||||
|
||||
- **The test:** Would removing this instruction cause the LLM to produce a worse outcome? If the LLM would do it anyway, the instruction is noise.
|
||||
- **Pruning:** If a block teaches the LLM something it already knows — scoring algorithms for subjective judgment, calibration tables for reading the room, weighted formulas for picking relevant participants — cut it. These are things LLMs do naturally.
|
||||
- **When procedure IS value:** Exact script invocations, specific file paths, API calls with precise parameters, security-critical operations. These need low freedom because there's one right way.
|
||||
|
||||
## 2. Informed Autonomy
|
||||
|
||||
The executing agent needs enough context to make judgment calls when situations don't match the script. The Overview establishes this: domain framing, theory of mind, design rationale.
|
||||
|
||||
- Simple utilities need minimal context — input/output is self-explanatory
|
||||
- Interactive/complex workflows need domain understanding, user perspective, and rationale for non-obvious choices
|
||||
- When in doubt, explain _why_ — an agent that understands the mission improvises better than one following blind steps
|
||||
|
||||
## 3. Intelligence Placement
|
||||
|
||||
Scripts handle plumbing (fetch, transform, validate). Prompts handle judgment (interpret, classify, decide).
|
||||
|
||||
**Test:** If a script contains an `if` that decides what content _means_, intelligence has leaked.
|
||||
|
||||
**Reverse test:** If a prompt validates structure, counts items, parses known formats, compares against schemas, or checks file existence — determinism has leaked into the LLM. That work belongs in a script.
|
||||
|
||||
## 4. Progressive Disclosure
|
||||
|
||||
SKILL.md stays focused. Detail goes where it belongs.
|
||||
|
||||
- Stage instructions → `./references/`
|
||||
- Reference data, schemas, large tables → `./references/`
|
||||
- Templates, config files → `./assets/`
|
||||
- Multi-branch SKILL.md under ~250 lines: fine as-is
|
||||
- Single-purpose up to ~500 lines (~5000 tokens): acceptable if focused
|
||||
|
||||
## 5. Description Format
|
||||
|
||||
Two parts: `[5-8 word summary]. [Use when user says 'X' or 'Y'.]`
|
||||
|
||||
Default to conservative triggering. See `./references/standard-fields.md` for full format.
|
||||
|
||||
## 6. Path Construction
|
||||
|
||||
Only use `{project-root}` for `_bmad` paths. Config variables used directly — they already contain `{project-root}`.
|
||||
|
||||
See `./references/standard-fields.md` for correct/incorrect patterns.
|
||||
|
||||
## 7. Token Efficiency
|
||||
|
||||
Remove genuine waste (repetition, defensive padding, meta-explanation). Preserve context that enables judgment (domain framing, theory of mind, design rationale). These are different things — never trade effectiveness for efficiency. A skill that works correctly but uses extra tokens is always better than one that's lean but fails edge cases.
|
||||
@@ -0,0 +1,100 @@
|
||||
# Script Opportunities Reference — Workflow Builder
|
||||
|
||||
**Reference: `references/script-standards.md` for script creation guidelines.**
|
||||
|
||||
## Core Principle
|
||||
|
||||
Scripts handle deterministic operations (validate, transform, count). Prompts handle judgment (interpret, classify, decide). If a check has clear pass/fail criteria, it belongs in a script.
|
||||
|
||||
---
|
||||
|
||||
## How to Spot Script Opportunities
|
||||
|
||||
### The Determinism Test
|
||||
|
||||
1. **Given identical input, will it always produce identical output?** → Script candidate.
|
||||
2. **Could you write a unit test with expected output?** → Definitely a script.
|
||||
3. **Requires interpreting meaning, tone, or context?** → Keep as prompt.
|
||||
|
||||
### The Judgment Boundary
|
||||
|
||||
| Scripts Handle | Prompts Handle |
|
||||
| -------------------------------- | ------------------------------------ |
|
||||
| Fetch, Transform, Validate | Interpret, Classify (ambiguous) |
|
||||
| Count, Parse, Compare | Create, Decide (incomplete info) |
|
||||
| Extract, Format, Check structure | Evaluate quality, Synthesize meaning |
|
||||
|
||||
### Signal Verbs in Prompts
|
||||
|
||||
When you see these in a workflow's requirements, think scripts first: "validate", "count", "extract", "convert/transform", "compare", "scan for", "check structure", "against schema", "graph/map dependencies", "list all", "detect pattern", "diff/changes between"
|
||||
|
||||
### Script Opportunity Categories
|
||||
|
||||
| Category | What It Does | Example |
|
||||
| ------------------- | ----------------------------------------------------------- | -------------------------------------------------- |
|
||||
| Validation | Check structure, format, schema, naming | Validate frontmatter fields exist |
|
||||
| Data Extraction | Pull structured data without interpreting meaning | Extract all `{variable}` references from markdown |
|
||||
| Transformation | Convert between known formats | Markdown table to JSON |
|
||||
| Metrics | Count, tally, aggregate statistics | Token count per file |
|
||||
| Comparison | Diff, cross-reference, verify consistency | Cross-ref prompt names against SKILL.md references |
|
||||
| Structure Checks | Verify directory layout, file existence | Skill folder has required files |
|
||||
| Dependency Analysis | Trace references, imports, relationships | Build skill dependency graph |
|
||||
| Pre-Processing | Extract compact data from large files BEFORE LLM reads them | Pre-extract file metrics into JSON for LLM scanner |
|
||||
| Post-Processing | Verify LLM output meets structural requirements | Validate generated YAML parses correctly |
|
||||
|
||||
### Your Toolbox
|
||||
|
||||
**Python is the default** for all script logic (cross-platform: macOS, Linux, Windows/WSL). See `references/script-standards.md` for full rationale and safe bash commands.
|
||||
|
||||
- **Python:** Full standard library (`json`, `pathlib`, `re`, `argparse`, `collections`, `difflib`, `ast`, `csv`, `xml`, etc.) plus PEP 723 inline-declared dependencies (`tiktoken`, `jsonschema`, `pyyaml`, etc.)
|
||||
- **Safe shell commands:** `git`, `gh`, `uv run`, `npm`/`npx`/`pnpm`, `mkdir -p`
|
||||
- **Avoid bash for logic** — no piping, `jq`, `grep`, `sed`, `awk`, `find`, `diff`, `wc` in scripts. Use Python equivalents instead.
|
||||
|
||||
### The --help Pattern
|
||||
|
||||
All scripts use PEP 723 metadata and implement `--help`. Prompts can reference `scripts/foo.py --help` instead of inlining interface details — single source of truth, saves prompt tokens.
|
||||
|
||||
---
|
||||
|
||||
## Script Output Standard
|
||||
|
||||
All scripts MUST output structured JSON:
|
||||
|
||||
```json
|
||||
{
|
||||
"script": "script-name",
|
||||
"version": "1.0.0",
|
||||
"skill_path": "/path/to/skill",
|
||||
"timestamp": "2025-03-08T10:30:00Z",
|
||||
"status": "pass|fail|warning",
|
||||
"findings": [
|
||||
{
|
||||
"severity": "critical|high|medium|low|info",
|
||||
"category": "structure|security|performance|consistency",
|
||||
"location": { "file": "SKILL.md", "line": 42 },
|
||||
"issue": "Clear description",
|
||||
"fix": "Specific action to resolve"
|
||||
}
|
||||
],
|
||||
"summary": {
|
||||
"total": 0,
|
||||
"critical": 0,
|
||||
"high": 0,
|
||||
"medium": 0,
|
||||
"low": 0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Implementation Checklist
|
||||
|
||||
- [ ] `--help` with PEP 723 metadata
|
||||
- [ ] Accepts skill path as argument
|
||||
- [ ] `-o` flag for output file (defaults to stdout)
|
||||
- [ ] Diagnostics to stderr
|
||||
- [ ] Exit codes: 0=pass, 1=fail, 2=error
|
||||
- [ ] `--verbose` flag for debugging
|
||||
- [ ] Self-contained (PEP 723 for dependencies)
|
||||
- [ ] No interactive prompts, no network dependencies
|
||||
- [ ] Valid JSON to stdout
|
||||
- [ ] Tests in `scripts/tests/`
|
||||
@@ -0,0 +1,92 @@
|
||||
# Script Creation Standards
|
||||
|
||||
When building scripts for a skill, follow these standards to ensure portability and zero-friction execution. Skills must work across macOS, Linux, and Windows (native, Git Bash, and WSL).
|
||||
|
||||
## Python Over Bash
|
||||
|
||||
**Always favor Python for script logic.** Bash is not portable — it fails or behaves inconsistently on Windows (Git Bash is MSYS2-based, not a full Linux shell; WSL bash can conflict with Git Bash on PATH; PowerShell is a different language entirely). Python with `uv run` works identically on all platforms.
|
||||
|
||||
**Safe bash commands** — these work reliably across all environments and are fine to use directly:
|
||||
|
||||
- `git`, `gh` — version control and GitHub CLI
|
||||
- `uv run` — Python script execution with automatic dependency handling
|
||||
- `npm`, `npx`, `pnpm` — Node.js ecosystem
|
||||
- `mkdir -p` — directory creation
|
||||
|
||||
**Everything else should be Python** — piping, `jq`, `grep`, `sed`, `awk`, `find`, `diff`, `wc`, and any non-trivial logic. Even `sed -i` behaves differently on macOS vs Linux. If it's more than a single safe command, write a Python script.
|
||||
|
||||
## Favor the Standard Library
|
||||
|
||||
Always prefer Python's standard library over external dependencies. The stdlib is pre-installed everywhere, requires no `uv run`, and has zero supply-chain risk. Common stdlib modules that cover most script needs:
|
||||
|
||||
- `json` — JSON parsing and output
|
||||
- `pathlib` — cross-platform path handling
|
||||
- `re` — pattern matching
|
||||
- `argparse` — CLI interface
|
||||
- `collections` — counters, defaultdicts
|
||||
- `difflib` — text comparison
|
||||
- `ast` — Python source analysis
|
||||
- `csv`, `xml.etree` — data formats
|
||||
|
||||
Only pull in external dependencies when the stdlib genuinely cannot do the job (e.g., `tiktoken` for accurate token counting, `pyyaml` for YAML parsing, `jsonschema` for schema validation). **External dependencies must be confirmed with the user during the build process** — they add install-time cost, supply-chain surface, and require `uv` to be available.
|
||||
|
||||
## PEP 723 Inline Metadata (Required)
|
||||
|
||||
Every Python script MUST include a PEP 723 metadata block. For scripts with external dependencies, use the `uv run` shebang:
|
||||
|
||||
```python
|
||||
#!/usr/bin/env -S uv run --script
|
||||
# /// script
|
||||
# requires-python = ">=3.10"
|
||||
# dependencies = ["pyyaml>=6.0", "jsonschema>=4.0"]
|
||||
# ///
|
||||
```
|
||||
|
||||
For scripts using only the standard library, use a plain Python shebang but still include the metadata block:
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
# /// script
|
||||
# requires-python = ">=3.10"
|
||||
# ///
|
||||
```
|
||||
|
||||
**Key rules:**
|
||||
|
||||
- The shebang MUST be line 1 — before the metadata block
|
||||
- Always include `requires-python`
|
||||
- List all external dependencies with version constraints
|
||||
- Never use `requirements.txt`, `pip install`, or expect global package installs
|
||||
- The shebang is a Unix convenience — cross-platform invocation relies on `uv run scripts/foo.py`, not `./scripts/foo.py`
|
||||
|
||||
## Invocation in SKILL.md
|
||||
|
||||
How a built skill's SKILL.md should reference its scripts:
|
||||
|
||||
- **Scripts with external dependencies:** `uv run scripts/analyze.py {args}`
|
||||
- **Stdlib-only scripts:** `python3 scripts/scan.py {args}` (also fine to use `uv run` for consistency)
|
||||
|
||||
`uv run` reads the PEP 723 metadata, silently caches dependencies in an isolated environment, and runs the script — no user prompt, no global install. Like `npx` for Python.
|
||||
|
||||
## Graceful Degradation
|
||||
|
||||
Skills may run in environments where Python or `uv` is unavailable (e.g., claude.ai web). Scripts should be the fast, reliable path — but the skill must still deliver its outcome when execution is not possible.
|
||||
|
||||
**Pattern:** When a script cannot execute, the LLM performs the equivalent work directly. The script's `--help` documents what it checks, making this fallback natural. Design scripts so their logic is understandable from their help output and the skill's context.
|
||||
|
||||
In SKILL.md, frame script steps as outcomes, not just commands:
|
||||
|
||||
- Good: "Validate path conventions (run `scripts/scan-paths.py --help` for details)"
|
||||
- Avoid: "Execute `python3 scripts/scan-paths.py`" with no context about what it does
|
||||
|
||||
## Script Interface Standards
|
||||
|
||||
- Implement `--help` via `argparse` (single source of truth for the script's API)
|
||||
- Accept target path as a positional argument
|
||||
- `-o` flag for output file (default to stdout)
|
||||
- Diagnostics and progress to stderr
|
||||
- Exit codes: 0=pass, 1=fail, 2=error
|
||||
- `--verbose` flag for debugging
|
||||
- Output valid JSON to stdout
|
||||
- No interactive prompts, no network dependencies
|
||||
- Tests in `scripts/tests/`
|
||||
@@ -0,0 +1,109 @@
|
||||
# Skill Authoring Best Practices
|
||||
|
||||
For field definitions and description format, see `./references/standard-fields.md`. For quality dimensions, see `./references/quality-dimensions.md`.
|
||||
|
||||
## Core Philosophy: Outcome-Based Authoring
|
||||
|
||||
Skills should describe **what to achieve**, not **how to achieve it**. The LLM is capable of figuring out the approach — it needs to know the goal, the constraints, and the why.
|
||||
|
||||
**The test for every instruction:** Would removing this cause the LLM to produce a worse outcome? If the LLM would do it anyway — or if it's just spelling out mechanical steps — cut it.
|
||||
|
||||
### Outcome vs Prescriptive
|
||||
|
||||
| Prescriptive (avoid) | Outcome-based (prefer) |
|
||||
| ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
|
||||
| "Step 1: Ask about goals. Step 2: Ask about constraints. Step 3: Summarize and confirm." | "Ensure the user's vision is fully captured — goals, constraints, and edge cases — before proceeding." |
|
||||
| "Load config. Read user_name. Read communication_language. Greet the user by name in their language." | "Load available config and greet the user appropriately." |
|
||||
| "Create a file. Write the header. Write section 1. Write section 2. Save." | "Produce a report covering X, Y, and Z." |
|
||||
|
||||
The prescriptive versions miss requirements the author didn't think of. The outcome-based versions let the LLM adapt to the actual situation.
|
||||
|
||||
### Why This Works
|
||||
|
||||
- **Why over what** — When you explain why something matters, the LLM adapts to novel situations. When you just say what to do, it follows blindly even when it shouldn't.
|
||||
- **Context enables judgment** — Give domain knowledge, constraints, and goals. The LLM figures out the approach. It's better at adapting to messy reality than any script you could write.
|
||||
- **Prescriptive steps create brittleness** — When reality doesn't match the script, the LLM either follows the wrong script or gets confused. Outcomes let it adapt.
|
||||
- **Every instruction should carry its weight** — If the LLM would do it anyway, the instruction is noise. If the LLM wouldn't know to do it without being told, that's signal.
|
||||
|
||||
### When Prescriptive Is Right
|
||||
|
||||
Reserve exact steps for **fragile operations** where getting it wrong has consequences — script invocations, exact file paths, specific CLI commands, API calls with precise parameters. These need low freedom because there's one right way to do them.
|
||||
|
||||
| Freedom | When | Example |
|
||||
| ------------------- | -------------------------------------------------- | ------------------------------------------------------------------- |
|
||||
| **High** (outcomes) | Multiple valid approaches, LLM judgment adds value | "Ensure the user's requirements are complete" |
|
||||
| **Medium** (guided) | Preferred approach exists, some variation OK | "Present findings in a structured report with an executive summary" |
|
||||
| **Low** (exact) | Fragile, one right way, consequences for deviation | `python3 scripts/scan-path-standards.py {skill-path}` |
|
||||
|
||||
## Patterns
|
||||
|
||||
These are patterns that naturally emerge from outcome-based thinking. Apply them when they fit — they're not a checklist.
|
||||
|
||||
### Soft Gate Elicitation
|
||||
|
||||
At natural transitions, invite contribution without demanding it: "Anything else, or shall we move on?" Users almost always remember one more thing when given a graceful exit ramp. This produces richer artifacts than rigid section-by-section questioning.
|
||||
|
||||
### Intent-Before-Ingestion
|
||||
|
||||
Understand why the user is here before scanning documents or project context. Intent gives you the relevance filter — without it, scanning is noise.
|
||||
|
||||
### Capture-Don't-Interrupt
|
||||
|
||||
When users provide information beyond the current scope, capture it for later rather than redirecting. Users in creative flow share their best insights unprompted — interrupting loses them.
|
||||
|
||||
### Dual-Output: Human Artifact + LLM Distillate
|
||||
|
||||
Artifact-producing skills can output both a polished human-facing document and a token-efficient distillate for downstream LLM consumption. The distillate captures overflow, rejected ideas, and detail that doesn't belong in the human doc but has value for the next workflow. Always optional.
|
||||
|
||||
### Parallel Review Lenses
|
||||
|
||||
Before finalizing significant artifacts, fan out reviewers with different perspectives — skeptic, opportunity spotter, domain-specific lens. If subagents aren't available, do a single critical self-review pass. Multiple perspectives catch blind spots no single reviewer would.
|
||||
|
||||
### Three-Mode Architecture (Guided / Yolo / Headless)
|
||||
|
||||
Consider whether the skill benefits from multiple execution modes:
|
||||
|
||||
| Mode | When | Behavior |
|
||||
| ------------ | ------------------- | ------------------------------------------------------------- |
|
||||
| **Guided** | Default | Conversational discovery with soft gates |
|
||||
| **Yolo** | "just draft it" | Ingest everything, draft complete artifact, then refine |
|
||||
| **Headless** | `--headless` / `-H` | Complete the task without user input, using sensible defaults |
|
||||
|
||||
Not all skills need all three. But considering them during design prevents locking into a single interaction model.
|
||||
|
||||
### Graceful Degradation
|
||||
|
||||
Every subagent-dependent feature should have a fallback path. A skill that hard-fails without subagents is fragile — one that falls back to sequential processing works everywhere.
|
||||
|
||||
### Verifiable Intermediate Outputs
|
||||
|
||||
For complex tasks with consequences: plan → validate → execute → verify. Create a verifiable plan before executing, validate with scripts where possible. Catches errors early and makes the work reversible.
|
||||
|
||||
## Writing Guidelines
|
||||
|
||||
- **Consistent terminology** — one term per concept, stick to it
|
||||
- **Third person** in descriptions — "Processes files" not "I help process files"
|
||||
- **Descriptive file names** — `form_validation_rules.md` not `doc2.md`
|
||||
- **Forward slashes** in all paths — cross-platform
|
||||
- **One level deep** for reference files — SKILL.md → reference.md, never chains
|
||||
- **TOC for long files** — >100 lines
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
| Anti-Pattern | Fix |
|
||||
| -------------------------------------------------- | ----------------------------------------------------- |
|
||||
| Numbered steps for things the LLM would figure out | Describe the outcome and why it matters |
|
||||
| Explaining how to load config (the mechanic) | List the config keys and their defaults (the outcome) |
|
||||
| Prescribing exact greeting/menu format | "Greet the user and present capabilities" |
|
||||
| Spelling out headless mode in detail | "If headless, complete without user input" |
|
||||
| Too many options upfront | One default with escape hatch |
|
||||
| Deep reference nesting (A→B→C) | Keep references 1 level from SKILL.md |
|
||||
| Inconsistent terminology | Choose one term per concept |
|
||||
| Scripts that classify meaning via regex | Intelligence belongs in prompts, not scripts |
|
||||
|
||||
## Scripts in Skills
|
||||
|
||||
- **Execute vs reference** — "Run `analyze.py`" (execute) vs "See `analyze.py` for the algorithm" (read)
|
||||
- **Document constants** — explain why `TIMEOUT = 30`, not just what
|
||||
- **PEP 723 for Python** — self-contained with inline dependency declarations
|
||||
- **MCP tools** — use fully qualified names: `ServerName:tool_name`
|
||||
@@ -0,0 +1,143 @@
|
||||
# Standard Workflow/Skill Fields
|
||||
|
||||
## Frontmatter Fields
|
||||
|
||||
Only these fields go in the YAML frontmatter block:
|
||||
|
||||
| Field | Description | Example |
|
||||
| ------------- | ---------------------------------------------------- | --------------------------------------------- |
|
||||
| `name` | Full skill name (kebab-case, same as folder name) | `bmad-workflow-builder`, `bmad-validate-json` |
|
||||
| `description` | [5-8 word summary]. [Use when user says 'X' or 'Y'.] | See Description Format below |
|
||||
|
||||
## Content Fields (All Types)
|
||||
|
||||
These are used within the SKILL.md body — never in frontmatter:
|
||||
|
||||
| Field | Description | Example |
|
||||
| --------------- | ----------------------------- | --------------------------------- |
|
||||
| `role-guidance` | Brief expertise primer | "Act as a senior DevOps engineer" |
|
||||
| `module-code` | Module code (if module-based) | `bmb`, `cis` |
|
||||
|
||||
## Simple Utility Fields
|
||||
|
||||
| Field | Description | Example |
|
||||
| --------------- | ----------------------------------- | ------------------------------------------- |
|
||||
| `input-format` | What it accepts | JSON file path, stdin text |
|
||||
| `output-format` | What it returns | Validated JSON, error report |
|
||||
| `standalone` | Fully standalone, no config needed? | true/false |
|
||||
| `composability` | How other skills use it | "Called by quality scanners for validation" |
|
||||
|
||||
## Simple Workflow Fields
|
||||
|
||||
| Field | Description | Example |
|
||||
| ------------ | --------------------- | ----------------------------------------- |
|
||||
| `steps` | Numbered inline steps | "1. Load config 2. Read input 3. Process" |
|
||||
| `tools-used` | CLIs/tools/scripts | gh, jq, python scripts |
|
||||
| `output` | What it produces | PR, report, file |
|
||||
|
||||
## Complex Workflow Fields
|
||||
|
||||
| Field | Description | Example |
|
||||
| ------------------------ | --------------------------------- | ------------------------------------- |
|
||||
| `stages` | Named numbered stages | "01-discover, 02-plan, 03-build" |
|
||||
| `progression-conditions` | When stages complete | "User approves outline" |
|
||||
| `headless-mode` | Supports autonomous? | true/false |
|
||||
| `config-variables` | Beyond core vars | `planning_artifacts`, `output_folder` |
|
||||
| `output-artifacts` | What it creates (output-location) | "PRD document", "agent skill" |
|
||||
|
||||
## Overview Section Format
|
||||
|
||||
The Overview is the first section after the title — it primes the AI for everything that follows.
|
||||
|
||||
**3-part formula:**
|
||||
|
||||
1. **What** — What this workflow/skill does
|
||||
2. **How** — How it works (approach, key stages)
|
||||
3. **Why/Outcome** — Value delivered, quality standard
|
||||
|
||||
**Templates by skill type:**
|
||||
|
||||
**Complex Workflow:**
|
||||
|
||||
```markdown
|
||||
This skill helps you {outcome} through {approach}. Act as {role-guidance}, guiding users through {key stages}. Your output is {deliverable}.
|
||||
```
|
||||
|
||||
**Simple Workflow:**
|
||||
|
||||
```markdown
|
||||
This skill {what it does} by {approach}. Act as {role-guidance}. Use when {trigger conditions}. Produces {output}.
|
||||
```
|
||||
|
||||
**Simple Utility:**
|
||||
|
||||
```markdown
|
||||
This skill {what it does}. Use when {when to use}. Returns {output format} with {key feature}.
|
||||
```
|
||||
|
||||
## SKILL.md Description Format
|
||||
|
||||
The frontmatter `description` is the PRIMARY trigger mechanism — it determines when the AI invokes this skill. Most BMad skills are **explicitly invoked** by name (`/skill-name` or direct request), so descriptions should be conservative to prevent accidental triggering.
|
||||
|
||||
**Format:** Two parts, one sentence each:
|
||||
|
||||
```
|
||||
[What it does in 5-8 words]. [Use when user says 'specific phrase' or 'specific phrase'.]
|
||||
```
|
||||
|
||||
**The trigger clause** uses one of these patterns depending on the skill's activation style:
|
||||
|
||||
- **Explicit invocation (default):** `Use when the user requests to 'create a PRD' or 'edit an existing PRD'.` — Quotes around specific phrases the user would actually say. Conservative — won't fire on casual mentions.
|
||||
- **Organic/reactive:** `Trigger when code imports anthropic SDK, or user asks to use Claude API.` — For lightweight skills that should activate on contextual signals, not explicit requests.
|
||||
|
||||
**Examples:**
|
||||
|
||||
Good (explicit): `Builds workflows and skills through conversational discovery. Use when the user requests to 'build a workflow', 'modify a workflow', or 'quality check workflow'.`
|
||||
|
||||
Good (organic): `Initializes BMad project configuration. Trigger when any skill needs module-specific configuration values, or when setting up a new BMad project.`
|
||||
|
||||
Bad: `Helps with PRDs and product requirements.` — Too vague, would trigger on any mention of PRD even in passing conversation.
|
||||
|
||||
Bad: `Use on any mention of workflows, building, or creating things.` — Over-broad, would hijack unrelated conversations.
|
||||
|
||||
**Default to explicit invocation** unless the user specifically describes organic/reactive activation during discovery.
|
||||
|
||||
## Role Guidance Format
|
||||
|
||||
Every generated workflow SKILL.md includes a brief role statement in the Overview or as a standalone line:
|
||||
|
||||
```markdown
|
||||
Act as {role-guidance}. {brief expertise/approach description}.
|
||||
```
|
||||
|
||||
This provides quick prompt priming for expertise and tone. Workflows may also use full Identity/Communication Style/Principles sections when personality serves the workflow's purpose.
|
||||
|
||||
## Path Rules
|
||||
|
||||
### Skill-Internal Files
|
||||
|
||||
All references to files within the skill use `./` prefix:
|
||||
|
||||
- `./references/reference.md`
|
||||
- `./references/discover.md`
|
||||
- `./scripts/validate.py`
|
||||
|
||||
This distinguishes skill-internal files from `{project-root}` paths — without the `./` prefix the LLM may confuse them.
|
||||
|
||||
### Project `_bmad` Paths
|
||||
|
||||
Use `{project-root}/_bmad/...`:
|
||||
|
||||
- `{project-root}/_bmad/planning/prd.md`
|
||||
|
||||
### Config Variables
|
||||
|
||||
Use directly — they already contain `{project-root}` in their resolved values:
|
||||
|
||||
- `{output_folder}/file.md`
|
||||
- `{planning_artifacts}/prd.md`
|
||||
|
||||
**Never:**
|
||||
|
||||
- `{project-root}/{output_folder}/file.md` (WRONG — double-prefix, config var already has path)
|
||||
- `_bmad/planning/prd.md` (WRONG — bare `_bmad` must have `{project-root}` prefix)
|
||||
@@ -0,0 +1,35 @@
|
||||
# Template Substitution Rules
|
||||
|
||||
The SKILL-template provides a minimal skeleton: frontmatter, overview, and activation with config loading. Everything beyond that is crafted by the builder based on what was learned during discovery and requirements phases.
|
||||
|
||||
## Frontmatter
|
||||
|
||||
- `{module-code-or-empty}` → Module code prefix with hyphen (e.g., `bmb-`) or empty for standalone
|
||||
- `{skill-name}` → Skill functional name (kebab-case)
|
||||
- `{skill-description}` → Two parts: [5-8 word summary]. [trigger phrases]
|
||||
|
||||
## Module Conditionals
|
||||
|
||||
### For Module-Based Skills
|
||||
|
||||
- `{if-module}` ... `{/if-module}` → Keep the content inside
|
||||
- `{if-standalone}` ... `{/if-standalone}` → Remove the entire block including markers
|
||||
- `{module-code}` → Module code without trailing hyphen (e.g., `bmb`)
|
||||
- `{module-setup-skill}` → Name of the module's setup skill (e.g., `bmad-builder-setup`)
|
||||
|
||||
### For Standalone Skills
|
||||
|
||||
- `{if-module}` ... `{/if-module}` → Remove the entire block including markers
|
||||
- `{if-standalone}` ... `{/if-standalone}` → Keep the content inside
|
||||
|
||||
## Beyond the Template
|
||||
|
||||
The builder determines the rest of the skill structure — body sections, phases, stages, scripts, external skills, headless mode, role guidance — based on the skill type classification and requirements gathered during the build process. The template intentionally does not prescribe these; the builder has the context to craft them.
|
||||
|
||||
## Path References
|
||||
|
||||
All generated skills use `./` prefix for skill-internal paths:
|
||||
|
||||
- `./references/{reference}.md` — Reference documents loaded on demand
|
||||
- `./references/{stage}.md` — Stage prompts (complex workflows)
|
||||
- `./scripts/` — Python/shell scripts for deterministic operations
|
||||
Reference in New Issue
Block a user