Pencel

Appearance

Writing Skills ​

Skills are the reusable capabilities your agents reach for when they encounter a recurring task. Where a guideline says "never do X" and a workflow says "run these steps end to end", a skill says "here's how to handle this specific kind of task when you see one." This guide walks you through creating one.

For the principles behind what makes a skill effective, see the Authoring Rubric and Writing Effective Skills.

Step-by-step: Create a skill ​

1. Open the Knowledge view ​

Navigate to Knowledge in the left sidebar. In the Folders column, click the Skills row at the bottom (sparkles icon). The middle column lists your skills.

2. Create a skill ​

Click the + button next to the filter field (tooltip: New skill) to create a skill with a starter template in the editor (When to use, Steps, Checks, Output, Example). Replace the placeholders with your real runbook. You can also use Add Knowledge in the page header → Generate with AI → set the type to Skill if you want a first draft from a short description.

3. Name the skill ​

Use kebab-case and the gerund form when you can — it reads naturally in a list and helps semantic retrieval. Good examples:

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

Avoid generic names like helper, skill-1, or data-stuff. The name is what the system matches against when deciding whether to load your skill for a given task — be specific with your own work terminology.

4. Write the one-sentence description ​

The description field is the most important piece of metadata. It should state what the skill does and when to use it in a single sentence.

Weak:

Helps with access requests.

Strong:

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

Start with an active verb. Never write "helps you" or "assists with" — say what the skill does.

5. Pick a category ​

Pencel ships with a set of skill categories: general, writing, analysis, coding, research, communication, data, custom. Pick the best fit. Default to general only if nothing else matches.

6. Write the instructions ​

This is the body of the skill — the actual markdown the agent will read when the skill is loaded. Structure it like a mini runbook:

markdown
## When to use
A specific trigger — what task prompts the agent to reach for this skill.

## Steps
1. First step, specific enough that a reviewer can verify it was followed.
2. Second step. Include *why* alongside any non-obvious rule.
3. …

## Example
One concrete input → expected output pair if the skill has any style dimension.

Effective instructions are:

  • Specific — every rule can be mechanically checked. "Be thorough" is not a rule.
  • Concise — every character is injected into the agent's context. Don't explain what SQL or JSON are.
  • Consistent — pick one term per concept and reuse it throughout.
  • Example-backed — one concrete example teaches more than three paragraphs of description.

Put the 80% case in the first screen; link to longer reference material only if it genuinely exists.

7. Set the activation mode ​

Skills have two modes:

  • Always — loaded on every task, no matter what. Reserve this for identity or safety-rail skills that apply to everything.
  • When relevant — loaded only when the current task semantically matches the skill. This is the right default for almost every skill.

WARNING

Do not default to Always. Each always-active skill uses tokens on every agent run, crowding out the actual task. "When relevant" uses Pencel's semantic matching to surface the skill only when it's needed — which is almost always what you want.

8. Save ​

Click Save. The skill takes effect immediately and will be surfaced by semantic matching when future tasks match.

Tips by skill type ​

Capability skills (analyzing-X, reconciling-Y) ​

Focus on the checks and the output format. If the skill produces a specific artifact shape, define the fields.

Drafting skills (drafting-X, writing-Y) ​

Include at least one before/after example of the desired voice. Describe tone, length, and formatting constraints.

Review skills (reviewing-X, critiquing-Y) ​

List the things the agent should actively look for. Include failure modes. Specify the output shape of the review (what fields, what order).

How many skills do you need? ​

Start small. Three to five skills covering your most common recurring tasks is plenty to begin with. Add new skills when you notice you're repeatedly giving the agent the same instructions inline.

If you find yourself writing more than fifteen skills in a workspace, audit for overlap — two overlapping skills will both load when their shared keywords appear, which doubles the token cost without doubling the value.

Next steps ​