mathodology-skill-authoring ยท diff
git:20260704.8b57eb0 to git:20260907.0cfcd93
21 added, 110 removed. Audit A to A.
---
name: mathodology-skill-authoring
- description: Use when adding, updating, validating, or reviewing Mathodology project skills, SKILL.md files, or agents/openai.yaml metadata.
+ description: Use when adding, editing or reviewing skills, role prompts or skill metadata.
---
# Mathodology Skill Authoring
- ## Scope
-
- This repository currently has one skill system: project skills under `.claude/skills/`.
-
- Each skill directory contains:
-
- ```text
- SKILL.md
- agents/openai.yaml
- ```
-
- No separate product runtime skill directory is present on this branch.
-
- Claude Code orchestration assets are adjacent to skills:
-
- ```text
- .claude/agents/<agent-name>.md
- .claude/workflows/<workflow-name>.md
- ```
-
- Codex orchestration belongs inside `SKILL.md`, `agents/openai.yaml`, and `docs/WORKFLOWS.md`.
-
- ## Frontmatter Rules
-
- Every `SKILL.md` needs YAML frontmatter with:
-
- ```yaml
- ---
- name: mathodology-example
- description: Use when ...
- ---
- ```
-
- Rules:
-
- - `name` must match the directory name.
- - `description` must start with `Use when`.
- - Keep descriptions trigger-focused; do not summarize the whole workflow.
- - Keep frontmatter concise.
-
- ## Body Rules
-
- Skills should be reusable process guidance, not a record of one editing session.
-
- For this skills-only branch:
-
- - Be explicit when subsystem knowledge is historical.
- - Do not link to current files that are no longer present.
- - Do not list old build or test commands as active validation gates.
- - Keep current-branch edits limited to skills, metadata, Claude Code agents/workflows, docs, and backup helper files.
-
- ## Adapter Rules
-
- Claude Code adaptation:
-
- - Put reusable project subagent definitions in `.claude/agents/`.
- - Put repeatable phase workflow templates in `.claude/workflows/`.
- - Keep each subagent role narrow and gate-driven.
- - Mention which Mathodology skill the subagent should load.
-
- Codex adaptation:
-
- - Put startup prompts and multi-agents rules in `SKILL.md` and `docs/WORKFLOWS.md`.
- - Keep `agents/openai.yaml` default prompts explicit enough to trigger the right skill.
- - Phrase Codex instructions as phase tasks with synthesis and independent critic gates.
-
- ## Metadata
-
- Each project skill should have `agents/openai.yaml` with:
-
- ```yaml
- interface:
- display_name: "Readable Name"
- short_description: "Short UI label"
- default_prompt: "Use $skill-name ..."
- ```
-
- The default prompt must mention the matching `$skill-name`.
-
- ## Validation
-
- Run the shared validator from the repository root; it covers frontmatter,
- metadata, links, whitelist, agents, and doc sync:
-
- ```bash
- python3 .claude/skills/mathodology-dev-test-release/scripts/validate_repo.py all
- ```
-
- Use a single subcommand (`skills`, `metadata`, `links`, `whitelist`, `agents`,
- `sync`, `selftest`) while iterating.
+ Write reusable guidance around decisions, evidence and useful outputs. Explain
+ when a method helps, how to recognize failure and when a simpler approach is
+ better. Avoid mandatory phases, handoff schemas, arbitrary scores and prose
+ that merely repeats another skill. Link the owning skill instead.
- Rules for validation logic and scripts:
+ Every skill has SKILL.md frontmatter with a `name` equal to its directory and
+ a trigger-focused `description` starting with `Use when`. Its agents/openai.yaml
+ contains display_name, short_description and a default_prompt mentioning the
+ matching `$skill-name`. These metadata files are discovery interfaces, not a
+ workflow engine. Use concise role definitions; inherit the host's model choice.
- - Shared validation logic lives ONLY in
- `.claude/skills/mathodology-dev-test-release/scripts/validate_repo.py`. Never
- re-inline these checks as heredocs in a SKILL.md, doc, or agent file; extend
- the script instead.
- - A skill MAY ship a `scripts/` directory. Every shipped script must be
- executable, carry a `--self-test` (or `selftest` subcommand) that is run and
- passes before shipping, and declare its prerequisites with an actionable error
- when one is missing.
- - Run-time gate contracts (the `handoff` / `gate` / `scorecard` /
- `decision_memo` schemas, judge thresholds, and QA scripts) belong to
- `mathodology-award-gates`. Reference that skill; do not invent new inline gate
- formats in individual skills or agents.
+ Put detailed figure recipes, source provenance and examples in references or
+ examples directories within the owning skill. Keep the entry point short and
+ load only the references relevant to the task. Preserve third-party licensing;
+ never execute downloaded source snapshots as an installation step.
- ## Update Checklist
+ Small scripts are appropriate when they perform concrete work such as plotting,
+ backup or rendering. Keep them optional, declare dependencies, and verify the
+ behavior they actually promise. Do not create a framework to enforce prompts.
- 1. Pick the narrowest skill that owns the behavior.
- 2. Edit `SKILL.md`.
- 3. Update `agents/openai.yaml` if display text or default prompt should change.
- 4. Run validation.
- 5. Check that no non-skills files were added back to the repository.
+ Update all affected entry points, role skill lists, metadata and English/Chinese
+ documentation. Keep each language natural; heading or code-block counts need
+ not match. Check that commands, capabilities and links agree. Use
+ [maintenance](../mathodology-dev-test-release/SKILL.md) for mechanical checks.