create-skill

# Create a PINA Skill > [!IMPORTANT] > Read [RULES.md](../RULES.md) before using this skill — it applies to all skills. Use this skill to create new PINA development skills or modify existing ones. Each PINA skill lives at `.opencode/skills/<name>/SKILL.md` and must be made available to all three tools (opencode, Claude Code, Codex CLI). ## Overview A PINA skill is a markdown file with YAML front matter that provides guided instructions for a specific PINA development task. Skills are auto-discovered by opencode, symlinked for Claude Code, and discoverable via the root `AGENTS.md` for Codex CLI. ### What makes a good PINA skill - **Narrow scope** — One focused task (e.g. defining domains, not "all of PINA") - **Concrete templates** — Copy-paste-ready code snippets using PINA's API - **Checklists** — Verifiable steps so the user knows when they're done - **Progressive disclosure** — Start with the common case, then branch to edge cases - **Why, not just what** — Explain why PINA conventions exist (e.g. why operators trigger a backward pass per call) ### Anatomy of a skill ``` .opencode/skills/<name>/ ├── SKILL.md (required) │ ├── YAML front matter (name, description, license, compatibility, metadata) │ └── Markdown instructions └── (optional resources) ``` ## Step 1 — Capture intent Understand what the user wants the skill to do: 1. **What PINA task should this skill guide?** (e.g. "setting up boundary conditions", "defining custom PDEs", "discretising domains") 2. **Who is the audience?** (new PINA users, experienced users, or both) 3. **What existing skill is closest?** — Check `.opencode/skills/` for related skills. If this skill extends an existing workflow, reference it. 4. **What PINA APIs does it need to cover?** — List the classes, functions, and import paths. ## Step 2 — Study existing skills as templates Read the existing PINA skills for style and structure. Key patterns: | File | Purpose | Reference pattern | |------|---------|-------------------| | `create-problem/SKILL.md` | Entry point, decision tree, templates | Multiple templates per audience, step-by-step flow, checklist | | `define-equations/SKILL.md` | Equation definition | Zoo reference table, custom signatures, edge cases | | `define-domains/SKILL.md` | Domain creation | Domain types table, common patterns, discretisation | | `condition-setup/SKILL.md` | Condition binding | Condition types table, data type options | ### Front matter template Use the same front matter format as existing skills: ```yaml --- name: <kebab-case-name> description: >- One or two sentences describing when this skill triggers. Include specific user phrases and contexts that should activate it. Be slightly "pushy" — err on the side of including near-miss use cases so the skill triggers when it should. license: MIT compatibility: opencode, codex, claude metadata: audience: users workflow: <workflow-name> --- ``` ### Writing guidelines - **Imperative voice** — "Define the domains", "Create the condition dict" - **Explain the why** — LLMs work better when they understand the reasoning behind conventions - **Use tables** for API references and option lists (consistent with existing skills) - **Provide templates** — At least one complete code template the user can adapt - **Checklists** at the end — Verifiable completion criteria - **Front matter `description`** is the primary trigger — include when-to-use context that matches real user phrasing ## Step 3 — Write the SKILL.md Organise content with progressive disclosure: ```markdown # [Title] > [!IMPORTANT] > Read [RULES.md](../RULES.md) before using this skill — it applies to all skills. > (If sub-skill: This is a sub-skill of **parent-skill**. Load the entry-point skill first.) Use this skill to [concise purpose statement]. ## Step 1 — [First step] ... ## Step N — [Last step] ## Templates ... ## Checklist - [ ] ... ``` ### Cross-tool compatibility Every new skill **must** be made available to all three tools. Include this checklist item and guide the user through the steps: 1. **opencode** — The skill at `.opencode/skills/<name>/SKILL.md` is auto-discovered. No extra step needed. 2. **Claude Code** — Create a symlink: ```bash mkdir -p .claude/skills/<name> ln -sf ../../../.opencode/skills/<name>/SKILL.md .claude/skills/<name>/SKILL.md ``` 3. **Codex CLI** — Create a symlink (same pattern): ```bash mkdir -p .agents/skills/<name> ln -sf ../../../.opencode/skills/<name>/SKILL.md .agents/skills/<name>/SKILL.md ``` The relative path `../../../.opencode/skills/<name>/SKILL.md` works from both symlink directories (3 `..` to root, then into `.opencode/`). ## Step 4 — Verify cross-tool setup After writing the skill, verify both symlinks resolve: ```bash test -f .claude/skills/<name>/SKILL.md && echo "claude: OK" test -f .agents/skills/<name>/SKILL.md && echo "codex: OK" ``` ## Step 5 — Review and iterate Present the skill to the user for review. Check: - Does the front matter `description` clearly convey when to use this skill? - Are the templates syntactically correct PINA code? - Is the cross-tool compatibility checklist complete? - Does the skill reference [RULES.md](../RULES.md) and link to related skills? ## Templates ### Template 1: New PINA skill (minimal) ```yaml --- name: my-new-skill description: >- Guides users through [task]. Use when the user asks about [topic] or needs help with [specific problem]. license: MIT compatibility: opencode, codex, claude metadata: audience: users workflow: my-workflow --- ``` ### Template 2: Symlinks for all three tools After creating `.opencode/skills/my-new-skill/SKILL.md`: ```bash mkdir -p .claude/skills/my-new-skill ln -sf ../../../.opencode/skills/my-new-skill/SKILL.md .claude/skills/my-new-skill/SKILL.md mkdir -p .agents/skills/my-new-skill ln -sf ../../../.opencode/skills/my-new-skill/SKILL.md .agents/skills/my-new-skill/SKILL.md test -f .claude/skills/my-new-skill/SKILL.md && echo "claude: OK" test -f .agents/skills/my-new-skill/SKILL.md && echo "codex: OK" ``` ## Checklist - [ ] `name` is kebab-case, unique across `.opencode/skills/` - [ ] `description` front matter includes trigger context (when to use) - [ ] `compatibility: opencode, codex, claude` is set - [ ] `metadata.audience` and `metadata.workflow` are set - [ ] Skill references [RULES.md](../RULES.md) at the top - [ ] Sub-skills reference their parent entry-point skill - [ ] At least one complete code template is provided - [ ] Cross-tool setup is complete: - [ ] `.claude/skills/<name>/SKILL.md` symlink exists and resolves - [ ] `.agents/skills/<name>/SKILL.md` symlink exists and resolves