Skills Reference

Skills are self-contained instruction files that teach an AI assistant how to do one job with XActions. Each is a markdown file with YAML frontmatter, written for a model to read rather than a human: it names the scripts to run, the page to run them on, the arguments that matter, and the mistakes to avoid.

They are how you get from "Claude has 152 tools" to "Claude knows which three of them to use, in what order, for this task."

• Location: skills/
• Machine-readable index: skills/index.json
• Template for new ones: skills/TEMPLATE.md
• Format: the Agent Skills specification, so any installer that follows it resolves this tree

Using them

Install into your agent

The CLI ships the whole catalogue and can copy any skill into the directory your coding agent already reads. Nothing is fetched: xactions skills resolves the skills/ directory relative to the installed package, so it works from a global npm install -g xactions as well as a clone.

xactions skills list                                   # every skill, and where each is installed
xactions skills show follower-monitoring               # print one SKILL.md in full
xactions skills install --all --global                 # Claude Code, for every project: ~/.claude/skills/<id>/
xactions skills install growth-automation              # Claude Code, this project only: ./.claude/skills/<id>/
xactions skills install --all --target cursor          # ./.cursor/rules/<id>.mdc
xactions skills install --all --target codex --global  # ~/.codex/skills/<id>/
xactions skills install --all --target windsurf        # ./.windsurf/rules/<id>.md
xactions skills uninstall --all --target cursor

Where each target puts things, and what it writes:

cursor, windsurf and project are per-project by definition, so --global is ignored for them and the command says so.

Every run is idempotent and reports what it did per skill: installed, updated (the copy on disk was stale), unchanged, removed, or absent. The rules-file targets carry a Source: line naming the package's skill directory, because a SKILL.md refers to its scripts by relative path and the agent needs to know where those resolve. --json on any sub-command prints the same report as JSON.

xactions doctor reports how many skills are installed per target, and xactions skills list marks each skill with where it was found.

Skills and MCP tool groups solve the same problem from two directions. A skill tells the model which tools to reach for; npx xactions-mcp --tools <groups> stops it from seeing the rest at all. Pairing a narrow skill with a narrow tool allowlist is the strongest setup: see MCP Setup.

Install with any spec-compliant installer

Every skill here follows the Agent Skills specification: a skills/<name>/ directory holding a SKILL.md whose frontmatter carries name and description. That is the layout third-party installers look for, so the cross-agent installer from vercel-labs resolves the catalogue straight from GitHub:

npx skills add nirholas/XActions            # pick from the list interactively
npx skills add nirholas/XActions --list     # see what is there, install nothing
npx skills add nirholas/XActions --all      # every skill, every detected agent

It walks skills/, reads each SKILL.md frontmatter, and links or copies the whole skill directory (references/ included) into whichever agent directories it finds on the machine. xactions skills install above is unaffected and still the right tool when XActions is already installed.

With Claude Code

Point Claude at the directory. It reads the frontmatter description of each skill to decide which one applies to your request:

claude "Read skills/follower-monitoring/SKILL.md and find who unfollowed me this week"

With any assistant

Skills are plain markdown. Paste the contents of a SKILL.md into any chat and the assistant has everything it needs for that job:

[paste skills/growth-automation/SKILL.md]

Now set this up for the "AI engineering" niche.

Programmatically

import { readFileSync } from 'node:fs';

const index = JSON.parse(readFileSync('skills/index.json', 'utf8'));
const skill = index.skills.find((s) => s.id === 'follower-monitoring');
const instructions = readFileSync(skill.path, 'utf8');

// Hand `instructions` to your model as a system or user message.

Anatomy of a skill

---
name: growth-automation
description: Automates X/Twitter growth via browser console scripts. Auto-likes
  tweets by keyword/user filters, auto-comments on target users... Use when
  automating Twitter growth, engagement, following, or audience building.
license: Apache-2.0
metadata:
  author: nichxbt
  version: "4.0"
---

# Growth Automation

Browser console scripts for X/Twitter. **Always paste `src/automation/core.js`
first** -- it provides shared config, selectors, utilities, and rate limiting.

## Script Selection

| Goal | File |
|------|------|
| Auto-like timeline tweets | `src/automation/autoLiker.js` |
| Follow users by keyword search | `src/automation/keywordFollow.js` |

The description is the load-bearing field. It is the only thing an assistant reads when deciding whether a skill is relevant, so it has to state both what the skill does and when to reach for it. A description that only says what it does will never get selected.

Frontmatter rules

name and description are required. The spec allows four more keys and nothing else: license, compatibility, metadata, and the experimental allowed-tools. An installer that finds an unknown key or a missing required one skips the skill entirely, which is worse than a bad description because nothing tells the user it happened.

One YAML trap worth naming, because it costs a skill its whole entry: an unquoted scalar cannot contain a colon followed by a space. description: Runs the server: fast is a parse error, not a long description. Rephrase, or quote the value.

The catalog

50 skills. Generated from skills/index.json.

Writing one

1. Copy skills/TEMPLATE.md to skills/your-skill/SKILL.md.

2. Write the frontmatter. Spend the effort on description: name the job and the trigger. Compare "Manages bookmarks" with "Organize, export, and bulk-clear bookmarks with auto-tagging. Use when someone asks to clean up, export, or categorize their saved posts."

3. Write the body for a model, not a person. Concrete file paths, exact page URLs, real argument values. Skip the motivation and the history.

4. Lead with a selection table mapping goals to files, so the assistant picks correctly before it reads any detail.

5. Add the entry to skills/index.json.

6. Check that an outside installer can still read the whole catalogue:

   npx skills add . --list        # from the repo root: should list every skill
   xactions skills list           # our own installer, same count
   

   A skill with broken frontmatter is not reported as broken by either tool. It is silently absent from the list, so compare the count against the number of directories under skills/.

Rules that keep a skill useful:

• Reference real files. Every path in a skill must exist. A skill that sends an agent to a missing script is worse than no skill.
• State the preconditions. "Paste core.js first", "must be on x.com/USERNAME/followers", "requires a logged-in session."
• Say what not to do. Rate limits, dry-run defaults, and destructive steps belong in the skill, because the agent will not infer them.
• No placeholders. No TODO, no invented arguments.

Related

• MCP Setup: the 153 tools skills drive
• Browser Scripts: what most skills reference
• Agents: the autonomous agent that consumes skills
• AGENTS.md: integration notes for AI coding assistants, and when to shell out to the CLI instead of loading the MCP server