/ /

Skill best practices

Guidelines for structuring, writing, and organizing Computer skills.

Anatomy of a skill

A skill is a folder. The folder name is the skill's identifier; the folder contents are what Computer uses.

your-skill-name/
├── SKILL.md            # Required — main skill file (instructions)
├── scripts/            # Optional — executable helpers (Python, Bash, etc.)
│   ├── fetch_data.py
│   └── validate.sh
├── references/         # Optional — documentation Computer loads on demand
│   ├── api-guide.md
│   └── examples/
└── assets/             # Optional — templates, fonts, icons, sample files
    └── report-template.md

Only SKILL.md is required. Everything else is optional.

A few critical rules:

  • SKILL.md is case-sensitive. It must be exactly SKILL.md — not skill.md, SKILL.MD, or Skill.md.

  • The folder must be kebab-case. notion-project-setup ✅. Notion Project Setup ❌. notion_project_setup ❌. NotionProjectSetup ❌.

  • No README.md inside the skill folder. If you want a human-readable overview, put it in your SKILL.md or in references/. (When you publish the skill to GitHub or a repo, you can have a separate repo-level README for human visitors — just not inside the skill folder.)

Writing SKILL.md

SKILL.md is a markdown file with YAML frontmatter at the top. The frontmatter is the most important piece — it's what Computer reads first to decide whether your skill is relevant to the current question.

Minimal SKILL.md

---
name: your-skill-name
description: What it does. Use when user asks to [specific phrases].
---

# Your Skill Name

## Instructions

### Step 1: First major step
Clear explanation of what happens.

### Step 2: Second major step
…

That's all you need to ship a working skill.

Frontmatter fields

name (required)

  • Kebab-case only — no spaces, no capitals, no underscores.

  • Should match the folder name.

  • This is how the skill is identified internally.

description (required)

The single most important field. If the description is wrong, your skill won't load when it should — Computer uses this field alone to decide relevance, before it ever reads the rest of SKILL.md.

A good description has three parts:

[What it does] + [When to use it (trigger phrases)] + [Key capabilities]

✅ Good — specific, actionable, with explicit triggers:

description: 
Produce a comprehensive account health report combining internal and external data. Use when user says "evaluate account", "account health", "how is [company] doing", "account summary", or "give me an overview of [account]"..

❌ Bad — too vague, no triggers, won't be picked up:

description: Helps with analysis.
description: Implements the Projects and helps with analysis

Rules for the description field:

  • Under 1024 characters.

  • No XML tags (< or >) — these can confuse the loader.

  • Include trigger phrases users would actually say.

compatibility (optional)

1–500 characters describing the environment your skill needs — for example: "Requires the Python 3.10+ in the working folder."

Forbidden in frontmatter:

  • XML angle brackets anywhere — they can inject instructions into Computer's system prompt.

  • Names containing "claude" or "anthropic" — these are reserved.

Body of SKILL.md

After the --- closing fence, write your actual instructions in Markdown.

A solid structure to start from:

---
name: your-skill
description: […]
---

# Your Skill Name

## Instructions

### Step 1: [First major step]
Clear explanation of what happens.

### Step 2: [Second major step]

Example:
```bash
python scripts/fetch_data.py --project-id PROJECT_ID

Adding scripts and references

Scripts

Put executable code in scripts/. Bash, Python, anything that runs in your local environment.

Reference scripts from SKILL.md with explicit invocation:

Run `python scripts/validate.py --input {filename}` to check data format.

If validation fails, common issues include:
- Missing required fields (add them to the CSV)
- Invalid date formats (use YYYY-MM-DD)

For critical validations, prefer a script over a prose instruction. Code is deterministic; language interpretation isn't. If you've got a step that absolutely must produce the same result every time (compliance checks, schema validation, formatting), bundle it as a script and have Computer call it rather than describing the rules in markdown.

References

Put long-form documentation, API guides, examples, or schemas in references/. Reference them from SKILL.md so Computer only loads them when needed.

For the full set of Salesforce field mappings, see `references/sf-fields.md`.

Assets

Put templates, fonts, sample documents, or any non-code files in assets/. Useful for skills that generate output (a report template, a slide deck template, a logo).

Patterns that work

Five patterns that have worked well in practice:

Pattern 1 — Sequential workflow orchestration

Use when your users need a multi-step process in a specific order.

## Workflow: Onboard New Customer

### Step 1: Create Account
Call MCP tool: `create_customer`
Parameters: name, email, company

### Step 2: Setup Payment
Call MCP tool: `setup_payment_method`
Wait for: payment method verification

### Step 3: Create Subscription
Call MCP tool: `create_subscription`
Parameters: plan_id, customer_id (from Step 1)

### Step 4: Send Welcome Email
Call MCP tool: `send_email`
Template: welcome_email_template

Key techniques: explicit step ordering, dependencies between steps, validation at each stage, rollback instructions for failures.

Pattern 2 — Iterative refinement

Use when output quality improves with iteration.

### Initial Draft
1. Fetch data via MCP
2. Generate first draft report
3. Save to temporary file

### Quality Check
1. Run `scripts/check_report.py`
2. Identify issues (missing sections, inconsistent formatting, data errors)

### Refinement Loop
1. Address each issue
2. Regenerate affected sections
3. Re-validate
4. Repeat until quality threshold met

### Finalization
1. Apply final formatting
2. Generate summary
3. Save final version

Key techniques: explicit quality criteria, validation scripts, knowing when to stop iterating.

Use when the same outcome needs different tools depending on context.

Pattern 3 — Domain-specific intelligence

Use when your skill adds specialized knowledge beyond bare tool access.

### Before Processing (Compliance Check)
1. Fetch transaction details via MCP
2. Apply compliance rules:
   - Check sanctions lists
   - Verify jurisdiction allowances
   - Assess risk level
3. Document compliance decision

### Processing
IF compliance passed:
  - Call payment processing MCP tool
  - Apply appropriate fraud checks
ELSE:
  - Flag for review
  - Create compliance case

Key techniques: domain expertise embedded in logic, checks before action, comprehensive documentation, clear governance.

Problem-first vs. tool-first framing

Two ways to frame a skill, and most skills lean one way or the other:

  • Problem-first — "I need to set up a project workspace." Your skill orchestrates the right MCP calls in the right sequence. Users describe outcomes; the skill handles the tools.

  • Tool-first — "I have Notion MCP connected." Your skill teaches Computer the optimal workflows and best practices for using a specific tool well. Users have access; the skill provides the expertise.

Pick the framing that fits your use case before you start writing.

Testing your skill

Test in three areas, in increasing rigor:

Triggering tests

Goal: the skill loads at the right times.

Write 10–20 test queries split into:

  • Should trigger — obvious tasks, paraphrased requests, edge phrasings.

  • Should NOT trigger — unrelated topics, near-misses that share keywords.

Should trigger:
- "Help me set up a new ProjectHub workspace"
- "I need to create a project in ProjectHub"
- "Initialize a ProjectHub project for Q4 planning"

Should NOT trigger:
- "What's the weather in San Francisco?"
- "Help me write Python code"
- "Create a spreadsheet" (unless ProjectHub skill handles sheets)

A handy debugging trick: ask Computer "When would you use the [skill name] skill?" — it'll quote the description back. Adjust based on what's missing.

Functional tests

Goal: the skill produces correct outputs.

Test: Create project with 5 tasks
Given: Project name "Q4 Planning", 5 task descriptions
When: Skill executes workflow
Then:
  - Project created in ProjectHub
  - 5 tasks created with correct properties
  - All tasks linked to project
  - No API errors

Cover: valid outputs, API calls succeed, error handling works, edge cases.

Performance comparison

Goal: prove the skill improves over the bare-baseline.

Run the same task with and without the skill enabled and compare:

Without skill:
- User provides instructions each time
- 15 back-and-forth messages
- 3 failed API calls requiring retry
- 12,000 tokens consumed

With skill:
- Automatic workflow execution
- 2 clarifying questions only
- 0 failed API calls
- 6,000 tokens consumed

Pro tip — iterate on a single task first. Get the skill working great on one challenging task, then expand coverage. Broader testing too early gives weaker signal than a deep single-task loop.

Using the skill-creator skill

Computer ships with a built-in skill called skill-creator that helps you author, review, and iterate on skills. To use it, open a chat and say:

"Use the skill-creator skill to help me build a skill for [your use case]."

It will:

  • Walk through use case definition with you

  • Generate SKILL.md with proper frontmatter

  • Suggest trigger phrases

  • Flag common issues (vague descriptions, missing triggers, structural problems)

  • Suggest test cases based on the skill's stated purpose

When you hit edge cases in production, bring the failing example back to skill-creator and say "use the issue & solution from this chat to improve how the skill handles [specific edge case]". It'll update the skill for you.

skill-creator helps you design and refine skills. It does not produce automated test suites or quantitative evaluation results — you still run your test queries manually or via scripts.

Distributing your skill

There are three places a skill can live:

Locally on your device (My Skills)

The default. You build the skill on your machine and it's available to you on this device only. Toggle on/off from Settings → Skills → My Skills.

To install a skill someone shared with you:

  1. Get the skill folder (or a .zip of it).

  2. Add the folder to computer via the canvas, and ask computer to install it.

Org-wide (Org Skills)

Admins can publish a skill to the entire org. Once published, it appears under Settings → Skills → Org Skills for every user — no install needed. Org skills are typically lean: a single SKILL.md with prompt-style instructions and optional MCP tool references. They're not the right home , right now, for skills that need scripts or per-user state.

Troubleshooting

Skill won't upload

  • Issue: Could not find SKILL.md in uploaded folder

    Solution: The filename is case-sensitive. Rename the file to SKILL.md and re-upload.

  • Issue: Invalid frontmatter — YAML formatting issue.

    Solution: Check for these two common mistakes and correct them:

# ❌ Missing delimiters
name: my-skill
description: Does things

# ❌ Unclosed quotes
---
name: my-skill
description: "Does things
---

# ✅ Correct
---
name: my-skill
description: Does things
---

- Issue: Invalid skill name — the name: field contains spaces or uppercase letters.

Solution: Use kebab-case only (for example, my-skill).

Skill doesn't trigger

- Issue: The skill never loads automatically, even for queries where it should apply.

  Solution: Revise your description. Common causes include:

  • Too vague — "Helps with projects" won't trigger anything.

  • Missing trigger phrases — include actual phrases users would say.

  • Missing file-type hints — if the skill handles PDFs or CSVs, say so.

Debug: ask Computer "When would you use the [skill name] skill?" — it quotes the description back. Adjust based on what's missing.

Skill triggers too often

- Issue: The skill loads for unrelated queries.

Solution: Use one or more of the following approaches:

  1. Add negative triggers.

    description: Advanced data analysis for CSV files. Use for statistical modeling,
  regression, clustering. Do NOT use for simple data exploration (use data-viz
  skill instead).

  2. Be more specific.

    # ❌ Too broad
description: Processes documents
# ✅ More specific
description: Processes PDF legal documents for contract review

  3. Clarify scope.

    description: PayFlow payment processing for e-commerce. Use specifically for
  online payment workflows, not for general financial queries.

Instructions not followed

- Issue: The skill loads but Computer doesn't follow its instructions.

Solution: Check for these common causes:

  • Instructions too verbose. Keep them concise; use bullets / numbered lists; move detail to references/.

  • Instructions buried. Put critical points at the top. Use ## Important or ## Critical headers.

  • Ambiguous language.

    ❌ Make sure to validate things properly.

✅ CRITICAL: Before calling create_project, verify:
- Project name is non-empty
- At least one team member assigned
- Start date is not in the past

Was this article helpful?