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. If the skill ships a Python package (pyproject.toml), the installer downloads it whole and pip install -e’s it automatically — no separate manual install step. Reinstalls only re-run pip when the package’s pyproject.toml changed.
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

# Skip Python package installs during a bulk install, then install them later
neqsim skill install --all --target vscode --no-pip
neqsim skill sync-packages

# Install one skill's Python package on first use (no-op when already importable)
neqsim skill ensure neqsim-my-topic

# Report export health and which packaged skills are importable
neqsim skill doctor --target vscode

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

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

A skill that ships a Python package is installed editable, so re-running install --force only re-runs pip when that skill’s pyproject.toml (dependencies/metadata) changed — refreshing a large catalog does not reinstall every package. --no-pip defers the package installs entirely; run neqsim skill sync-packages (all pending, one pip pass) or `neqsim skill ensure

` (one skill, on first use) before using a skill that imports its own package. ### 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: ```bash # 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//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//` 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: ```text 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`: ```yaml 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 ```bash # 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: ```bash 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: ```bash 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: ```bash neqsim agent export neqsim-example-agent --target generic neqsim agent doctor --target generic ``` This keeps the trust boundary explicit: ```text 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: ```bash # 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: ```bash 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 --target vscode` or `neqsim skill export --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 | --- ### Method 1: NeqSim Install and Export Targets (Recommended) 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. ```powershell # 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: ```powershell 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: - Files survive across all workspaces and conversations - You invoke them by name with `#` — the agent reads the full file - They are never committed to any repository - They work with Copilot Chat, Copilot Edits, and agent mode #### 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\\AppData\Roaming\Code\User\prompts\ ``` Create it if it doesn't exist: ```powershell # Windows PowerShell New-Item -ItemType Directory -Path "$env:APPDATA\Code\User\prompts" -Force ``` ```bash # 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: ```json { "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: ```powershell # 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 `` entry pointing to your local file: ```xml neqsim-my-local-skill My local skill for company-specific workflows. USE WHEN: task involves our plant data. C:\Users\ESOL\.neqsim\skills\neqsim-my-local-skill\SKILL.md ``` 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: - Lives on each user's machine (never committed to public repos) - Supports **local file paths**, **network shares**, **private GitHub repos**, and **direct URLs** (internal Git, Azure DevOps) - Installed skills appear alongside community skills in the CLI ### Setup The quickest path registers a private repository **and** signs in with browser SSO in one command — no hand-editing of YAML required: ```bash # One step: create the catalog, register a private GitHub repo, and sign in # --catalog-path reads the catalog published in the repo instead of scanning it neqsim skill private-init --repo my-org/neqsim-enterprise-skills --catalog-path enterprise-skills.yaml --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: > If `neqsim` is not recognized (no elevated privileges, console script not on > PATH), run the same commands as `python -m neqsim_cli ...` — the arguments are > identical. ```bash neqsim skill list --private # verify discovered skills neqsim skill install --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): ```bash # 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`: ```bash neqsim agent private-init --repo my-org/neqsim-enterprise-agents --catalog-path enterprise-agents.yaml --login neqsim agent list --private neqsim agent install --vscode ``` ### Catalog Format The private catalog supports four source types: ```yaml 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: ```powershell # 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//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` ```markdown --- 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 ```bash # 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 ```bash 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 ```python 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` - `XX` = system number (e.g., 35 = gas compression) - `YY` = equipment type code (e.g., KA = compressor) - `NNN` = sequence number - `Z` = train identifier (A, B, C...) ## 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: ```python 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 ```python 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 ```python 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: ```markdown # 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 --target vscode/generic` | `neqsim skill export --target vscode/generic` | `neqsim agent export --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](https://github.com/openclaw/openclaw) (360k+ GitHub stars), the largest open-source AI assistant. OpenClaw has a mature skill ecosystem with [ClawHub](https://github.com/openclaw/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) - **Vector search** for the community catalog (find skills by meaning, not just keywords) - **Automated security analysis** of contributed skills (check that declared `requires` matches actual behavior) - ~~**`publish` command**~~ — already implemented via `neqsim skill publish` - **`sync` command** to auto-detect changed skills and publish updates - **Workflow composition** (OpenClaw has [lobster](https://github.com/openclaw/lobster) for chaining skills into pipelines) ## Related Documentation - [AI Agents Reference](/neqsim/integration/ai_agents_reference.html) — Complete catalog of all agents and skills - [AI Agentic Programming Introduction](/neqsim/integration/ai_agentic_programming_intro.html) — Overview of the agentic system - [AI Workflow Examples](/neqsim/integration/ai_workflow_examples.html) — End-to-end worked examples