mirror of https://github.com/contentful/skills.git synced 2026-09-14 20:17:03 +08:00

Files

T

Tim Beyer 304df8742d fix: add post-build script to fix skill package.json after skill-kit build

skill-kit build overwrites package.json with a minimal {name, version},
losing the scoped name, description, license, and files fields. The
release pipeline now runs fix-skill-packagejson.mjs after build to
restore repo conventions and sync the version from root package.json.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-04-24 10:35:35 +02:00

3.1 KiB

Raw Permalink Blame History

Contentful Skills — Claude Code

Read AGENTS.md for general project conventions (naming, structure, distribution boundary, commit format).

This file covers Claude Code-specific configuration.

Internal Skills

Internal contributor skills live in .agents/skills/ and are symlinked at .claude/skills for Claude Code discovery. Use /skill-authoring to get guidance on creating, modifying, or reviewing skills.

Claude Code Frontmatter Extensions

When authoring skills for this repo, these Claude Code-specific frontmatter fields are available beyond the base agentskills.io spec:

Field	Description
`disable-model-invocation`	`true` prevents auto-loading; user must invoke via `/<name>`
`user-invocable`	`false` hides from `/` menu; Claude can still auto-load
`context`	`fork` runs in an isolated subagent
`agent`	Subagent type when `context: fork` (`Explore`, `Plan`, `general-purpose`, or custom)
`model`	Model override when skill is active
`effort`	Effort level override (`low`, `medium`, `high`, `max`)
`argument-hint`	Autocomplete hint, e.g., `[issue-number]`
`hooks`	Hooks scoped to this skill's lifecycle

String Substitutions

$ARGUMENTS — all arguments passed to the skill
$0, $1, etc. — positional arguments
${CLAUDE_SESSION_ID} — current session ID
${CLAUDE_SKILL_DIR} — the skill's directory path

Dynamic Context

Use !`command` in SKILL.md to run a shell command before sending skill content to Claude.

skill-kit Skills

Some skills are built with @contentful/skill-kit — TypeScript source compiled to CLI binaries. Source lives in src/skills/, build output in skills/.

Commands

pnpm install — install dependencies
pnpm run typecheck — type check TypeScript source
pnpm run test — run all skill tests
pnpm run build — build skill-kit skills (requires Bun)

Structure

src/skills/<skill-name>/     # TypeScript source (not distributed)
  skill.ts                   # Skill definition
  skill.test.ts              # Tests
  schemas.ts                 # Shared Zod schemas
  actions/                   # CLI-side actions
  references/                # Reference docs (copied to output)
skills/<skill-name>/         # Build output (distributed)
  SKILL.md                   # Generated
  package.json               # Manually maintained (see below)
  scripts/run                # Generated shell wrapper
  bin/                       # Compiled binaries
  references/                # Copied from source

package.json for skill-kit skills

skill-kit build overwrites package.json with a minimal {name, version}. The release pipeline runs node scripts/fix-skill-packagejson.mjs after build to restore repo conventions (@contentful/skill-* name, repo version, license, files).

When adding a new skill-kit skill, ensure its built package.json has a description field — the fix script preserves existing fields but doesn't invent descriptions. Run node scripts/fix-skill-packagejson.mjs after your first build to verify.

3.1 KiB Raw Permalink Blame History