Add a User-Facing Skill
End-to-end workflow for creating a skill in skills/ that teaches AI agents how to use a cx CLI command. This skill is often invoked from add-command Step 6, but can also be used standalone when documenting an existing command.
contributing/adding-a-skill.md has the full reference guide and a copy-pasteable template. Read it alongside this workflow.
Step 0: Understand the Domain
Before writing anything, answer these questions:
- What cx command are you documenting? Identify the command and all its subcommands (e.g.,
cx alerts list, cx alerts get, cx alerts create).
- What can the user do with it? List the key operations, flags, and output formats supported.
- Who is the audience? Skills are consumed by AI agents, not humans directly. Write instructions an agent can follow step-by-step to accomplish a user's goal.
- Is there dense reference material? Schemas, enum catalogs, field references, or language syntax exceeding ~100 lines belong in a separate
references/ file.
Step 1: Read Existing Skills
Before writing any skill, read existing ones to internalize the project's patterns. Agents that study existing skills first produce consistent, high-quality results rather than inventing new formats.
Always read:
contributing/adding-a-skill.md - full guide with directory structure, frontmatter conventions, reference file rules, and a copy-pasteable template
skills/README.md - the public catalog you'll update in Step 4
Study at least two existing skills:
| Skill |
Why study it |
skills/cx-alerts/SKILL.md |
REST-based command with rich examples, JSON payloads, investigation workflow; uses both shared and skill-local reference files |
skills/cx-telemetry-querying/SKILL.md |
Gateway skill that loads shared reference files per pillar — good model for cross-pillar routing and reference-loading patterns |
skills/cx-dashboards/SKILL.md |
Complex multi-step workflow; uses shared references (dataprime, promql, logs, spans) plus skill-local references |
skills/cx-cost-optimization/SKILL.md |
Workflow skill covering 5 commands unified by "reduce costs" intent — good model for multi-command skills |
Pick the two closest to what you're building and read them completely.
Step 2: Create Directory and Write SKILL.md
Create skills/cx-<domain-name>/SKILL.md. All skill directories use the cx- prefix. Use the directory structure, frontmatter format, and templates from contributing/adding-a-skill.md § "Directory Structure" through "Complete Template" (single-command) or § "Workflow Skills" (multi-command).
Writing effective trigger descriptions
The description frontmatter field is the primary trigger mechanism - agents use it to decide when to activate a skill. This is the single most important line in the file. Write at least 10 trigger phrases covering:
- Explicit command names (
"list alerts", "get alert by ID")
- User intents (
"investigate alert failures", "debug noisy alerts")
- Synonyms and variations (
"check", "find", "search", "analyze")
- Domain jargon (
"SLO breach", "error budget")
Body structure
Follow this order (see contributing/adding-a-skill.md § "Complete Template" for a starting point):
- Title and intro - one sentence explaining what the skill covers and which
cx commands it uses
- CLI Commands table -
| Command | Purpose | Key flags | for every subcommand. Include -o json/-o toon and -p <profile> notes.
- Workflow / Investigation steps - numbered steps an agent should follow. Start with discovery, end with verification.
- Key Principles - 4-6 bullet points: use
-o json with jq, multi-profile behavior, always verify, etc.
- Additional Resources - links to
references/ files and related skills
Style guidelines
- Write for an AI agent - be explicit about what to run and in what order
- Use code blocks for every CLI invocation
- Include realistic examples with actual flag values, not placeholders
- Show
jq filtering examples when the command supports -o json
- Keep SKILL.md under ~200 lines; move dense material to
references/
Step 3: Add Reference Files and Update README
Follow contributing/adding-a-skill.md § "Reference Files" for when and how to create references/ files, and § "Updating skills/README.md" for adding the skill to the public catalog.
Shared vs. skill-local references
Before creating a new reference file, check whether the content is language-level or telemetry-pillar material:
- Language guides (DataPrime syntax, PromQL guidelines) →
skills/shared/
- Telemetry-pillar how-tos (logs querying, spans querying, metrics workflow, RUM) →
skills/shared/
- Skill-specific schemas or templates (alert JSON schemas, dashboard widget templates) →
skills/cx-your-domain/references/
If your skill needs a file from skills/shared/:
- Add your skill and file list to
scripts/sync-shared-references.sh
- Run
bash scripts/sync-shared-references.sh — it copies the file(s) into your references/
- Commit the sync script change and the generated
references/ copies together
If you're adding a new shared reference:
- Create it in
skills/shared/
- Register it in the sync script for all consuming skills
- Run the script to generate copies, then commit everything
Step 4: Verify
- Frontmatter -
name matches directory, description has 10+ trigger phrases, metadata.version is "0.1.0"
- Body completeness - has CLI Commands table, workflow steps, key principles, and additional resources (if references exist)
- Reference links - any
references/ paths in SKILL.md point to files that actually exist
- README updated -
skills/README.md has the new row
- No bloat - SKILL.md doesn't duplicate >100 lines of material that belongs in
references/
- Shared references synced - if the skill uses files from
skills/shared/, confirm bash scripts/sync-shared-references.sh was run and the generated references/ copies are committed
- Agent readability - would an AI agent know exactly what to do after reading this skill? If not, add missing steps or examples
For advanced trigger optimization, use the /skill-creator skill to run eval-driven description testing and iterate on your trigger phrases.
Use the PR checklist from contributing/adding-a-skill.md § "PR Checklist" in your PR description.
1---2name: add-skill3description: Use this skill when the user asks to "add a skill", "create a skill", "new skill", "write a skill for", "skill for cx <something>", "add a user-facing skill", "create a SKILL.md", "teach an agent how to use", "agent skill for", "document a command as a skill", "make a skill", "add skill to skills/", "create agent instructions for", "build a skill", or wants to create a new user-facing skill in the skills/ directory that teaches AI agents how to use a cx CLI command. Use this even when the user is following the add-command workflow and reaches the skill creation step.4metadata:5 source: https://skillmd.com/skills/coralogix/add-skill6 version: "0.1.0"7 internal: true8---910# Add a User-Facing Skill1112End-to-end workflow for creating a skill in `skills/` that teaches AI agents how to use a cx CLI command. This skill is often invoked from `add-command` Step 6, but can also be used standalone when documenting an existing command.1314`contributing/adding-a-skill.md` has the full reference guide and a copy-pasteable template. Read it alongside this workflow.1516## Step 0: Understand the Domain1718Before writing anything, answer these questions:19201. **What cx command are you documenting?** Identify the command and all its subcommands (e.g., `cx alerts list`, `cx alerts get`, `cx alerts create`).212. **What can the user do with it?** List the key operations, flags, and output formats supported.223. **Who is the audience?** Skills are consumed by AI agents, not humans directly. Write instructions an agent can follow step-by-step to accomplish a user's goal.234. **Is there dense reference material?** Schemas, enum catalogs, field references, or language syntax exceeding ~100 lines belong in a separate `references/` file.2425## Step 1: Read Existing Skills2627Before writing any skill, read existing ones to internalize the project's patterns. Agents that study existing skills first produce consistent, high-quality results rather than inventing new formats.2829**Always read:**30- `contributing/adding-a-skill.md` - full guide with directory structure, frontmatter conventions, reference file rules, and a copy-pasteable template31- `skills/README.md` - the public catalog you'll update in Step 43233**Study at least two existing skills:**3435| Skill | Why study it |36|-------|-------------|37| `skills/cx-alerts/SKILL.md` | REST-based command with rich examples, JSON payloads, investigation workflow; uses both shared and skill-local reference files |38| `skills/cx-telemetry-querying/SKILL.md` | Gateway skill that loads shared reference files per pillar — good model for cross-pillar routing and reference-loading patterns |39| `skills/cx-dashboards/SKILL.md` | Complex multi-step workflow; uses shared references (dataprime, promql, logs, spans) plus skill-local references |40| `skills/cx-cost-optimization/SKILL.md` | Workflow skill covering 5 commands unified by "reduce costs" intent — good model for multi-command skills |4142Pick the two closest to what you're building and read them completely.4344## Step 2: Create Directory and Write SKILL.md4546Create `skills/cx-<domain-name>/SKILL.md`. All skill directories use the `cx-` prefix. Use the directory structure, frontmatter format, and templates from `contributing/adding-a-skill.md` § "Directory Structure" through "Complete Template" (single-command) or § "Workflow Skills" (multi-command).4748### Writing effective trigger descriptions4950The `description` frontmatter field is the primary trigger mechanism - agents use it to decide when to activate a skill. This is the single most important line in the file. Write at least **10 trigger phrases** covering:51- Explicit command names (`"list alerts"`, `"get alert by ID"`)52- User intents (`"investigate alert failures"`, `"debug noisy alerts"`)53- Synonyms and variations (`"check"`, `"find"`, `"search"`, `"analyze"`)54- Domain jargon (`"SLO breach"`, `"error budget"`)5556### Body structure5758Follow this order (see `contributing/adding-a-skill.md` § "Complete Template" for a starting point):59601. **Title and intro** - one sentence explaining what the skill covers and which `cx` commands it uses612. **CLI Commands table** - `| Command | Purpose | Key flags |` for every subcommand. Include `-o json`/`-o toon` and `-p <profile>` notes.623. **Workflow / Investigation steps** - numbered steps an agent should follow. Start with discovery, end with verification.634. **Key Principles** - 4-6 bullet points: use `-o json` with `jq`, multi-profile behavior, always verify, etc.645. **Additional Resources** - links to `references/` files and related skills6566### Style guidelines6768- Write for an AI agent - be explicit about what to run and in what order69- Use code blocks for every CLI invocation70- Include realistic examples with actual flag values, not placeholders71- Show `jq` filtering examples when the command supports `-o json`72- Keep SKILL.md under ~200 lines; move dense material to `references/`7374## Step 3: Add Reference Files and Update README7576Follow `contributing/adding-a-skill.md` § "Reference Files" for when and how to create `references/` files, and § "Updating skills/README.md" for adding the skill to the public catalog.7778### Shared vs. skill-local references7980Before creating a new reference file, check whether the content is language-level or telemetry-pillar material:8182- **Language guides** (DataPrime syntax, PromQL guidelines) → `skills/shared/`83- **Telemetry-pillar how-tos** (logs querying, spans querying, metrics workflow, RUM) → `skills/shared/`84- **Skill-specific schemas or templates** (alert JSON schemas, dashboard widget templates) → `skills/cx-your-domain/references/`8586If your skill needs a file from `skills/shared/`:871. Add your skill and file list to `scripts/sync-shared-references.sh`882. Run `bash scripts/sync-shared-references.sh` — it copies the file(s) into your `references/`893. Commit the sync script change and the generated `references/` copies together9091If you're adding a new shared reference:921. Create it in `skills/shared/`932. Register it in the sync script for all consuming skills943. Run the script to generate copies, then commit everything9596## Step 4: Verify97981. **Frontmatter** - `name` matches directory, `description` has 10+ trigger phrases, `metadata.version` is `"0.1.0"`992. **Body completeness** - has CLI Commands table, workflow steps, key principles, and additional resources (if references exist)1003. **Reference links** - any `references/` paths in SKILL.md point to files that actually exist1014. **README updated** - `skills/README.md` has the new row1025. **No bloat** - SKILL.md doesn't duplicate >100 lines of material that belongs in `references/`1036. **Shared references synced** - if the skill uses files from `skills/shared/`, confirm `bash scripts/sync-shared-references.sh` was run and the generated `references/` copies are committed1047. **Agent readability** - would an AI agent know exactly what to do after reading this skill? If not, add missing steps or examples105106For advanced trigger optimization, use the `/skill-creator` skill to run eval-driven description testing and iterate on your trigger phrases.107108Use the PR checklist from `contributing/adding-a-skill.md` § "PR Checklist" in your PR description.