Skills Architecture

How the skills system works between Cowork Desktop and Claude Code Desktop (CCD).

Two skill environments

Environment	Path	CCD Prefix	Managed by
Cowork 3p	~/Library/Application Support/Claude-3p/local-agent-mode-sessions/skills-plugin/<uuid>/<uuid>/	anthropic-skills:<name>	Cowork Desktop
Claude Code global	~/.claude/skills/<name>/	<name> (no prefix)	Manual

Rule: do not duplicate skills between the two environments. Choose a single source of truth.

Cowork 3p Plugin Structure

<plugin-uuid>/
└── <instance-uuid>/
    ├── .claude-plugin/
    │   └── plugin.json        → plugin namespace
    ├── manifest.json           → registry (managed by Cowork)
    └── skills/
        └── <skill-name>/
            ├── SKILL.md        → required
            ├── LICENSE.txt     → optional
            ├── scripts/        → optional (executable code)
            ├── references/     → optional (docs loaded on demand)
            ├── assets/         → optional (templates, icons, fonts)
            └── agents/         → optional (subagent instructions)

manifest.json

Skills registry. Each entry:

{
  "skillId": "skill-name",
  "name": "skill-name",
  "description": "When to use and what it does",
  "creatorType": "user | anthropic",
  "syncManaged": false,
  "updatedAt": "2026-07-07T20:55:26.452Z",
  "enabled": true
}

Important: Cowork Desktop manages manifest.json. Direct edits are reverted by the process. Register skills via Cowork UI or copy the folder and restart.

How CCD discovers skills

1. CCD reads the manifest.json of the active plugin instance
2. Each skill appears as anthropic-skills:<name> in the available list
3. The description in SKILL.md frontmatter is the triggering mechanism
4. CCD does NOT read from other plugin instances

Skill Anatomy (OKF + Bundled Resources)

Any skill (user or anthropic) can have bundled resources:

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/    → executable code (PEP 723, etc.)
    ├── references/ → docs loaded into context on demand
    ├── assets/     → files used in output (templates, icons)
    └── agents/     → instructions for specialized subagents

Progressive Disclosure (3 levels)

1. Metadata (name + description) — always in context (~100 words)
2. SKILL.md body — in context when skill triggers (<500 lines ideal)
3. Bundled resources — on demand (scripts execute without loading into context)

skill-creator

Anthropic's official skill for creating, testing, iterating, and optimizing skills. Includes:

• Complete workflow: draft → test → eval → iterate → package
• Eval viewer for human review
• Benchmarking with variance analysis
• Description optimization to improve triggering
• Agents: grader, comparator, analyzer

Available as anthropic-skills:skill-creator in CCD.

Discoveries (2026-07-07)

• Multiple plugin instances exist under skills-plugin/ (different UUIDs)
• CCD only reads from the active instance
• Copying skill folder between instances + restarting Cowork is sufficient to register
• /reload-skills in CCD reloads the available skills list
• creatorType and bundled resources are metadata, not limitations — user skills can have everything