PART 05 — PHASE 3

Build your first skill, from scratch.

We'll build a deliberately small, instruction-only caption-drafting skill. It will use synthetic examples, request no secrets, and stop before publishing. You will then test whether Claude discovers it and follows its boundaries.

20–25 Min Claude Your Brain

Reviewed 31 August 2026. These paths apply to Claude Code custom skills: project skills live under .claude/skills/ and personal skills under ~/.claude/skills/. API skills use a different packaging and constrained code-execution workflow. Verify the current Agent Skills overview before implementation.

The skill we're building — "caption-writer"

This example drafts short social captions with a defined structure. It does not publish, access accounts, or claim to reproduce anyone's identity. Replace examples only with synthetic material or content you have permission to use; remove personal, client, and confidential information.

1

Open a text editor and create SKILL.md

Any editor works — TextEdit (in plain-text mode), VS Code, Sublime, even Notes if you save as .md. Name the file exactly SKILL.md.

2

Write the frontmatter — name and description

The description supports discovery. Name the task, output, trigger cues, and exclusions, then test activation and non-activation rather than assuming the metadata is sufficient.

  caption-writer / SKILL.md — step 2
--- name: caption-writer description: Draft short-form social captions when the user asks for a caption, hook, or social post; do not use for long-form articles, direct messages, or publishing. ---
3

Add a # Voice section — the rules Claude follows

Define observable style choices with short bullets. Treat them as generation guidance, not guaranteed enforcement. Keep security and authorization boundaries in runtime and application controls.

  caption-writer / SKILL.md — step 3
--- name: caption-writer description: Draft short-form social captions when requested; never publish... --- # Voice - Short sentences. Under 14 words each. - One idea per line — no filler. - End with a question or a CTA. - Never use emojis unless asked.
4

Add a # Workflow — the steps Claude follows

Describe the intended order and what to do when context is missing. A workflow can reduce ambiguity, but it does not guarantee sequence or replace an approval control.

  caption-writer / SKILL.md — step 4
[ frontmatter and # Voice from step 3 ] # Workflow 1. Ask which platform (IG, LinkedIn, X). 2. Ask the single most important point. 3. Draft three options. Label them 1, 2, 3. 4. Ask which direction to tighten. 5. Never publish, message, or access an account; return drafts only.
5

Add 1–2 synthetic or rights-cleared # Examples

Examples can clarify format and tone. Start with fictional content; use your own material only when you have the rights and have removed confidential or personal data. Test for unwanted copying and bias.

  caption-writer / SKILL.md — step 5 (final)
[ frontmatter, # Voice, # Workflow from above ] # Examples Prompt: "Caption for LinkedIn about a fictional product demo." 1. "One less manual step. The fictional Acme demo now exports drafts in one click." 2. "We simplified the demo workflow. What repetitive step should the Acme team test next?" 3. "A smaller workflow can still remove friction. This fictional example is ready for review—not publishing."
6

Choose project or personal scope in Claude Code

Use project scope when the skill belongs with a repository and personal scope only when it should be available across your own projects. Review repository disclosure before committing examples or references. A new Claude Code session may be needed for discovery.

PROJECT.claude/skills/caption-writer/SKILL.md
PERSONAL · macOS/Linux~/.claude/skills/caption-writer/SKILL.md
PERSONAL · Windows%USERPROFILE%\.claude\skills\caption-writer\SKILL.md
7

Test it — open Claude and ask for a caption

Start a fresh Claude Code session with no secrets or production data in scope. Test an intended request, a near miss such as a blog post, an adversarial request to publish, and missing context. Verify that no external action occurs and inspect tool/permission logs.

If behavior misses the rubric, diagnose whether discovery, instructions, examples, conflicting skills, model variation, or runtime controls caused it. Change one thing, record the version, and rerun the same test set.

What you just did

You created a minimal skill candidate with an explicit non-publishing boundary. It is ready for controlled evaluation—not automatic trust or distribution. The next part turns the expected behavior into a repeatable test suite and adds failure, privacy, and approval checks.

← Part 4 — Establishing trust Part 6 — Make it testable →