Claude Skills for writing work best when they handle one recurring editorial decision. Define the input, describe exactly which requests should select the Skill, then test matching and non-matching requests before relying on it. A Skill can edit a completed blog draft for structure, clarity, and house style while preserving its argument and flagging unsupported claims. It should not silently become a research tool or a general-purpose writing persona.
The practical boundary is important: a Skill supplies a repeatable procedure, not the current brief, evidence, approval history, or publication system. Those inputs must be supplied through the product surface where the Skill runs. The strongest workflow therefore combines a focused Skill with versioned documents, deterministic checks, and a named editor who owns exceptions.
This guide uses one editorial example throughout: editing a completed blog draft for publication. The same design can be adapted to other writing tasks, but each task should have its own trigger, procedure, output, and review gate.
How Claude Skills fit a writing workflow
An Anthropic Agent Skill is a folder with a required SKILL.md file and optional references, templates, examples, or scripts. The file begins with YAML frontmatter containing a name and description, followed by instructions. Anthropic describes a progressive-disclosure model: metadata is available for discovery, the instructions load when the Skill is selected, and supporting files are accessed when needed. See Anthropic’s Agent Skills overview for the documented structure and surface-specific behavior.
That structure makes a Skill a reusable procedure rather than a self-contained editorial system. A writing Skill still needs the correct draft, brief, style references, and evidence supplied or made available through the permitted surface. Start with a job that has a recognizable input, transformation, and usable output. If every assignment requires unrelated decisions, a single reusable Skill may be the wrong first tool.
Automate a repeated editorial decision only after defining its input, expected transformation, and human-owned exception.
Availability and runtime behavior differ across claude.ai, Claude Code, and the Claude API. Anthropic documents claude.ai custom Skills as user-specific, Claude Code Skills as filesystem-based, and API Skills as uploaded through the Skills API and shared workspace-wide. Skills uploaded to one surface do not automatically sync to the others. API Skills require the code execution environment and run without network access or runtime package installation, while Claude Code operates in a local environment whose available permissions may be broader.
Write the description as a routing contract
Claude uses a Skill’s name and description for discovery and routing. A label such as “brand voice” gives little guidance about when to use the procedure. Anthropic’s Skill authoring guidance recommends describing what the Skill does and when it should be used.
For the completed-draft editor, a useful description could be: “Edits an existing blog draft for structure, clarity, and house style. Use when asked to edit, polish, tighten, or prepare a draft for publication. Do not use for research or drafting from an empty brief.” It names the input, matching requests, and boundary. Automatic selection remains discovery behavior rather than a deterministic workflow gate, so test it in the product where the Skill will run.
Anthropic documents a maximum name length of 64 characters. Names must use lowercase letters, numbers, and hyphens, cannot contain XML tags, and cannot use reserved terms including “anthropic” and “claude.” The description must be non-empty, cannot contain XML tags, and can be up to 1,024 characters. Product-interface limits may differ, so confirm the current documentation before publishing a Skill.
- Positive test: “Edit this finished draft for clarity” should be in scope.
- Natural-language test: “Can you polish this post before I send it to the editor?” should match if publication preparation is in scope.
- Boundary test: “Tighten this introduction” should match only if partial edits are intended.
- Negative test: “Find current statistics for a new article” should not match.
If an in-scope request fails to select the Skill, make the description more concrete and rerun the test. If it appears on research or blank-brief requests, narrow the boundary. Where the product supports explicit selection or invocation, keep that manual path available for review and troubleshooting.
Build one focused writing Skill
Choose a job with repeatable editorial decisions, such as editing a completed blog post for structure, clarity, and house style while preserving its argument. Capture corrections that recur in real work: retain useful specifics, keep evidence near the claim it supports, avoid unnecessary rewrites, and repair transitions after cuts. These decisions make better instructions than a broad request to “make it good.”
Keep SKILL.md as a concise ordered procedure. Put detailed style rules, banned phrases, and approved examples in supporting files, and tell Claude when to consult them. A hypothetical folder could look like this:
blog-editing-workflow/
SKILL.md
style-guide.md
banned-phrases.md
examples/
approved-intros.md
scripts/
check_style.pyThis folder is an illustrative design, not an Anthropic-provided editorial template. Use reasoning instructions for decisions that require judgment, reference files for material that must be consulted, and scripts for checks with deterministic answers. A script can detect an exact banned phrase or missing heading; it cannot decide whether the article’s argument is persuasive or whether its voice still belongs to the writer.
A practical procedure is to read the full draft, identify its argument and intended reader, check whether the opening fulfills the article’s promise, edit structure and clarity, apply relevant style references, run the final checklist, and return the revised draft with evidence gaps flagged. Avoid prescribing every sentence rhythm or preferred turn of phrase. Overly rigid creative rules can make prose compliant but lifeless.
SKILL.md; move detailed references into separate files.Define a reviewable output and validation gate
Replace “make this good” with checks an editor can inspect: required headings, banned terms, supported claims, preserved examples, repaired transitions, and fit for the intended reader. Use scripts for exact tests such as phrase detection, required headings, link format, or word limits. Use editorial review for argument preservation, voice, evidence sufficiency, and strategic fit.
The following is a hypothetical review contract for one run on one document version and one Skill version. It is not a native Claude or ClickUp schema:
{
"review_run_id": "run-2026-0017",
"document_id": "blog-104",
"document_version_id": "v7",
"skill_version": "1.2",
"decision": "revise",
"issues": [
{
"type": "evidence",
"location": "Results section",
"action": "Request a source for the performance claim"
}
],
"evidence_needed": [
"Source for the performance claim"
],
"reviewer_required": true
}Validate that required fields exist and that decision uses an allowed value such as pass, revise, or block. Route an evidence gap to the editor rather than asking the model to invent support. Save the revised text as a new version in the editorial system of record, with the review record linked to that version. Do not overwrite the source draft.
Keep the data grain explicit. One review record should mean one run on one document version with one Skill version. If model variants or prompt versions are compared, store those dimensions on the run record. Store individual citations as separate citation records with their own identity rather than placing citation-level observations into a run-level row.
When duplicate prevention matters, enforce a database unique constraint or use a transactional upsert on the intended key. A read-then-insert check alone can race when concurrent runs arrive. A proposed key such as document_id + document_version_id + skill_version + model_variant + workflow_stage is an implementation choice, not a vendor-published field. Add a separate run identifier when the same version may be reviewed intentionally more than once.
A structured result makes a review inspectable. It does not verify a claim, prevent duplicate runs, or grant publication approval. Validate the fields and permitted values, then route consequential decisions to the person who owns them.
Test the Skill on real drafts and boundary cases
Before routine use, run at least three representative drafts: a straightforward draft, one with known style violations, and one with unresolved factual claims. Compare each result with a no-Skill baseline. Judge whether the specified task improved, not whether the model changed more text. Check that relevant reference files were consulted and that mechanical checks catch known violations.
| Trigger and input | AI job | Validation and destination | Exception |
|---|---|---|---|
| Existing blog draft plus a request to edit, polish, or prepare it for publication | Preserve the argument and useful specifics; improve structure, clarity, transitions, and applicable style | Run heading, phrase, link, and format checks; save a new draft version and review record | Send factual or strategic questions to the editor instead of resolving them by invention |
| Existing draft plus a partial-edit request, such as tightening an introduction | Make only the requested change while checking its effect on the surrounding promise and transition | Compare the changed passage with the source version; return the focused revision for review | Ask for the full brief when the local change could alter the article’s argument |
| Blank brief or request for current research | Do not apply the editing procedure; route to the appropriate research or planning workflow | Record that the request was out of scope; no editorial version is created | Require a draft and evidence-handling instructions before activating the editing Skill |
Use test records with the case, expected behavior, observed Skill selection, output defects, and next revision. If in-scope requests fail to select the Skill, revise the description. If an instruction is ignored, make the step explicit or add it to a final checklist. If prose becomes stiff, loosen creative constraints while retaining verifiable rules. If a claim lacks evidence, route it for sourcing or removal.
- Test a positive request, a natural-language request, a boundary request, and a negative request.
- Include a known style violation and confirm that the mechanical check detects it.
- Include an evidence gap and confirm that it is flagged rather than filled with invented support.
- Compare with a no-Skill baseline and inspect whether useful specifics survived.
- Confirm that the editor, system of record, document version, and Skill version are recorded.
Anthropic’s official Skills repository offers examples, templates, and learning material. Anthropic presents the repository as educational, so inspect and test examples rather than treating them as production-ready editorial procedures. Review third-party instructions and scripts as software because accessible files, tools, and network permissions depend on the execution surface.
Choose the right home for the procedure
These mechanisms solve different problems and should not be treated as interchangeable:
- Claude Skill: a reusable procedure with optional references and scripts. Use it when the repeated decision is mainly about the text.
- Project context: material tied to one campaign, client, or workspace. Keep the current brief, terminology, and project decisions with that project.
- Persistent instructions: broad preferences such as spelling conventions. Do not use them as a substitute for a task sequence.
- Command or explicit invocation: a deliberate entry point where the installed surface supports it. This differs from automatic discovery.
- External tool or work-platform connection: access to outside systems, live data, permissions, assignments, or status changes. Verify the actual connection and permission path before designing around it.
Use a portable Claude Skill when the recurring decision is mainly about the text itself. Use a workspace-based process when assignment, comments, deadlines, permissions, or ownership affect the decision. Teams designing those states and handoffs in ClickUp can review ClickUp setup and automation as a related implementation service.
Deployment, access, and ownership
Anthropic documents custom Skills across claude.ai, Claude Code, and the Claude API, but their storage and execution differ. In claude.ai, custom Skills are individual to the user. In Claude Code, personal Skills can live in ~/.claude/skills/ and project Skills in .claude/skills/; project files can be version-controlled with the repository. For the API, Skills are uploaded through the Skills API and shared workspace-wide.
Anthropic documents creating an API Skill with POST /v1/skills and uploading files with SKILL.md at the root of the Skill directory. API execution requires the code execution environment. The API Skill runtime has no network access or runtime package installation, so it is not a live web-research environment. Claude Code runs locally, where available filesystem and network permissions may be broader. Review Skill instructions and scripts according to the permissions of the environment that will execute them.
Anthropic documents custom claude.ai Skills for Pro, Max, Team, and Enterprise plans. Product eligibility and interface details can change, so confirm the current plan requirements before promising availability. Enterprise Skill and plugin scanning covers certain third-party uploads in Claude and Cowork, with documented exclusions including API and Console uploads, MCP servers, hooks, and Skills shared through connected MCP servers. A passing scan is not a complete safety guarantee.
ClickUp AI Skills are saved instructions used by ClickUp Brain and Super Agents. ClickUp documents creation, sharing, enabling, templates, and Skills Miner, subject to plan, role, and enabled ClickApps. Skills Miner surfaces repeated workflows from Workspace material, but ClickUp publishes no accuracy benchmark for it. ClickUp documents manual, scheduled, and Automation triggers for Super Agents. Those features can support a content-review design, but the scoring, assignment, exception, approval, and duplicate-handling logic must be configured and tested for the specific workflow.
For repeated automated reviews, key each saved result to the document version and Skill version, and enforce uniqueness in the system of record where duplicate prevention matters. Require explicit human approval before a consequential status change or publication. Teams defining an agent that acts on workspace context can explore AI agent implementation.
The operating target is modest and testable: the right requests find the procedure, the procedure improves a specified editorial task, deterministic checks catch exact defects, and a named editor resolves judgment calls before publication.