mathodology-skill-authoring
starsforks
How to install mathodology-skill-authoring?
sweetcornna/mathodology/mathodology-skill-authoring
$npx -y skills add sweetcornna/mathodology --skill mathodology-skill-authoringUse when adding, updating, validating, or reviewing Mathodology project skills, SKILL.md files, or agents/openai.yaml metadata.
SKILL.md
| 1 | # Mathodology Skill Authoring |
| 2 | |
| 3 | ## Scope |
| 4 | |
| 5 | This repository currently has one skill system: project skills under `.claude/skills/`. |
| 6 | |
| 7 | Each skill directory contains: |
| 8 | |
| 9 | ```text |
| 10 | SKILL.md |
| 11 | agents/openai.yaml |
| 12 | ``` |
| 13 | |
| 14 | No separate product runtime skill directory is present on this branch. |
| 15 | |
| 16 | Claude Code orchestration assets are adjacent to skills: |
| 17 | |
| 18 | ```text |
| 19 | .claude/agents/<agent-name>.md |
| 20 | .claude/workflows/<workflow-name>.md |
| 21 | ``` |
| 22 | |
| 23 | Codex orchestration belongs inside `SKILL.md`, `agents/openai.yaml`, and `docs/WORKFLOWS.md`. |
| 24 | |
| 25 | ## Frontmatter Rules |
| 26 | |
| 27 | Every `SKILL.md` needs YAML frontmatter with: |
| 28 | |
| 29 | ```yaml |
| 30 | --- |
| 31 | name: mathodology-example |
| 32 | description: Use when ... |
| 33 | --- |
| 34 | ``` |
| 35 | |
| 36 | Rules: |
| 37 | |
| 38 | - `name` must match the directory name. |
| 39 | - `description` must start with `Use when`. |
| 40 | - Keep descriptions trigger-focused; do not summarize the whole workflow. |
| 41 | - Keep frontmatter concise. |
| 42 | |
| 43 | ## Body Rules |
| 44 | |
| 45 | Skills should be reusable process guidance, not a record of one editing session. |
| 46 | |
| 47 | For this skills-only branch: |
| 48 | |
| 49 | - Be explicit when subsystem knowledge is historical. |
| 50 | - Do not link to current files that are no longer present. |
| 51 | - Do not list old build or test commands as active validation gates. |
| 52 | - Keep current-branch edits limited to skills, metadata, Claude Code agents/workflows, docs, and backup helper files. |
| 53 | |
| 54 | ## Adapter Rules |
| 55 | |
| 56 | Claude Code adaptation: |
| 57 | |
| 58 | - Put reusable project subagent definitions in `.claude/agents/`. |
| 59 | - Put repeatable phase workflow templates in `.claude/workflows/`. |
| 60 | - Keep each subagent role narrow and gate-driven. |
| 61 | - Mention which Mathodology skill the subagent should load. |
| 62 | |
| 63 | Codex adaptation: |
| 64 | |
| 65 | - Put startup prompts and multi-agents rules in `SKILL.md` and `docs/WORKFLOWS.md`. |
| 66 | - Keep `agents/openai.yaml` default prompts explicit enough to trigger the right skill. |
| 67 | - Phrase Codex instructions as phase tasks with synthesis and independent critic gates. |
| 68 | |
| 69 | ## Metadata |
| 70 | |
| 71 | Each project skill should have `agents/openai.yaml` with: |
| 72 | |
| 73 | ```yaml |
| 74 | interface: |
| 75 | display_name: "Readable Name" |
| 76 | short_description: "Short UI label" |
| 77 | default_prompt: "Use $skill-name ..." |
| 78 | ``` |
| 79 | |
| 80 | The default prompt must mention the matching `$skill-name`. |
| 81 | |
| 82 | ## Validation |
| 83 | |
| 84 | Run the shared validator from the repository root; it covers frontmatter, |
| 85 | metadata, links, whitelist, agents, and doc sync: |
| 86 | |
| 87 | ```bash |
| 88 | python3 .claude/skills/mathodology-dev-test-release/scripts/validate_repo.py all |
| 89 | ``` |
| 90 | |
| 91 | Use a single subcommand (`skills`, `metadata`, `links`, `whitelist`, `agents`, |
| 92 | `sync`, `selftest`) while iterating. |
| 93 | |
| 94 | Rules for validation logic and scripts: |
| 95 | |
| 96 | - Shared validation logic lives ONLY in |
| 97 | `.claude/skills/mathodology-dev-test-release/scripts/validate_repo.py`. Never |
| 98 | re-inline these checks as heredocs in a SKILL.md, doc, or agent file; extend |
| 99 | the script instead. |
| 100 | - A skill MAY ship a `scripts/` directory. Every shipped script must be |
| 101 | executable, carry a `--self-test` (or `selftest` subcommand) that is run and |
| 102 | passes before shipping, and declare its prerequisites with an actionable error |
| 103 | when one is missing. |
| 104 | - Run-time gate contracts (the `handoff` / `gate` / `scorecard` / |
| 105 | `decision_memo` schemas, judge thresholds, and QA scripts) belong to |
| 106 | `mathodology-award-gates`. Reference that skill; do not invent new inline gate |
| 107 | formats in individual skills or agents. |
| 108 | |
| 109 | ## Update Checklist |
| 110 | |
| 111 | 1. Pick the narrowest skill that owns the behavior. |
| 112 | 2. Edit `SKILL.md`. |
| 113 | 3. Update `agents/openai.yaml` if display text or default prompt should change. |
| 114 | 4. Run validation. |
| 115 | 5. Check that no non-skills files were added back to the repository. |
People who liked this also viewed
6 picksType
- hyperframes-cliUse the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish, cloud, SkillsJul 2026
- request-refactor-planSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
- analyze-projectRigor Analyze / Rigor Audit read-only skill for deep learning research repositories. Use when the user wants to read and understand a repository, inspect model structure and training or inference entrSkillsMay 2026
- explore-codeRigor Improve implementation leaf skill for auditable candidate implementation in deep learning research repositories. Use when the researcher explicitly authorizes exploratory work on an isolated braSkillsMay 2026
- ubiquitous-languageSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
- scaffold-exercisesSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
