NeqSim Skills and Agents

TL;DR — Quick Start by Extension Type

I want to… Do this
Use an existing core skill Nothing — workspace agents load them automatically from the .github/skills/ discovery layer
Create a new core skill neqsim new-skill "name" → edit SKILL.md → register in README + copilot-instructions → PR
Install a community skill neqsim skill install neqsim-topic → canonical install in ~/.neqsim/skills → export with --target vscode or --target generic
Install a community agent neqsim agent install agent-name → canonical install in ~/.neqsim/agents → export with --target vscode or --target generic
Check PaperLab commands neqsim paperlab prints help only; this confirms the command exists but does not install anything
Use PaperLab in VS Code neqsim paperlab install --vscode for the @paperlab gateway; add --include-internal only for direct specialist-agent compatibility
Publish my skill to the community Host SKILL.md in a GitHub repo → neqsim skill publish user/repo → PR gets reviewed
Set up company enterprise repos Create private enterprise skills + agents repos → publish enterprise-skills.yaml and enterprise-agents.yaml → configure EH_SOURCES_FILE for the Engineering Harness
Create a private/local skill Put SKILL.md under ~/.neqsim/skills/<name>/ or a private catalog → export with --target vscode or --target generic
Share private skills with my team neqsim skill private-init → edit ~/.neqsim/private-skills.yaml → distribute to team

Read on for the full details of each workflow.

Skills are the knowledge layer of NeqSim’s agentic engineering system. They are structured markdown documents that encode domain-specific expertise — API patterns, code templates, decision rules, reference data, common error patterns, and recovery strategies — in a format that AI agents can read, interpret, and apply to engineering tasks.

Agents are the workflow layer. An agent defines a role, objective, constraints, handoff pattern, and the skills it expects to load. In professional agent tools this separation is common: skills are reusable capabilities; agents are curated workflows that combine those capabilities for a specific job.

This guide covers skills, installable agents, how to create each type, and how they work together. For company-private enterprise repositories and installable internal catalogs, see Enterprise Agent and Skill Repositories. For the current cross-catalog dependency overview, see Agent to Skill Map.

Where the catalogs live

Catalog Purpose Location
Community agents Public AI agent workflows (thermodynamics, process, flow assurance, energy, field development) equinor/neqsim-community-agents
Community skills Public reusable engineering skills for agentic workflows equinor/neqsim-community-skills
Enterprise agents / skills Internal, company-private agents and skills — governed in private repos; never committed to public NeqSim repos Private company repos (enterprise-agents.yaml / enterprise-skills.yaml)

Browse and install with neqsim agent list / neqsim skill list, then neqsim agent install <name> / neqsim skill install <name>.

Version compatibility across repos

The catalogs are versioned independently of the core NeqSim library. To keep a professional setup reproducible:

Layer Versioning Compatibility rule
NeqSim core Semantic version (e.g. 3.16.0), Maven Central The baseline everything targets.
Community / enterprise skills Per-skill version in SKILL.md frontmatter A skill states the minimum NeqSim version it was verified against; skills avoid depending on unreleased APIs.
Community / enterprise agents Per-agent version + declared required_skills An agent works when its required_skills are installed at a compatible version and the target NeqSim core meets each skill’s minimum.

Guidance for reproducible environments:

Canonical Installs and Tool Exports

NeqSim separates source-of-truth content from tool-specific discovery folders:

Layer Purpose Typical path
Core workspace discovery Skills and agents committed with NeqSim and visible to VS Code in this workspace .github/skills/, .github/agents/
User-level canonical install Community, private, and enterprise content installed for one user without modifying the repo ~/.neqsim/skills/, ~/.neqsim/agents/
VS Code export Generated compatibility copies for VS Code Copilot discovery ~/.copilot/skills for installed skills and ~/.copilot/agents for installed agents (the personal folders VS Code and the GitHub Copilot CLI scan in every workspace); .github/skills and .github/agents only for explicit --vscode-scope workspace exports
Generic export Tool-neutral copies and manifest for Codex, Claude, harnesses, or other coding agents ~/.neqsim/export/generic/
PaperLab canonical source PaperLab’s full internal role and skill library neqsim-paperlab/agents/, neqsim-paperlab/skills/

Treat .github/skills and .github/agents as core workspace discovery surfaces, not the default destination for installed community/private content. Installed content should be managed through ~/.neqsim and, for VS Code, exported to the personal ~/.copilot/skills and ~/.copilot/agents folders unless a maintainer explicitly wants a workspace export. (VS Code does not discover skills from its User prompts folder — that folder feeds prompt/instruction/agent files only, so --vscode skill export targets ~/.copilot/skills.) PaperLab follows the same principle: neqsim-paperlab/ is canonical, while the VS Code default is the single @paperlab gateway plus its declared public skills.

For the exact PaperLab CLI commands, including the no-subcommand help output, list, --dry-run, and the actual install command, see PaperLab CLI and VS Code Chat Install.

The Four Types of Skills

NeqSim’s skill system is organised into four tiers, each with a different scope, audience, and lifecycle:

Type Location Scope Who Creates Version Controlled
Core Program Skills .github/skills/ discovery layer in the NeqSim repo All users, all agents NeqSim maintainers Yes (Git, PR review)
Community Skills External repos, listed in community-skills.yaml Anyone who installs them Domain experts, contributors Yes (author’s repo)
Enterprise Skills Private company repos, listed in enterprise-skills.yaml Company/project runtimes Company domain owners Yes (private Git, governed review)
Local Private Skills ~/.neqsim/skills/ on your machine, exported per tool when needed Only you You Optional (your choice)

Core Program Skills

These are the workspace-visible skills shipped with NeqSim. They cover NeqSim’s own API (neqsim-api-patterns), Java 8 rules (neqsim-java8-rules), and domain expertise that references NeqSim internals (flow assurance, CCS, distillation, platform modeling, etc.). Agents load these automatically when relevant.

Examples: neqsim-api-patterns, neqsim-flow-assurance, neqsim-troubleshooting, neqsim-platform-modeling

Community Skills

Skills contributed by the community but hosted outside the core repo. They are listed in the machine-readable community-skills.yaml catalog and installed via the CLI tool. Community skills cover public workflows and domains that do not require deep NeqSim internal knowledge or company-private policy.

Examples: educational screening checks, public regional regulatory workflows, alternative EOS validation approaches

Enterprise Skills and Agents

Enterprise skills and agents live in private company repositories. They are listed in enterprise-skills.yaml and enterprise-agents.yaml, declare trust: internal, and are installed by configuring the runtime’s plugin sources. Enterprise skills use enterprise-* IDs and may extend approved public neqsim-* skills. Enterprise agents orchestrate both layers through required_skills.

Examples: company hydrate-margin policy overlays, governed STID-to-NeqSim study preparation, internal document-reading workflows, plant-data integration wrappers

See Enterprise Agent and Skill Repositories for the repository template, catalog examples, plugins/sources.yaml configuration, token handling, and validation commands.

Local Private Skills

Skills stored on your own machine at ~/.neqsim/skills/. These encode private or company-specific knowledge that should never be committed to a public repository — plant historian tag mappings, internal STID retrieval procedures, company standards, proprietary workflows. Export them to VS Code or generic agent folders only when a tool needs a discovery copy.

Examples: Equinor STID document retrieval, plant data reading from specific PI servers, company TR document requirements

How Skills Work

When an agent receives a task, the skill loading process works as follows:

  1. Request analysis — The agent examines the user’s request and identifies the engineering domain(s) involved.
  2. Skill matching — The agent compares the identified domains against skill descriptions. Each skill’s description and USE WHEN clause provides matching criteria.
  3. Selective loading — Only matched skills are loaded into the agent’s context using read_file. A hydrate calculation loads neqsim-flow-assurance and neqsim-api-patterns. A distillation design loads neqsim-distillation-design and neqsim-api-patterns.
  4. Application — The agent combines its general reasoning capabilities with the skill’s specific domain knowledge to produce correct, working code and analysis.

This dynamic loading keeps the agent’s finite context window focused on task-relevant knowledge rather than loading all 28+ skills at once.

Anatomy of a Skill File

Every skill follows the same structure regardless of type. Here is the anatomy of a SKILL.md file:

---
name: neqsim-my-topic
version: "1.0.0"
description: "Short description. USE WHEN: trigger conditions for when agents should load this skill."
last_verified: "2026-04-19"
requires:
  python_packages: [pandas]    # pip packages needed to run patterns
  # java_packages: []           # Maven artifacts beyond NeqSim core
  # env: [MY_API_KEY]           # environment variables needed at runtime
  # network: [equinor-vpn]      # network access requirements
---

# Skill Title

One-paragraph summary of what this skill covers and when agents should load it.

## When to Use This Skill

- When the user asks about [topic]
- When a task involves [specific operation]

## Key Concepts

### Concept 1
Explanation of domain concepts the agent needs to understand.

## NeqSim Code Patterns

### Pattern: Basic Setup
```java
// Java 8 compatible — no var, List.of(), etc.
SystemInterface fluid = new SystemSrkEos(273.15 + 25.0, 60.0);
fluid.addComponent("methane", 0.85);
fluid.setMixingRule("classic");

Pattern: Python (Jupyter)

from neqsim import jneqsim
fluid = jneqsim.thermo.system.SystemSrkEos(273.15 + 25.0, 60.0)

Common Mistakes

Symptom Cause Fix
Zero viscosity after flash Missing initProperties() Add fluid.initProperties() after flash

References

The key sections and their purposes:

Section Purpose
YAML frontmatter Machine-readable metadata: name, version, description with USE WHEN triggers, verification date, dependency declarations
When to Use Explicit trigger conditions so agents know when to load the skill
Key Concepts Domain knowledge the agent needs to reason correctly
Code Patterns Copy-paste templates with inline comments marking mandatory steps
Common Mistakes Error catalog: symptom, cause, fix — prevents agents from repeating known failures
References Standards, papers, and documentation links for traceability

Frontmatter Fields

Field Required Description
name Yes Unique identifier, must start with neqsim-
version Yes Semver version (e.g., "1.0.0"). Bump major for breaking changes, minor for new patterns, patch for fixes
description Yes Short description including USE WHEN: trigger clause
last_verified Yes ISO date when code patterns were last tested against NeqSim
requires No Dependency declarations (see below)
requires.python_packages No Python packages needed (e.g., [tagreader, pandas])
requires.java_packages No Maven artifacts beyond NeqSim core
requires.env No Environment variables needed at runtime (e.g., [PI_WEB_API_URL])
requires.network No Network access requirements (e.g., [equinor-vpn])

The requires block is inspired by OpenClaw’s runtime metadata. It lets agents check prerequisites before attempting patterns that need external access or packages. Agents should warn the user if a declared requirement is not met.

Creating Core Program Skills

Core skills are shipped with NeqSim and reference internal Java classes, method signatures, or package structure. They require PR review by maintainers.

Step 1: Scaffold the Skill

neqsim new-skill "neqsim-my-topic"
neqsim new-skill "neqsim-my-topic" --description "Short description of what it covers"

This creates .github/skills/neqsim-my-topic/SKILL.md with a structured template.

Step 2: Fill in the Template

Edit the generated SKILL.md. Focus on three critical sections:

  1. When to Use — be specific about trigger conditions
  2. Code Patterns — every pattern must work against NeqSim’s actual API
  3. Common Mistakes — catalogue real failures you’ve encountered

Step 3: Verify Code Patterns

Every code example must be tested:

# For Java patterns — create a JUnit test
./mvnw test -Dtest=MySkillPatternsTest

# For Python patterns — run in a notebook
from neqsim import jneqsim
# ... test each pattern ...

# Verify method names exist in the source
# Use grep_search or file_search to confirm

Step 4: Register the Skill

Two registrations are required:

1. Add to the skills README (.github/skills/README.md):

Add a row to the Skill Index table:

| `neqsim-my-topic` | Description of what the skill covers | agent1, agent2 |

2. Add to copilot-instructions.md (.github/copilot-instructions.md):

Add a <skill> entry under the <skills> section:

<skill>
<name>neqsim-my-topic</name>
<description>Description. USE WHEN: trigger conditions.</description>
<file>.github/skills/neqsim-my-topic/SKILL.md</file>
</skill>

Step 5: Submit a PR

One skill per PR. Include the skill file, the two registrations, and any supporting test files.

What Makes a Good Core Skill

A core skill should be:

Creating Community Skills

Community skills are contributed by domain experts and hosted outside the core NeqSim source tree. They are listed in the community-skills.yaml catalog for discoverability and can be installed by any user. The recommended shared public collection is equinor/neqsim-community-skills, which is intended for reusable, public, non-confidential skills.

When to Create a Community Skill (vs. Core)

Create a community skill when:

Do not put proprietary methods, plant data, private tag names, internal URLs, company standards, customer/project identifiers, or project-specific design bases in the public community repository. Put that material in a private skill catalog instead.

Step 1: Create the Skill in Your Repository

Create a GitHub repository for your skill (or add it to an existing repo). The skill needs a SKILL.md file following the standard format.

Single-skill repo (simplest):

neqsim-my-topic/
├── SKILL.md          # required — the skill content
├── CHANGELOG.md      # recommended — version history
└── README.md         # optional — repo landing page

Multi-skill repo (one repo, several skills):

your-repo/
└── skills/
    ├── neqsim-skill-a/
    │   └── SKILL.md
    └── neqsim-skill-b/
        └── SKILL.md

The path field in the catalog entry tells the installer where to find SKILL.md. For a single-skill repo it defaults to SKILL.md (the repo root). For a multi-skill repo, set it explicitly (e.g., path: "skills/neqsim-skill-a/SKILL.md").

For a public multi-skill GitHub repo, the NeqSim catalog can also list the repo once under repositories:. The CLI searches the online repository, first reading its remote community-skills.yaml and then falling back to scanning for matching SKILL.md files:

repositories:
  - repo: "equinor/neqsim-community-skills"
    catalog_path: "community-skills.yaml"
    skill_path_glob: "skills/**/SKILL.md"

This keeps the NeqSim catalog small while allowing new skills in the external repo to appear in neqsim skill list after the external repo updates its own catalog.

The skill name must start with neqsim-. Use the anatomy template shown above, including the version and requires fields in the YAML frontmatter.

SKILL.md Requirements Checklist

Before publishing, verify your SKILL.md meets these requirements:

Requirement Details
File name Must be SKILL.md (exact case)
Skill name Must start with neqsim- (e.g., neqsim-teg-dehydration)
YAML frontmatter Must include name, version, description, last_verified
USE WHEN clause The description field must contain a USE WHEN: trigger so agents know when to load it
Version Semver format: "1.0.0"
When to Use section Bullet list of explicit trigger conditions
Code Patterns section At least one working code example (Java 8 compatible if Java)
Common Mistakes section Table with Symptom / Cause / Fix columns
Java 8 compatible No var, List.of(), String.repeat(), text blocks, etc. in Java code
Tested All code patterns verified against NeqSim’s actual API
No duplication Does not duplicate an existing core skill
requires block (if needed) Declare Python packages, env vars, or network access your patterns need

Tip: You can use the scaffolder to create the initial template locally, then copy it to your repo:

neqsim new-skill "neqsim-my-topic" --description "My skill description"
# Creates .github/skills/neqsim-my-topic/SKILL.md (local template)
# Copy the generated SKILL.md to your external repo

Step 2: Publish to the Community Catalog

There are two ways to add your skill to the catalog:

Option A: Automated (recommended) — Use neqsim skill publish:

neqsim skill publish your-username/your-repo
# The tool will:
#   1. Validate that SKILL.md exists in your repo on GitHub
#   2. Extract description and auto-detect tags from content
#   3. Generate the catalog entry and show it for confirmation
#   4. Append the entry to community-skills.yaml
#   5. Create a Git branch and draft PR via GitHub CLI (if `gh` is installed)

If GitHub CLI (gh) is not installed, the tool saves the catalog entry and prints manual PR instructions:

git checkout -b community-skill/neqsim-my-topic
git add community-skills.yaml
git commit -m "Add community skill: neqsim-my-topic"
git push -u origin community-skill/neqsim-my-topic
gh pr create --draft --title "Add community skill: neqsim-my-topic"

Option B: Manual — Edit community-skills.yaml directly and submit a PR:

skills:
  - name: neqsim-my-topic
    version: "1.0.0"
    description: "What it does and when to use it"
    author: "your-github-username"
    repo: "your-username/your-repo"
    path: "skills/neqsim-my-topic/SKILL.md"
    tags: [keyword1, keyword2]
    min_neqsim_version: "3.7.0"  # optional

Step 3: PR Review and Merge

A NeqSim maintainer will review the PR. They check:

Once merged, the skill appears in the catalog and anyone can install it.

Step 4: Users Install with the CLI

Once in the catalog, anyone can install your skill:

# Browse available community skills
neqsim skill list

# Search by keyword
neqsim skill search "dehydration"

# Install a skill (downloads to ~/.neqsim/skills/)
neqsim skill install neqsim-my-topic

# Install and export for VS Code user prompts discovery
neqsim skill install neqsim-my-topic --target vscode

# Install and export for tool-neutral discovery
neqsim skill install neqsim-my-topic --target generic

# Check that exported agents can see their required skills
neqsim agent doctor --target generic

# Check what's installed
neqsim skill installed

# Get details about a specific skill
neqsim skill info neqsim-my-topic

# Remove a skill
neqsim skill remove neqsim-my-topic

Installed community skills are stored at ~/.neqsim/skills/<name>/SKILL.md.

Step 5: Make Installed Skills Visible to Agents

Installed community skills at ~/.neqsim/skills/ are the local source of truth. Agent tools discover different folders, so use export targets to create generated copies for a specific tool:

# Export an already-installed skill to VS Code's user prompts skills folder
neqsim skill export neqsim-my-topic --target vscode

# Export an already-installed skill to ~/.neqsim/export/generic/skills/
neqsim skill export neqsim-my-topic --target generic

The generic export writes ~/.neqsim/export/generic/skills/<name>/SKILL.md plus ~/.neqsim/export/generic/manifest.json. The same manifest also records generic agent exports when both agents and skills are exported. Use this target for coding agents that can be configured with arbitrary local instruction folders. Use the VS Code target when you want Copilot/VS Code to discover the skill from the personal ~/.copilot/skills folder. Maintainers can choose workspace export explicitly with --vscode-scope workspace when a generated .github/skills copy is intentional.

Prefer the export commands over manual copying. If a tool cannot read the VS Code or generic export layouts, point that tool at the installed source folder ~/.neqsim/skills/<name>/ or copy from there into the tool-specific location it documents.

Installing Community and Private Agents

Skills and agents are intentionally separate concepts. A skill is a reusable capability or knowledge package. An agent is a role/workflow definition that may depend on several skills. NeqSim installs agents into ~/.neqsim/agents/ so they do not pollute the core repository, and installation never executes agent code.

Agent packages can use either of these shapes:

single-file-agent/
└── process.agent.md

folder-agent/
├── AGENT.md
├── agent.yaml
├── prompts/
├── workflows/
├── examples/
└── tests/

The folder package is preferred for larger workflows because agent.yaml can declare dependencies and compatibility metadata in a tool-neutral way. The current NeqSim agent manifest schema is 1.0:

agent_manifest_schema_version: "1.0"
name: tie-in-screening-agent
description: Early-stage tie-in screening using NeqSim and community skills
version: "0.1.0"
required_skills:
  - neqsim-flow-assurance
  - neqsim-standards-lookup
supported_domains:
  - flow-assurance
  - process
inputs:
  - feed_composition
  - operating_conditions
outputs:
  - results_json
  - report
requires_mcp_tools:
  - runProcess
human_review_required: true
trust_level: community  # core | community | private | experimental

Agent CLI Commands

# Browse available community and private agents
neqsim agent list

# Search by name, tag, description, or required skill
neqsim agent search "tie-in"

# Inspect catalog metadata
neqsim agent info neqsim-example-agent

# Install an agent definition to ~/.neqsim/agents/
neqsim agent install neqsim-example-agent

# Install and export to the personal ~/.copilot/agents folder
neqsim agent install neqsim-example-agent --target vscode

# Install and export to ~/.neqsim/export/generic/agents/
neqsim agent install neqsim-example-agent --target generic

# Agent install also installs and exports required skills when they exist in skill catalogs
neqsim agent doctor --target generic

# Export an already-installed agent later
neqsim agent export neqsim-example-agent --target generic

# Install every agent in the catalog at once
neqsim agent install --all

# Optionally install missing required skills that are present in skill catalogs
neqsim agent install neqsim-example-agent --install-missing-skills

# Validate an installed agent or local folder
neqsim agent validate neqsim-example-agent
neqsim agent validate ./agents/tie-in-screening-agent

# Show the supported agent.yaml schema
neqsim agent schema

# Remove an installed agent
neqsim agent remove neqsim-example-agent

The public catalog lives in community-agents.yaml. Private/internal agents use the same pattern as private skills:

neqsim agent private-init
# Edit ~/.neqsim/private-agents.yaml
neqsim agent list --private
neqsim agent install company-tie-in-screening-agent

Agent catalog entries support local folders, private GitHub repositories, network shares, and direct internal URLs. For private GitHub repositories, prefer browser SSO through gh auth login --web or Git Credential Manager; GITHUB_TOKEN remains a non-interactive fallback for CI or service contexts. Direct internal URLs can use PRIVATE_AGENT_TOKEN when the URL endpoint cannot use the normal corporate browser or git credential flow.

Making Installed Agents Visible to Tools

Installed agents are not automatically run by NeqSim. Point your AI tool at the installed folder, or export a generated copy to the tool-specific layout. For VS Code Copilot custom agents, the default NeqSim export target is the personal ~/.copilot/agents folder, not the Git-tracked workspace:

neqsim agent export neqsim-example-agent --target vscode
neqsim agent doctor --target vscode

For tool-neutral agents, use the generic target and point the tool at the generated manifest:

neqsim agent export neqsim-example-agent --target generic
neqsim agent doctor --target generic

This keeps the trust boundary explicit:

skill install = install reusable capability
agent install = install workflow/role definition
agent run = explicit action in the AI tool that owns execution

Complete Example: Contributing a TEG Dehydration Skill

Here is a complete walkthrough of contributing a community skill:

# 1. Create a repo on GitHub: your-username/neqsim-teg-dehydration
#    Add your SKILL.md with TEG-specific patterns

# 2. Publish to the NeqSim community catalog
neqsim skill publish your-username/neqsim-teg-dehydration

#    Output:
#    Validating your-username/neqsim-teg-dehydration / SKILL.md ...
#    [OK] Found SKILL.md (2847 bytes)
#
#    Generated catalog entry:
#      - name: neqsim-teg-dehydration
#        description: "TEG dehydration sizing and design per GPA 8100..."
#        author: "your-username"
#        repo: "your-username/neqsim-teg-dehydration"
#        path: "SKILL.md"
#        tags: [flow-assurance, process]
#
#    Add to catalog and create PR? [y/N] y
#    [OK] Added entry to community-skills.yaml
#    [OK] Draft PR created: https://github.com/equinor/neqsim/pull/1234

# 3. Wait for maintainer review and merge

# 4. Other users install it:
neqsim skill install neqsim-teg-dehydration

# 5. Export for your AI tool:
neqsim skill export neqsim-teg-dehydration --target vscode
neqsim skill export neqsim-teg-dehydration --target generic

Updating a Published Community Skill

When you update your skill in your repo (e.g., bump version to 1.1.0):

  1. Update the SKILL.md in your repository (add patterns, fix mistakes, bump version)
  2. Users re-install with --force to get the latest: 
    neqsim skill install neqsim-my-topic --force

Creating Local Private Skills

Local skills encode knowledge that is specific to your organisation and should never be committed to a public repository. This is the most important skill type for production engineering workflows because it connects the generic NeqSim capabilities to your specific plant, your specific data systems, and your specific corporate standards.

Important: local skills are not auto-discovered by every tool. Install shared local, community, and private skills into ~/.neqsim/skills/, then export generated copies with neqsim skill export <name> --target vscode or neqsim skill export <name> --target generic for the tool you want to use. VS Code user prompt files remain useful for one-off personal prompts, but they are no longer the preferred NeqSim skill install location.

How Local Skills Become Visible to Agents

There are several ways to make local skills available. They are listed from most recommended to least:

Method Auto-loads Works across workspaces Setup effort
NeqSim install + export targets (recommended) Yes, when the target tool reads the export Yes for generic and default VS Code user exports; workspace-scoped only with explicit --vscode-scope workspace Low
VS Code User Prompt Files Yes, when referenced with # Yes Low
Workspace .github/copilot-instructions.md Yes, always in context No, per-workspace only Medium
Manual prompt reference No, must ask each time Yes None

Use this method for reusable skills that should behave like installed community or enterprise skills. The canonical copy stays under ~/.neqsim/skills; exports are generated compatibility copies.

# Install from a public, private, local, GitHub, git, or URL catalog entry
neqsim skill install neqsim-company-stid

# Make the installed skill visible to VS Code from the user prompts skills folder
neqsim skill export neqsim-company-stid --target vscode

# Make it visible to tool-neutral coding agents
neqsim skill export neqsim-company-stid --target generic

For agents, the equivalent commands install into ~/.neqsim/agents and export to VS Code user prompts or the generic agent layout:

neqsim agent install company-study-review-agent --install-missing-skills
neqsim agent export company-study-review-agent --target vscode
neqsim agent export company-study-review-agent --target generic
neqsim agent doctor --target generic

The generic target writes ~/.neqsim/export/generic/manifest.json, which records exported agents and skills for coding agents that can consume arbitrary local instruction folders.

Method 2: VS Code User Prompt Files

VS Code Copilot has a user-level prompts folder that works across all workspaces. Any .md file placed there becomes a reusable prompt that you can invoke by name in Copilot Chat. This is useful for personal, VS Code-only prompts because:

Step 1: Create the user prompts folder

The folder location depends on your OS:

OS Path
Windows %APPDATA%\Code\User\prompts\
macOS ~/Library/Application Support/Code/User/prompts/
Linux ~/.config/Code/User/prompts/

On Windows, the full path is typically:

C:\Users\<YourName>\AppData\Roaming\Code\User\prompts\

Create it if it doesn’t exist:

# Windows PowerShell
New-Item -ItemType Directory -Path "$env:APPDATA\Code\User\prompts" -Force

# macOS / Linux
mkdir -p ~/.config/Code/User/prompts  # Linux
mkdir -p ~/Library/Application\ Support/Code/User/prompts  # macOS

Step 2: Enable prompt files in VS Code settings

Open VS Code settings (Ctrl+, or Cmd+,) and ensure this setting is enabled:

{
  "chat.promptFiles": true
}

Or search for “prompt files” in the Settings UI and check the box.

Step 3: Create your skill as a prompt file

Write a .md file in the prompts folder. Use the same SKILL.md format:

# Windows — create a local STID skill
New-Item -ItemType File -Path "$env:APPDATA\Code\User\prompts\neqsim-equinor-stid.md"

Then edit the file with your skill content (see the full examples below).

Step 4: Use the skill in Copilot Chat

In any VS Code workspace, type # in Copilot Chat to see available prompt files, then select your skill:

#neqsim-equinor-stid

Download compressor curves for 35-KA001A on Grane platform

Copilot reads the full file content and uses it as context for the task. The agent gets all your patterns, tag conventions, and common mistakes — just like a core skill.

You can also reference multiple skills in one prompt:

#neqsim-equinor-stid #neqsim-equinor-plant-data

Compare the rated compressor capacity from STID datasheets
against actual PI historian data for the last 30 days

Example: User prompts folder structure

C:\Users\ESOL\AppData\Roaming\Code\User\prompts\
├── neqsim-equinor-stid.md          # STID document retrieval
├── neqsim-equinor-plant-data.md    # PI historian access
├── neqsim-equinor-standards.md     # Company TR requirements
└── neqsim-my-platform-tags.md      # Tag mappings for a specific platform

Method 3: Workspace-Level copilot-instructions.md

If you want a local skill to be loaded automatically for every conversation in a specific workspace (without needing to type #), add it to the workspace’s .github/copilot-instructions.md. This is useful for project-specific skills that every team member needs.

Warning: .github/copilot-instructions.md is typically committed to Git. If you add private skill references here, either add the skill file path to .gitignore or use a separate non-committed instructions file.

Add a <skill> entry pointing to your local file:

<skill>
<name>neqsim-my-local-skill</name>
<description>My local skill for company-specific workflows. USE WHEN: task involves our plant data.</description>
<file>C:\Users\ESOL\.neqsim\skills\neqsim-my-local-skill\SKILL.md</file>
</skill>

The agent will see this skill in its available skills list and load it when the description matches the task.

Method 4: Manual Prompt Reference

The simplest (but least convenient) approach — just tell the agent to read your skill file in the chat:

Read the file at C:\Users\ESOL\.neqsim\skills\neqsim-equinor-stid\SKILL.md
and use it to download compressor curves for 35-KA001A

This works but requires you to remember and type the path every time.

Where to Store Skill Files

You can store the actual skill files anywhere on your machine. Two common locations:

Option A: ~/.neqsim/skills/ — co-located with community skills installed via neqsim skill install:

~/.neqsim/skills/
├── installed.json                    # manifest of installed community skills
├── neqsim-my-stid-retrieval/
│   └── SKILL.md                     # your private STID skill
├── neqsim-my-plant-data/
│   └── SKILL.md                     # your private plant data skill
└── neqsim-my-company-standards/
    └── SKILL.md                     # your company's engineering standards

Option B: VS Code user prompts folder — useful for ad hoc personal prompts that you invoke manually with #:

%APPDATA%\Code\User\prompts\
├── neqsim-equinor-stid.md           # skill = prompt file (no subfolder needed)
├── neqsim-equinor-plant-data.md
└── neqsim-equinor-standards.md

Option B is simple because the files are both the skill content and the prompt reference, but it is VS Code-specific. Prefer Option A plus export targets for reusable NeqSim skills and agents that should work across tools.

Private Skill Catalog

For teams that need to share private skills across an organisation — without publishing them to the public community catalog — the CLI supports a private skill catalog stored at ~/.neqsim/private-skills.yaml.

This works exactly like community-skills.yaml but:

Setup

The quickest path registers a private repository and signs in with browser SSO in one command — no hand-editing of YAML required:

# One step: create the catalog, register a private GitHub repo, and sign in
neqsim skill private-init --repo my-org/neqsim-enterprise-skills --login

# Internal Git server instead of GitHub:
neqsim skill private-init --url https://git.internal.company.com/neqsim/enterprise-skills.git

# Add more private repos later (same options; creates the catalog if missing):
neqsim skill add-repo --repo my-org/another-skills-repo --login

private-init prints the exact catalog file location at the end so you can edit it afterwards. Use private-init for first-time setup and add-repo to register additional repos later — they accept the same options. Then:

neqsim skill list --private                 # verify discovered skills
neqsim skill install <name> --target vscode # install + export for VS Code

Options for private-init and add-repo (both neqsim skill and neqsim agent):

Option Meaning Default
--repo OWNER/REPO Register a private GitHub repo —
--url GIT_URL Register an internal Git repo —
--source github\|git\|local Repository source github with --repo, git with --url
--auth github-cli\|git-credential-manager Auth broker matches source
--branch NAME Branch to read main
--catalog-path PATH Catalog file in the repo, or empty to scan "" (scan)
--skill-path-glob / --agent-path-glob Discovery glob skills/**/SKILL.md / agent globs
--name-prefix PREFIX Prefix to avoid public/private name clashes —
--login Launch browser SSO (gh auth login --web) after registering off

Which YAML file, and where? private-init writes to ~/.neqsim/private-skills.yaml (skills) and ~/.neqsim/private-agents.yaml (agents) — on Windows that is %USERPROFILE%\.neqsim\. These files are per-user and must never be committed to a public repo. The command prints the full path when it finishes; open that file to add or adjust entries by hand.

Manual alternative (edit the YAML yourself):

# 1. Create the catalog template
neqsim skill private-init

# 2. Edit ~/.neqsim/private-skills.yaml — uncomment and fill in entries
# 3. Verify
neqsim skill list --private

# 4. Install a private skill (same command as community skills)
neqsim skill install neqsim-company-stid

The identical flow exists for agents — swap skill for agent:

neqsim agent private-init --repo my-org/neqsim-enterprise-agents --login
neqsim agent list --private
neqsim agent install <name> --vscode

Catalog Format

The private catalog supports four source types:

catalog_version: "1.0"
organisation: "equinor"

skills:
  # Local file or network share
  - name: neqsim-equinor-stid
    description: "STID document retrieval for Equinor installations"
    author: "process-engineering"
    source: local
    path: "C:/Users/me/.neqsim/skills/neqsim-equinor-stid/SKILL.md"
    tags: [stid, documents, internal]

  # Network share (UNC path)
  - name: neqsim-company-standards
    description: "Company TR requirements for equipment design"
    author: "engineering-team"
    source: local
    path: "//fileserver/shared/neqsim-skills/company-standards/SKILL.md"
    tags: [standards, tr, internal]

  # Private GitHub repo (prefer gh auth login --web or Git Credential Manager;
  # GITHUB_TOKEN is a CI/non-interactive fallback)
  - name: neqsim-plant-data-mapping
    description: "PI tag mappings for our platforms"
    author: "data-team"
    source: github
    repo: "equinor/neqsim-internal-skills"
    path: "skills/neqsim-plant-data-mapping/SKILL.md"
    tags: [pi, historian, plant-data]

  # Direct URL (Azure DevOps, internal Git, etc.)
  - name: neqsim-internal-workflow
    description: "Internal simulation workflow for project X"
    author: "project-team"
    source: url
    url: "https://dev.azure.com/org/project/_git/repo?path=/SKILL.md"
    tags: [workflow, internal]

Authentication for Private Sources

Source Auth mechanism How to set
local File system permissions No token needed
github (private repo) Preferred: browser SSO via GitHub CLI or Git Credential Manager. Fallback: GITHUB_TOKEN for CI/non-interactive runs gh auth login --web, or configure Git Credential Manager; fallback $env:GITHUB_TOKEN = "..."
git Git Credential Manager or another configured git SSO broker Run the normal enterprise git login once; NeqSim reuses git credentials
url Preferred: normal corporate browser/session or network access. Fallback: PRIVATE_SKILL_TOKEN/PRIVATE_AGENT_TOKEN Use the internal URL directly when accessible; fallback $env:PRIVATE_SKILL_TOKEN = "Bearer ..."

Distributing the Catalog to Your Team

The catalog file itself can be shared via:

  1. Network share — put private-skills.yaml on a shared drive and have each team member copy it to ~/.neqsim/
  2. Internal Git repo — store the catalog in a private repo and clone/sync periodically
  3. Onboarding script — include in your team’s setup script:
# Example onboarding snippet
Copy-Item "\\fileserver\neqsim-config\private-skills.yaml" `
          "$env:USERPROFILE\.neqsim\private-skills.yaml"
neqsim skill list --private

How It Relates to the Three Skill Types

┌─────────────────────────────────────────────────────────┐
│  Core Skills (.github/skills/)                          │
│  └─ Auto-loaded by agents, version-controlled           │
├─────────────────────────────────────────────────────────┤
│  Community Catalog (community-skills.yaml)              │
│  └─ Public, anyone can contribute via PR                │
├─────────────────────────────────────────────────────────┤
│  Private Catalog (~/.neqsim/private-skills.yaml)   NEW  │
│  └─ Company-internal, shared via network/private repo   │
├─────────────────────────────────────────────────────────┤
│  Local Skills (VS Code user prompts / manual files)     │
│  └─ Personal, only on your machine                      │
└─────────────────────────────────────────────────────────┘

All installed skills (community and private) go to ~/.neqsim/skills/<name>/SKILL.md and are used the same way.

Example: Local Skill for STID Document Retrieval

This example shows a local private skill for retrieving engineering documents from Equinor’s STID system. This skill is private because it contains company-specific server URLs, authentication patterns, and tag naming conventions.

~/.neqsim/skills/neqsim-equinor-stid/SKILL.md

---
name: neqsim-equinor-stid
version: "1.0.0"
description: "Retrieves engineering documents from Equinor's STID system for
  use in NeqSim tasks. USE WHEN: a task requires vendor datasheets, compressor
  curves, mechanical drawings, or P&IDs for Equinor-operated installations."
last_verified: "2026-04-19"
requires:
  python_packages: [pymupdf]
  network: [equinor-vpn]
  env: [STID_BASE_URL]
---

# Equinor STID Document Retrieval

Retrieve engineering documents (compressor curves, mechanical drawings, data
sheets) from Equinor's STID (Statoil Technical Information and Documentation)
system for use in NeqSim engineering tasks.

## When to Use This Skill

- When a task references specific equipment tags (e.g., 35-KA001A)
- When vendor performance data is needed (compressor maps, pump curves)
- When mechanical drawings are needed for design verification
- When P&IDs are needed for process topology analysis

## Prerequisites

- VPN access to Equinor's internal network
- `devtools/doc_retrieval_config.yaml` configured (gitignored):

```yaml
backend: stidapi
stidapi:
  base_url: "https://stid.equinor.com/api/v2"
  auth: kerberos
  timeout: 60
  default_installation: "MYINST"

Retrieval Patterns

Download by Equipment Tag

# Download documents for specific equipment tags
python devtools/stid_download.py \
    --task-dir task_solve/2026-04-19_my_task \
    --inst GRANE --tags 35-KA001A 35-KA001B

# Download + convert to PNG for AI image analysis
python devtools/stid_download.py \
    --task-dir task_solve/2026-04-19_my_task \
    --inst GRANE --tags 35-KA001A --convert-png

Download by Document Number

python devtools/stid_download.py \
    --task-dir task_solve/2026-04-19_my_task \
    --inst GRANE --docs E001-AS-P-XB-00001-01

Programmatic Retrieval

from devtools.doc_retriever import retrieve_documents

docs = retrieve_documents(
    tags=['35-KA001A'],
    doc_types=['CE', 'DS', 'AA', 'MD'],
    output_dir='step1_scope_and_research/references/'
)

Document Type Codes

Code Type When Relevant
CE Performance Curves Compressor, pump, turbine analysis
DS Data Sheet Any equipment analysis
AA General Arrangement Physical layout, sizing
MD Mechanical Drawing Detailed dimensions, nozzles
PI P&ID Process topology
IN Instrument Data Sheet Control system design

Tag Naming Convention (Equinor)

Equipment tags follow the pattern: XX-YYNNNZ

Common Mistakes

| Symptom | Cause | Fix | |———|——-|—–| | No documents returned | Wrong installation code | Check --inst matches the platform (GRANE, TROLL, etc.) | | Timeout errors | VPN not connected | Connect to Equinor VPN first | | Documents saved outside task | Wrong output path | Always use --task-dir flag | | Irrelevant documents cluttering analysis | No type filtering | Use --doc-types CE,DS to filter |


---

## Example: Local Skill for Plant Data from PI Historian

This example shows a local private skill for reading real-time and historical data from Equinor's OSIsoft PI historian. This is private because it contains server names, tag naming conventions, and authentication details.

### `~/.neqsim/skills/neqsim-equinor-plant-data/SKILL.md`

```markdown
---
name: neqsim-equinor-plant-data
version: "1.0.0"
description: "Reads plant process data from Equinor's PI historian for
  use in NeqSim digital twin and model validation tasks. USE WHEN: a task
  needs real operating data — temperatures, pressures, flow rates,
  compositions — from an Equinor-operated facility."
last_verified: "2026-04-19"
requires:
  python_packages: [tagreader, pandas]
  network: [equinor-vpn]
---

# Equinor Plant Data via PI Historian

Read process data from Equinor's OSIsoft PI historian using tagreader-python.

## When to Use This Skill

- When validating a NeqSim model against real plant data
- When building a digital twin loop
- When extracting operating conditions for design basis
- When comparing simulated vs measured values

## Prerequisites

- On Equinor network (or VPN)
- `pip install tagreader`
- Kerberos authentication (default on Equinor machines)

## Connection Pattern

```python
import tagreader

# List available PI sources
sources = tagreader.list_sources("piwebapi")
print(sources)  # e.g., ['PINO', 'PIMNT', 'PIK', ...]

# Connect to a specific PI server
c = tagreader.IMSClient("PINO", "piwebapi")
c.connect()

Tag Mapping Pattern

Map NeqSim simulation variables to PI historian tags:

TAG_MAP = {
    # NeqSim variable name  :  PI tag name
    "hp_sep.pressure"       : "35-PT-0101.PV",
    "hp_sep.temperature"    : "35-TT-0101.PV",
    "hp_sep.gas_flow"       : "35-FT-0101.PV",
    "hp_sep.oil_level"      : "35-LT-0101.PV",
    "compressor.suction_p"  : "35-PT-0201.PV",
    "compressor.discharge_p": "35-PT-0202.PV",
    "compressor.speed"      : "35-ST-0201.PV",
    "export.gas_flow"       : "36-FI-0001.PV",
}

Reading Data

tags = list(TAG_MAP.values())
start = "01.06.2025 06:00:00"
end   = "01.06.2025 18:00:00"

# Interpolated data every 5 minutes
df = c.read(tags, start, end, 300)

# MANDATORY: Save to CSV in the task folder
import pathlib
REFS_DIR = TASK_DIR / "step1_scope_and_research" / "references"
REFS_DIR.mkdir(parents=True, exist_ok=True)
df.to_csv(str(REFS_DIR / "plant_data_raw.csv"))

Digital Twin Comparison Pattern

import pandas as pd

# Run NeqSim simulation
process.run()

# Compare with plant data
sim_results = {
    "hp_sep.pressure": sep.getPressure("bara"),
    "hp_sep.temperature": sep.getTemperature("C"),
    "compressor.discharge_p": comp.getOutletPressure("bara"),
}

comparison = []
for var_name, sim_value in sim_results.items():
    tag = TAG_MAP[var_name]
    plant_value = df[tag].mean()
    deviation_pct = abs(sim_value - plant_value) / plant_value * 100
    comparison.append({
        "variable": var_name,
        "simulated": round(sim_value, 2),
        "measured": round(plant_value, 2),
        "deviation_%": round(deviation_pct, 1),
    })

df_comp = pd.DataFrame(comparison)
print(df_comp.to_string(index=False))

Common Mistakes

| Symptom | Cause | Fix | |———|——-|—–| | ConnectionError | Not on Equinor network | Connect VPN or use read_type=SNAPSHOT for quick test | | NaN values in DataFrame | Tag doesn’t exist or no data in range | Verify tag with c.search("TAG*") | | Timezone mismatch | PI returns UTC, analysis assumes Oslo | Set tz="Europe/Oslo" in client constructor | | Stale data in CSV | Forgot to re-read after time range change | Delete old CSV, re-run read | | Plant data not in task folder | Saved to workspace root | Always save to REFS_DIR inside the task |


---

## Skill Lifecycle and Maintenance

### When to Update a Skill

Update a skill when:

- NeqSim's API changes (new methods, renamed classes, changed signatures)
- New failure modes are discovered
- Better patterns are found through operational experience
- Industry standards are updated

### Version Tracking

Skills use [semver](https://semver.org/) versioning plus a verification date:

```yaml
---
name: neqsim-my-skill
version: "1.2.0"
last_verified: "2026-04-19"
---
Version bump When
Major (2.0.0) Breaking changes: removed patterns, changed prerequisites, incompatible with previous NeqSim versions
Minor (1.3.0) New patterns, new sections, expanded coverage
Patch (1.2.1) Fix typos, correct code errors, update verification date

Update version for every change and last_verified whenever you re-verify patterns against NeqSim’s API.

The neqsim new-skill scaffolder also creates a CHANGELOG.md alongside SKILL.md to track version history:

# neqsim-my-skill Changelog

## 1.2.0 (2026-04-19)

- Added Python pattern for batch processing
- New common mistake: missing initProperties() after PSflash

## 1.1.0 (2026-03-15)

- Added valve sizing pattern per IEC 60534

## 1.0.0 (2026-02-01)

- Initial release

From Local to Community to Core

Skills can be promoted through the tiers:

  1. Start local — Write a private skill for your workflow
  2. Share as community — Once proven, publish to your repo and add to community-skills.yaml
  3. Promote to core — If the skill references NeqSim internals and is used by multiple agents, propose merging into .github/skills/

Summary

Aspect Core Skills Community Skills Private Skills Community/Private Agents
Location .github/skills/ External repos ~/.neqsim/private-skills.yaml, ~/.neqsim/skills/ External repos or ~/.neqsim/private-agents.yaml, installed to ~/.neqsim/agents/
Visibility All users Catalog browsers You or your team Catalog browsers, you, or your team
Creation neqsim new-skill + PR Your repo + catalog entry YAML entry or local file Agent markdown/folder + community-agents.yaml or private catalog
Installation Automatic (in repo) neqsim skill install to ~/.neqsim/skills neqsim skill install to ~/.neqsim/skills neqsim agent install to ~/.neqsim/agents
Tool export Already workspace-visible; some folders may be generated compatibility exports neqsim skill export <name> --target vscode/generic neqsim skill export <name> --target vscode/generic neqsim agent export <name> --target vscode/generic
Source types Git repo Public GitHub Local / network / private GitHub / URL Local / network / GitHub / URL
Contains private data Never Never Yes (company-internal) Yes only in private catalogs
Review process PR review by maintainers Self-published Team-managed PR review for public catalog; team-managed for private
Examples neqsim-api-patterns Custom TEG sizing Company STID, PI tags, TR standards Tie-in screening agent, internal review agent

The skill and agent system makes it possible for any engineer to package domain expertise and repeatable workflows — from thermodynamic model selection rules to company-specific review processes — in a format AI tools can use safely. Public knowledge is shared broadly while private knowledge stays private.

Comparison with OpenClaw

NeqSim’s skill system was partly inspired by OpenClaw (360k+ GitHub stars), the largest open-source AI assistant. OpenClaw has a mature skill ecosystem with ClawHub — a public registry hosting 18,000+ community-published skills with vector search, versioning, and security analysis.

Both systems share the same core idea: install structured, versioned knowledge or workflow packages into layered locations. For NeqSim, SKILL.md packages knowledge and AGENT.md or .agent.md packages workflow definitions. The key differences and lessons learned are:

What NeqSim adopted from OpenClaw

Feature OpenClaw NeqSim adoption
Semver versioning version: "1.2.0" in frontmatter Added to all skills — major/minor/patch with CHANGELOG.md
Dependency declarations metadata.openclaw.requires (env, bins, config) Added requires block: python_packages, java_packages, env, network
CLI workflow clawhub install/publish/search/sync neqsim skill (install/list/search/remove/publish)
Agent packages Role/workflow definitions can depend on skills neqsim agent (install/list/search/remove/validate) with required_skills checks

Where the systems differ

Aspect OpenClaw NeqSim
Scale 18,000+ skills (open marketplace) ~30 curated core + community catalog
Content Mostly API wrappers (Todoist, Slack, Gmail, etc.) Deep engineering domain knowledge
Quality Unfiltered, variable quality Expert-verified, PR-reviewed core skills
Search Vector search (OpenAI embeddings) Keyword search in YAML catalog
Security Automated analysis of declared vs actual behavior Manual PR review by maintainers
Agent integration Skills exported into a tool-visible layout and described by a manifest Core skills are workspace-visible; installed skills and agents live under ~/.neqsim/ and are exported to VS Code or generic folders for explicit tool use
Tiers Single public tier + local workspace Three tiers (core/community/local) with different trust levels
License MIT-0 (no attribution) Per-skill, follows NeqSim’s Apache 2.0 for core

What NeqSim does better

  1. Domain curation — 30 expert-verified skills beat 18,000 unfiltered ones for engineering reliability
  2. Three-tier architecture — Clear separation between core/community/local with different trust levels
  3. Trigger-based loading — USE WHEN clauses enable automatic skill selection based on task analysis, not manual installation
  4. Knowledge-first — Skills encode physics, standards, and engineering expertise rather than wrapping third-party APIs

Potential future improvements (inspired by OpenClaw)