Agent Skills

Repository: Nuelink/nuelink-agent Install: npx skills add Nuelink/nuelink-agent

The MCP server lets an assistant call Nuelink. Skills tell it how to call Nuelink well.

A skill is a short instruction file your agent reads when a task matches it. The Nuelink skills pack encodes the workflows we’d want any agent to follow: resolve IDs before mutating, preview with --dry-run, treat ambiguous publishing intent as a draft, and ask before anything goes live. Without them, an agent left alone with a publishing tool tends to guess. With them, it checks.

Who this is for

• You use Claude Code, Codex, or another agent runtime that reads skills.
• You want the agent to run Nuelink CLI commands without you approving each one blindly.
• You want a consistent, reviewable workflow across your team.

If you just want to publish from a chat, you want the MCP server instead. Skills are for agents that run commands.

Install

1. Install the skills pack

npx skills add Nuelink/nuelink-agent

The command is npx skills add

Not npm add skills. The installer discovers the three canonical skills only. Legacy aliases stay opt-in.

2. Install and authenticate the CLI

The skills drive the CLI, so the CLI has to be there:

npm install -g @nuelink/nuelink-cli
printf '%s' "$NUELINK_API_KEY" | nuelink-cli auth:login --stdin
nuelink-cli auth:status

In CI, prefer the NUELINK_API_KEY environment variable over a saved config file.

3. (Optional) Connect the MCP server separately

The repository includes an example .mcp.json for https://mcp.nuelink.com/mcp, but npx skills add installs skill directories only. Add the MCP server through your runtime’s separate MCP configuration flow; do not assume that installing the Skills configured MCP.

Tested install locations

Runtime	Repository scope	Typical user scope
Codex / agents-compatible runtimes	.agents/skills/	$HOME/.agents/skills/
Claude Code	.claude/skills/	$HOME/.claude/skills/

Other runtimes can use different paths. Follow that runtime’s current Skills documentation.

Skills are executable instructions

Only install skills from repositories you trust. A skill tells your agent what commands to run.

The three skills

The pack is deliberately small. Three skills, picked by what the task ends in.

nuelink-cli-setup

Install, authenticate, verify identity, and troubleshoot config.

Use it first, or any time you’re not sure which account is active.

npm install -g @nuelink/nuelink-cli
nuelink-cli --version
printf '%s' "$NUELINK_API_KEY" | nuelink-cli auth:login --stdin
nuelink-cli auth:status
nuelink-cli auth:validate
nuelink-cli me

Guardrails: never echo a full API key, stop before any mutation if me shows the wrong account, and re-authenticate with auth:clear if auth looks stale or auth:validate fails.

nuelink-cli-manage

Discover resources and safely create the non-post ones: collections and automations, plus listing brands, channels, and media.

nuelink-cli brands --per-page 25 --page 1
nuelink-cli collections --brand-id BRAND_ID --per-page 25 --page 1
nuelink-cli channels --brand-id BRAND_ID --per-page 25 --page 1
nuelink-cli automations --brand-id BRAND_ID
nuelink-cli media --brand-id BRAND_ID

Its mutation workflow, in order:

1. Resolve resource names and confirm exactly one target ID per resource.
2. Validate payload fields and required enums.
3. Run the create command with --dry-run and show the validated payload.
4. Get explicit user confirmation.
5. Run the same complete command without --dry-run, then report the created ID.

Step 5 matters: the agent repeats the same command, not an abbreviated one that could change the payload.

nuelink-cli-publish

Upload media, and list, draft, queue, schedule, publish, update, or delete posts, then review what was published. The skill that touches the outside world.

nuelink-cli media:upload --brand-id BRAND_ID --file ./assets/image.jpg --dry-run
nuelink-cli posts --brand-id BRAND_ID --collection-id COLLECTION_ID
nuelink-cli brand-posts --brand-id BRAND_ID --view SCHEDULED
nuelink-cli schedule --brand-id BRAND_ID
nuelink-cli posts:create \
  --brand-id BRAND_ID \
  --collection-id COLLECTION_ID \
  --caption "Post body" \
  --publish-mode DRAFT \
  --dry-run
nuelink-cli posts:update --brand-id BRAND_ID --post-id POST_ID --queue-position FRONT --dry-run
nuelink-cli published-posts --brand-id BRAND_ID --status FAILED

Its rules:

• Resolve and confirm exactly one BRAND_ID and one COLLECTION_ID.
• Preview every upload and every post mutation with --dry-run first.
• If publishing intent is ambiguous, use DRAFT.
• Require explicit confirmation for QUEUE, SCHEDULE, and IMMEDIATE.
• Check the current state with schedule and brand-posts before updating a queued or scheduled post, and confirm every posts:update against the exact brand and post ID.
• Treat posts:delete as irreversible: ask for a separate, explicit confirmation immediately before running it.

Safety defaults

Every skill in the pack shares the same posture:

Rule	Why
Resolve target IDs before any mutation	Stops posts landing in the wrong brand
Preview with --dry-run	Shows the intended JSON payload or upload metadata without contacting the API; server acceptance is not guaranteed
Default ambiguous intent to DRAFT	A misread instruction saves a draft, not a live post
Require explicit intent for QUEUE, SCHEDULE, IMMEDIATE	Publishing is never a side effect
Confirm posts:delete separately, right before it runs	Deletion is the one change that can’t be undone
One resource change at a time	Failures stay small and easy to reverse
Inject secrets from a secret manager	Avoids command arguments and saved CLI config; still prevent environment dumps and unnecessary child-process inheritance
Use explicit pagination in scripts	Deterministic results across runs

Repository integration metadata

The repository contains runtime-specific metadata:

Runtime or surface	Repository file
Claude Code plugin metadata	.claude-plugin/plugin.json
Codex metadata	.codex-plugin/plugin.json
Remote MCP example	.mcp.json

The documented npx skills add command installs the three canonical Skills as copied directories; it does not install these root files. A full marketplace/plugin installation can install the plugin package and bundled MCP configuration when the runtime supports it. Each canonical Skill’s references/ directory is copied with that Skill.

For an MCP-backed public OpenAI marketplace submission, add public HTTPS values for privacyPolicyURL, termsOfServiceURL, and supportURL to the Codex plugin interface. Repository CI should also run the official Claude plugin validator and a Codex marketplace install/MCP discovery smoke test, rather than only JSON-parsing the manifests.

Compatibility aliases

An earlier layout used nine narrower skills. Those still exist under compatibility-skills/ as an opt-in migration package, and each one routes to its canonical replacement:

Legacy skill	Now
nuelink-cli-install-auth, nuelink-cli-profile, nuelink-cli-ops	nuelink-cli-setup
nuelink-cli-brands, nuelink-cli-channels, nuelink-cli-collections, nuelink-cli-automations, nuelink-cli-media	nuelink-cli-manage
nuelink-cli-posts	nuelink-cli-publish

They aren’t part of the default bundle. Copy that directory only when migrating an installation that still references an old name.

Aliases aren’t self-contained

Each alias links its “Primary reference” to the canonical skill using a relative path like ../../skills/nuelink-cli-manage/references/manage-workflow.md. If you install an alias on its own, that link points outside the installed directory and won’t resolve. Install the canonical skill when you need something self-contained.

Recommended workflow

Skills are instruction files, not a policy engine or sandbox. The canonical Skills guide agents to resolve targets, preview mutations, default ambiguous publishing intent to DRAFT, and request confirmation for non-draft publishing. Users must still review commands and control the agent’s shell, file, credential, and network permissions.

Additional recommended checks—not guaranteed by every shipped Skill—are:

• Read a created resource back when a matching list operation can identify it reliably.
• Show a collection’s channels before non-draft post creation.
• Confirm the brand timezone and absolute timestamp before SCHEDULE, remembering that listed publish dates come back in UTC.
• For a first automation, pass --load-old-posts false and --add-posts-as-draft true explicitly. false is the API’s default for both, but spelling it out keeps the reviewed command self-describing.
• Prefer posts:update --publish-mode DRAFT over posts:delete when the goal is only to stop a post from going out.

A request that works well

Using the Nuelink CLI, verify the connected account, find the brand “Example Brand” and the collection “Product Launches”, show me that collection’s channels, then prepare a DRAFT post command with --dry-run. Don’t upload or create anything until I approve the exact command.

Every clause is doing work: it names the brand and collection, asks for the channels before anything is written, sets the publish mode explicitly, and withholds permission until the command is on screen.

Examples

Request and response examples live in examples/, grouped by domain, using placeholder tokens like SAMPLE_BRAND_ID. Replace them with your own IDs before running anything.

• Profile and brand list responses
• Channel, collection, automation, and media list responses
• Collection and automation create payloads, and the media upload response
• Post create and update payloads
• Post list, schedule, and published-results responses

Contributing

If you’re editing skills locally, validate before you open a PR:

npm run lint:md
npm run validate
npm run validate:behavior
npm run validate:all

What CI actually runs:

Check	Covers
npm ci --ignore-scripts	Clean dependency install
npm run validate	Skill structure and frontmatter
npm run validate:installer	Installer discovery for Codex and Claude Code
skills-ref validate	The Agent Skills reference implementation, run over every skill and alias
npm run validate:behavior	Behavior fixtures
npm run validate:contracts	JSON syntax, default-skill inventory, and seven network-blocked mutation dry-runs
markdownlint-cli2	Markdown lint

The contract check runs all seven API mutation dry-runs with the network blocked, including posts:update and posts:delete, so a dry-run path that quietly tries to reach the API fails the build. The plugin manifests parse as JSON, but CI does not yet run ecosystem-specific semantic validation for either manifest format.

Review skill changes before you update. A skill update changes how your agent behaves, not just what it reads.

The pack is MIT licensed. Issues and PRs welcome at github.com/Nuelink/nuelink-agent.