Skip to content

claude-skill-packaging.md

Latest commit

 

History

History
56 lines (40 loc) · 3.56 KB

claude-skill-packaging.md

File metadata and controls

56 lines (40 loc) · 3.56 KB
Raw

Claude Skill packaging

Status: roadmap. A dedicated Claude Skill packaging target is planned but not implemented. This page documents how today's generated package maps onto Claude's Agent Skills conventions, a manual conversion recipe that works now, and the planned automation. Nothing here should be read as a shipped --target claude-skill flag.

What Claude expects

Claude Code and the Claude Agent SDK discover skills as a directory containing a SKILL.md whose body holds the instructions and whose YAML frontmatter carries at least a name and a description (the description drives skill triggering). Project skills live under .claude/skills/<skill-name>/, personal skills under ~/.claude/skills/<skill-name>/, and plugins can bundle skills as well. Supporting files may sit next to SKILL.md.

What forge generates today

A forge package (see skill-package-format.md) is already a flat directory centered on a SKILL.md:

calendar-scheduling-skill-1.0.0.zip
├── SKILL.md                 # instructions — no YAML frontmatter yet
├── skill.manifest.json      # name, version, description, tools, quality gate
├── tools.json               # tool contracts
├── eval-cases.json          # verification evidence
├── verification-rules.json
├── examples.md
├── README.md
├── verification-report.html # gate evidence
├── verification-summary.json
└── package-info.json        # provenance: run ID, model, verifier, metrics

The overlap is deliberate: the SKILL.md body sections (When to Use, When Not to Use, Tool Use Rules, Safety Rules, Failure Behavior, …) are exactly the content a Claude skill wants. The gap is the frontmatter — forge keeps name/description in skill.manifest.json instead.

Manual conversion (works today)

  1. Unzip the release package.

  2. Prepend frontmatter to SKILL.md, copying the fields from skill.manifest.json:

    ---
name: calendar-scheduling-skill
description: Help an agent schedule calendar events safely. Use when the user asks to check availability, propose meeting slots, or create calendar events.
---

# calendar-scheduling-skill
...existing generated body...

    Tip: extend the manifest description with "Use when …" trigger phrasing — the frontmatter description is what the model reads when deciding to activate the skill.

  3. Copy the folder to .claude/skills/calendar-scheduling-skill/. Keep examples.md (useful context); the eval/verification files are optional at runtime — they are evidence, not instructions — but keeping them documents why this skill version was released.

  4. Review the skill by hand before use. Forge's verification is structural; it does not execute the skill against a live model.

Planned automation (roadmap)

Tracked in roadmap.md ("Claude Skill packaging examples"):

  • A packaging target (e.g. --package-format claude-skill) that emits the frontmatter from the manifest, writes the .claude/skills/<name>/ layout, and separates runtime files from verification evidence.
  • Trigger-description generation: derive the "Use when …" sentence from the requirement's goals so activation quality is part of the spec, not an afterthought.
  • A verification rule that lints the frontmatter (name matches manifest, description length, no forbidden claims) so the same quality gate covers the Claude-specific surface.

If you want this sooner, the seam to extend is src/packaging/package-builder.ts — packaging is a pure function over the verified skill directory.