Create Skill

Create a PINA Skill

[!IMPORTANT] Read 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:

Front matter template

Use the same front matter format as existing skills:

---
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:

# [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:

   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):

   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:

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 and link to related skills?

Templates

Template 1: New PINA skill (minimal)

---
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:

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 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