BoxLang Skills

AI agent skills for BoxLang, the AI-native software productivity platform for building, modernizing and running applications, with developers and AI agents working together.

This repository provides reusable AI skills for BoxLang development, compatible with any agent that supports the skills.sh open standard — including Claude Code, Cursor, Copilot, and more.

Skills inject BoxLang domain knowledge directly into your AI agent so it can write accurate, idiomatic BoxLang code for you.

You can find all our skills published to our online directory at https://skills.boxlang.io/.

---

What Are Skills?

Skills are Markdown files (SKILL.md) that give your AI agent expert-level context on a specific topic. They are discovered and loaded automatically by the agent when relevant — a query about async programming loads the async skill, a question about deployment loads the deployment skill, and so on.

Each skill in this repo contains:

• Language syntax and idioms with working code examples
• API references and BIF signatures
• Configuration patterns
• Best practices and gotchas

Skill identifiers now use the boxlang-dev-* naming convention for easier discovery in installed skill lists.

---

Quick Install

Requires Node.js — no installation needed, just npx:

# Install ALL BoxLang skills (all categories)
npx skills add ortus-boxlang/skills

That's it. Your AI agent now has BoxLang and CommandBox expertise.

Claude Plugin Install

Add this repository as a plugin marketplace, then install the plugin:

claude plugin marketplace add ortus-boxlang/skills
claude plugin install boxlang-agent-skills@boxlang-agent-skills

Inside a session, /plugin marketplace add ortus-boxlang/skills and /plugin install boxlang-agent-skills@boxlang-agent-skills do the same.

The plugin also connects the Ortus documentation MCP servers: BoxLang, BoxLang IDE, BoxLang AI, BoxLang ORM, TestBox, ColdBox, CommandBox, WireBox, CacheBox and LogBox.

Codex Plugin Install

The same marketplace works in Codex, with the same skills and documentation MCP servers:

codex plugin marketplace add ortus-boxlang/skills
codex plugin add boxlang-agent-skills@boxlang-agent-skills

bx-playwright Add-on (opt-in)

The bx-playwright plugin gives the agent a real browser through Playwright's MCP server, started by bxplaywright mcp --headless. It needs the bx-playwright module, so it is a separate install:

install-bx-module bx-playwright
bxplaywright install

# Claude Code
claude plugin install bx-playwright@boxlang-agent-skills

# Codex
codex plugin add bx-playwright@boxlang-agent-skills

In Claude Code it also adds two commands: /bx-playwright:doctor (check the installation and fix what is missing) and /bx-playwright:new-browser-spec (scaffold a TestBox @browser spec). The bx-playwright skills ship in boxlang-agent-skills.

Cursor Marketplace Install

This repository also ships a Cursor plugin manifest under .cursor-plugin/, covering the same skill set as the Claude plugin. Add it from Cursor's Marketplace (Settings → Marketplace → Add Marketplace, or your installed Cursor version's marketplace/plugin CLI) pointed at:

ortus-boxlang/skills

Grok Plugin Install

A Grok-compatible plugin manifest is published at .grok-plugin/plugin.json. Point your Grok agent's plugin/marketplace loader at this repository (ortus-boxlang/skills) to install it.

ColdBox CLI

# Install the ColdBox CLI if you haven't already
box install coldbox-cli

# Install AI integration into your app
# This reads your app, box.json and installs skills based on your stack and preferences
coldbox ai install

# Skills Management

# List installed skills
coldbox ai skills list
# Add a skill
coldbox ai skills add Ortus-Solutions/skills/vuejs-expert
# Remove a skill
coldbox ai skills remove vuejs-expert

All skills are installed at .agents/skills/ in your project.

---

Categories

boxlang-developer — Building Applications with BoxLang

For developers writing BoxLang applications: web apps, APIs, database access, async pipelines, caching, Java interop, module usage, and deployment.

npx skills add ortus-boxlang/skills/boxlang-developer

Skill	What It Covers
boxlang-dev-application-descriptor	Application.bx discovery, multi-app isolation, lifecycle callbacks, app-level this.* settings, and app-scoped this.schedulers/this.watchers wiring
boxlang-dev-boxlang-async-programming	BoxFuture, futureNew, asyncRun, asyncAll, asyncAny, asyncAllApply, executors (io-tasks/cpu-tasks/scheduled-tasks), schedulers, thread component, bx:lock
boxlang-dev-boxlang-file-watchers	Filesystem watcher lifecycle (watcherNew/watcherStart/watcherStop), listener strategies (closure/struct/class), event payload handling, debounce/throttle tuning, and watcher stats
boxlang-dev-boxlang-best-practices	Naming conventions, scoping, function structure, error handling, performance, and maintainability guidelines
boxlang-dev-boxlang-caching	Cache providers, named regions, cachePut/cacheGet, output caching, Redis, Couchbase, TTL policies, distributed locking
boxlang-dev-boxlang-cfml-migration	Key syntax and behavioral differences, module, converting file types, fixing common migration issues

boxlang-core-development — Extending the BoxLang Runtime

For developers building BoxLang modules, contributing to the core runtime, and creating custom built-in functions, interceptors, and components.

npx skills add ortus-boxlang/skills/boxlang-core-development

Skill	What It Covers
boxlang-dev-boxlang-async-tasks	BoxFuture, AsyncService, executor types, BaseScheduler, ScheduledTask fluent API, cron constraints, task lifecycle callbacks, registering schedulers via ModuleConfig.bx
boxlang-dev-boxlang-bif-development	@BoxBIF annotation, invoke() method, argument typing, @BoxMember for member functions, Java BIF classes, runtime service access
boxlang-dev-boxlang-component-development	Custom tags/components, onStartTag/onEndTag, body content, attribute declarations, registering component paths in modules
boxlang-dev-boxlang-interceptors	Observer/Intercepting Filter patterns, 3 interceptor pools, BoxLang/Java/lambda interceptors, registration, interception points, custom events
boxlang-dev-boxlang-logging	LoggingService, BoxLangLogger (trace/debug/info/warn/error), pre-configured loggers, named loggers, parameterized messages, boxlang.json logging config
boxlang-dev-boxlang-module-development	ModuleConfig.bx lifecycle (configure/onLoad/onUnload), settings, Gradle build, ForgeBox publishing

---

commandbox — CommandBox CLI, Package Manager & Embedded Server

For developers using CommandBox — the CFML/BoxLang CLI, package manager, and embedded Undertow server from Ortus Solutions.

npx skills add ortus-boxlang/skills/commandbox

Skill	What It Covers
boxlang-dev-commandbox-setup	Installation (macOS/Linux/Windows/Homebrew), upgrading, Java configuration, commandbox.properties, light vs thin binaries
boxlang-dev-commandbox-usage	CLI commands, named/positional parameters, flags, system settings (${VAR:default}), env vars, backtick expressions, piping, recipes, REPL, aliases, exit codes, watch
boxlang-dev-commandbox-package-management	box.json schema, ForgeBox / Git / HTTP / folder / S3 / Gist / Java endpoints, semver ranges, dependencies vs devDependencies, lock files, package scripts, artifacts cache, publishing
boxlang-dev-commandbox-embedded-server	Undertow server configuration via server.json, server profiles, JVM/heap settings, SSL/TLS, URL rewrites, server rules, multi-site support, basic auth, aliases, OS service, server scripts
boxlang-dev-commandbox-task-runners	Task CFC anatomy, lifecycle events, interactive jobs DSL, progress bars, ANSI print helpers, threading/async, file watching, running sub-commands, property files, ad-hoc JARs/modules
boxlang-dev-commandbox-developing	Custom commands, namespace conventions, parameter annotations, WireBox DI, module structure, ModuleConfig.cfc, interceptors, core interception points, injection DSL, sharing/publishing

---

boxlang-modules: Official BoxLang Modules

Topic skills for official modules (bx-ai, bx-orm, bx-playwright, bx-mail, bx-pdf and more). See boxlang-modules/README.md for the full list.

npx skills add ortus-boxlang/skills/boxlang-modules
npx skills add ortus-boxlang/skills/boxlang-modules/bx-playwright

---

Install Individual Skills

# Single skill from boxlang-developer
npx skills add ortus-boxlang/skills/boxlang-developer/language-fundamentals
npx skills add ortus-boxlang/skills/boxlang-developer/application-descriptor
npx skills add ortus-boxlang/skills/boxlang-developer/async-programming
npx skills add ortus-boxlang/skills/boxlang-developer/file-watchers
npx skills add ortus-boxlang/skills/boxlang-developer/scheduled-tasks
npx skills add ortus-boxlang/skills/boxlang-developer/web-development
npx skills add ortus-boxlang/skills/boxlang-developer/database-access
npx skills add ortus-boxlang/skills/boxlang-developer/caching
npx skills add ortus-boxlang/skills/boxlang-developer/java-integration
npx skills add ortus-boxlang/skills/boxlang-developer/modules-and-packages
npx skills add ortus-boxlang/skills/boxlang-developer/deployment
npx skills add ortus-boxlang/skills/boxlang-developer/classes-and-oop
npx skills add ortus-boxlang/skills/boxlang-developer/functional-programming

# Single skill from boxlang-core-development
npx skills add ortus-boxlang/skills/boxlang-core-development/module-development
npx skills add ortus-boxlang/skills/boxlang-core-development/bif-development
npx skills add ortus-boxlang/skills/boxlang-core-development/interceptors
npx skills add ortus-boxlang/skills/boxlang-core-development/component-development
npx skills add ortus-boxlang/skills/boxlang-core-development/runtime-architecture

# Single skill from commandbox
npx skills add ortus-boxlang/skills/commandbox/commandbox-setup
npx skills add ortus-boxlang/skills/commandbox/commandbox-usage
npx skills add ortus-boxlang/skills/commandbox/commandbox-package-management
npx skills add ortus-boxlang/skills/commandbox/commandbox-embedded-server
npx skills add ortus-boxlang/skills/commandbox/commandbox-task-runners
npx skills add ortus-boxlang/skills/commandbox/commandbox-developing
npx skills add ortus-boxlang/skills/commandbox/commandbox-config-settings
npx skills add ortus-boxlang/skills/commandbox/commandbox-deploying
npx skills add ortus-boxlang/skills/commandbox/commandbox-testing

---

Managing Skills

# List installed skills
npx skills list

# Update all skills to latest
npx skills update

# Remove a skill
npx skills remove boxlang-dev-boxlang-language-fundamentals

# Search for skills
npx skills find boxlang

---

Direct / Manual Installation

If you prefer not to use the npx skills CLI — or if you are adding skills to a tool that supports its own marketplace or custom knowledge files — you can download individual SKILL.md files directly from this repository and place them wherever your tool expects them.

Claude Projects (Support Files)

Claude Projects let you attach files as project knowledge that Claude reads at the start of every conversation. Add any SKILL.md from this repo as a support file to give Claude deep BoxLang expertise without any CLI tooling.

1. Open the Project in Claude.ai → Project Knowledge → Add content
2. Paste the raw content of the skill file you want, e.g.:
   • boxlang-developer/language-fundamentals/SKILL.md
   • boxlang-developer/web-development/SKILL.md
   • boxlang-core-development/module-development/SKILL.md
   • commandbox/commandbox-embedded-server/SKILL.md
   • commandbox/commandbox-package-management/SKILL.md

Raw file URLs follow this pattern:

https://raw.githubusercontent.com/ortus-boxlang/skills/main/<category>/<skill>/SKILL.md

Example:

https://raw.githubusercontent.com/ortus-boxlang/skills/main/boxlang-developer/language-fundamentals/SKILL.md

Claude Code (.claude/ directory)

Claude Code automatically picks up Markdown files placed in .claude/skills/ inside your project. Copy any SKILL.md directly:

To install this repo as a Claude Code plugin marketplace, use the /plugin command:

/plugin marketplace add ortus-boxlang/skills
/plugin install boxlang-agent-skills@boxlang-agent-skills

Or add a single skill file manually:

# Add a single skill manually
mkdir -p .claude/skills
curl -o .claude/skills/boxlang-dev-boxlang-language-fundamentals.md \
  https://raw.githubusercontent.com/ortus-boxlang/skills/main/boxlang-developer/language-fundamentals/SKILL.md

Or use the npx skills CLI which handles this automatically (see Quick Install above).

Other Marketplaces & Manual Placement

Tool	Where to place the skill file
Claude Code	.claude/skills/<name>.md (project) or ~/.claude/skills/<name>.md (global)
Cursor	.cursor/rules/<name>.mdc
GitHub Copilot	append to .github/copilot-instructions.md
OpenHands	.openhands/instructions.md
Codex	.codex/<name>.md
Windsurf	.windsurf/rules/<name>.md

---

Supported Agents

The npx skills CLI detects which agents you have installed and places skills in the right location automatically:

Agent	Skills Location
Claude Code	~/.claude/skills/ (personal) or .claude/skills/ (project)
Cursor	.cursor/rules/
GitHub Copilot	.github/copilot-instructions.md
OpenHands	.openhands/
Codex	.codex/
Windsurf	.windsurf/rules/

For manual placement and Claude Project support files, see Direct / Manual Installation above.

---

About BoxLang

BoxLang is the AI-native software productivity platform, built on a modern, dynamic JVM language (JRE 21+) designed for rapid application development. It features:

• Multi-runtime deployment — web servers, CLI scripts, AWS Lambda, Docker, WASM, Spring Boot, Android
• Complete Java interoperability — use any Java library directly, compile to Java bytecode
• Modern language features — lambdas, closures, destructuring, spread syntax, optional chaining, virtual threads
• CFML compatibility — migrate existing ColdFusion/Lucee applications via bx-compat-cfml
• Rich module ecosystem — PDF, Redis, CSV, spreadsheets, ORM, LDAP, mail, image processing, and more
• Open source — Apache 2.0 license, commercially supported by Ortus Solutions

---

Resources

Resource	Link
BoxLang Documentation	https://boxlang.ortusbooks.com/
BoxLang GitHub	https://github.com/ortus-boxlang/BoxLang
CommandBox Documentation	https://commandbox.ortusbooks.com/
CommandBox GitHub	https://github.com/Ortus-Solutions/commandbox
Module Template	https://github.com/ortus-boxlang/boxlang-module-template
ForgeBox (packages)	https://forgebox.io
Ortus Community	https://community.ortussolutions.com/
BoxLang Slack	https://boxlang.io/slack
skills.sh	https://skills.sh

---

Contributing

Contributions are welcome! To add or improve a skill:

1. Fork this repository
2. Create or edit the relevant SKILL.md file
3. Verify the frontmatter has a name and description
4. Submit a pull request

Plugins are released by bumping one version across every manifest (Claude, Cursor, Grok, Codex and the bx-playwright add-on). Run scripts/sync-version.sh <version>; CI fails when the manifests disagree (scripts/sync-version.sh --check).

Skills should contain accurate, working code examples verified against the BoxLang documentation.