Pencel

Appearance

Writing Effective Skills ​

Skills are reusable capability packages — named bundles of instructions that agents load when they are relevant to the current task. A good skill teaches the agent how to handle a recurring problem in a consistent way. A bad skill burns context on generic advice the agent already has.

The principles below are the same ones in the Authoring Rubric — consult that page for the full rationale. This page applies the rubric specifically to skills.

Name the skill for discovery ​

The skill's name and description feed semantic activation. A generic name never gets retrieved, no matter how good the body is.

Weak:

helper-skill
writing-helper
data-stuff

Strong:

analyzing-sap-access-requests
drafting-exec-summaries
reconciling-intercompany-balances

Prefer kebab-case, gerund-form. Use the same terminology you use at work — the retrieval system matches against your own vocabulary.

One sentence, two pieces of information ​

The description field is the single most important piece of metadata. Treat it like the subject line of an email: it must state WHAT the skill does AND WHEN to use it, in one sentence, so that another agent reading a list of skills can decide whether to load yours.

Weak:

Helps with access requests.

Strong:

Evaluates SAP access requests against the SOD matrix and role-card minimums, flagging conflicts, dormant accounts, and dual-approval requirements — use when reviewing any access request or quarterly access review item.

Write instructions the way you'd write a runbook ​

Lead with a "When to use" or "Quick start" section. Put the 80% case in the first screen. Link to deeper references only when they genuinely exist. Use headings so the agent can skim.

  • Be specific. Every instruction should be mechanically checkable. "Be thorough" is not an instruction.
  • Explain the why alongside non-obvious rules. A one-line reason lets the agent handle the edge cases you didn't anticipate. "Use Treasury FX rates only — market rates drift and produce consolidation differences."
  • Match degree-of-freedom to fragility. Use prose for judgment calls; use exact commands or checklists for fragile steps.
  • Include one concrete example if the skill has any style or formatting dimension. One example teaches more than three paragraphs of description.
  • No time-sensitive content in the main body. Put "this was true before X" in a clearly labeled ## Legacy section.

Activation mode: default to "when relevant" ​

Skills have two activation modes:

  • Always — loaded on every task. Pay this cost only for identity/safety-rail skills that genuinely apply to everything the agent does. A healthy workspace has very few of these.
  • When relevant — loaded only when the current task semantically matches the skill. This is the right default for almost every skill you create.

If the skill is only useful for a specific domain (finance close, code review, customer emails), it is when relevant. Not always.

When to split a skill into two ​

If you find yourself writing "and also" between two distinct capabilities, split the skill. Semantic retrieval gets sharper when each skill covers one well-scoped ability, and you can adjust activation per skill.

Bad: a single finance-helpers skill containing reconciliation, flux analysis, and flash-report formatting.

Good: three skills — reconciling-intercompany-balances, analyzing-month-over-month-flux, formatting-flash-reports — each with its own activation mode and retrieval signature.

Quick checklist before saving ​

  • [ ] Name is specific, kebab-case, and uses your own terminology.
  • [ ] Description is one sentence containing both what and when.
  • [ ] Instructions lead with "When to use" or "Quick start".
  • [ ] Every rule is mechanically checkable — no aspirations.
  • [ ] Non-obvious rules include a why clause.
  • [ ] At least one concrete example if style matters.
  • [ ] No time-sensitive content in the main body.
  • [ ] Activation mode is when relevant unless the skill genuinely applies to every task.
  • [ ] The skill covers one capability, not several.