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.
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.
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.
SKILL.mdAny editor works — TextEdit (in plain-text mode), VS Code, Sublime, even Notes if you save as .md. Name the file exactly SKILL.md.
name and descriptionThe description supports discovery. Name the task, output, trigger cues, and exclusions, then test activation and non-activation rather than assuming the metadata is sufficient.
# Voice section — the rules Claude followsDefine observable style choices with short bullets. Treat them as generation guidance, not guaranteed enforcement. Keep security and authorization boundaries in runtime and application controls.
# Workflow — the steps Claude followsDescribe 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.
# ExamplesExamples 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.
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.
.claude/skills/caption-writer/SKILL.md~/.claude/skills/caption-writer/SKILL.md%USERPROFILE%\.claude\skills\caption-writer\SKILL.mdStart 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.
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.