Skill Authoring

Skill Authoring

How to create, modify, and review Agent Skills for the contentful/skills repository.

For the full conventions document with templates, detailed rules, and examples, see references/conventions.md.

What is an Agent Skill?

An Agent Skill is a directory containing a SKILL.md file with YAML frontmatter and markdown instructions. It can optionally include scripts, reference documents, and assets. The format is portable across Claude Code, Cursor, GitHub Copilot, OpenAI Codex, Gemini CLI, and other agent platforms.

Skills use progressive disclosure — three tiers of context loading:

1. Metadata (~100 tokens): name and description fields loaded at startup for all installed skills. This is how the agent decides which skills are relevant.
2. Instructions (< 5000 tokens recommended): The full SKILL.md body loaded when the agent activates the skill.
3. Resources (on demand): Files in scripts/, references/, and assets/ loaded only when the instructions reference them.

The description field is the most important piece — it's always in context and determines whether the skill activates. Keep the SKILL.md body concise (under 500 lines). Heavy reference material goes in separate files.

Repository Layout

skills/                         Distributed to customers (distribution boundary)
  contentful-personalization/   A skill — name field is "contentful-personalization"
    SKILL.md
    package.json
    references/
    scripts/
    bin/
.agents/skills/                 Internal contributor skills (never distributed)
  skill-authoring/
    SKILL.md
    package.json
    references/

skills/ is the distribution boundary. Only its contents are installed via npx skills add contentful/skills. Internal skills in .agents/skills/ stay in the repo. .claude/skills is a symlink to .agents/skills/ for Claude Code discovery.

SKILL.md Format

Required Frontmatter

Optional Frontmatter

Claude Code Extensions

These fields are beyond the base agentskills.io spec — use for skills in this repo:

Body Content

Markdown after the frontmatter. No format restrictions, but recommended sections:

• Step-by-step instructions
• Examples of inputs and outputs
• Common edge cases and gotchas
• Pointers to reference files (loaded on demand)

Reference scripts and docs with relative paths from the skill root:

Run the diagnostic:
    ${CLAUDE_SKILL_DIR}/scripts/check.sh --env production

For API details, see [references/api.md](references/api.md).

Writing Effective Descriptions

The description is the sole activation trigger. The agent scans all installed skills at startup and loads only name + description (~100 tokens each). The full SKILL.md body loads only when the agent judges the skill relevant.

Write descriptions that are slightly "pushy" — it's better to activate too often than to miss a relevant trigger.

Best pattern:

Use this skill when [explicit scenarios]. Triggers on [keyword list].
Does NOT apply to [boundary conditions].

Good:

description: >-
  Diagnose and fix Contentful optimization and personalization issues.
  Validates configuration, SDK versions, API connectivity. Use when
  troubleshooting optimization problems, debugging personalization behavior,
  or checking why experiments aren't running. Also triggers on "why isn't
  personalization working" or "check my config". Not for initial end-to-end
  setup from scratch — that is covered by the onboard flow in the same
  `contentful-personalization` skill.

Bad:

description: Helps with optimization issues.

Include:

• Imperative phrasing ("Diagnose and fix", not "A skill for diagnosing")
• Direct trigger keywords the user would naturally say
• Indirect keywords (e.g., for a deploy skill, also mention "ship", "release")
• Negative scope to prevent false activations
• Cross-references to related skills with explicit phrasing (for example, the contentful-guide skill for general CMS help)

Directory Structure

Documentation-only skill (minimum)

my-skill/
  SKILL.md              Required
  package.json          Required (even for docs-only)

Skill with references

my-skill/
  SKILL.md              Required
  package.json          Required
  references/           On-demand documentation
    api.md
    patterns.md
  assets/               Templates, data files, static resources

Skill with scripts

my-skill/
  SKILL.md              Required
  package.json          Required
  scripts/              Stable public interface (SKILL.md references these)
    check               Executable (chmod +x)
    fix                 Executable (chmod +x)
  src/                  Optional — implementation behind scripts/
    ...
  references/           On-demand documentation

package.json

Required for every skill, even documentation-only. Provides versioning and npm-compatible metadata.

Distributed skills (in skills/):

{
  "name": "@contentful/skill-<domain>-<skill-name>",
  "version": "1.0.0",
  "description": "Same as SKILL.md description (short form)",
  "license": "MIT",
  "files": ["SKILL.md", "references/**", "scripts/**", "assets/**"]
}

Internal skills (in .agents/skills/):

{
  "name": "skill-name",
  "version": "1.0.0"
}

Versioning happens at the package level — metadata.version in SKILL.md frontmatter should mirror package.json version.

Naming Conventions

Name validation rules: 1-64 chars, [a-z0-9-] only, no leading/trailing/consecutive hyphens, must match parent directory name exactly.

Skills live in a flat structure directly under skills/. The name must be globally unambiguous (not just readiness) — the domain prefix makes this possible while remaining compatible with the agentskills.io spec.

Script Conventions

The key pattern

scripts/ is the skill's stable public interface. SKILL.md references only scripts/<name>, never internal paths.

Scripts can be anything executable: bash, Python, compiled binaries, Node.js, etc. The only requirement is that they are executable (chmod +x) and follow the design rules below.

Simple skills — executables directly in scripts/:

contentful-personalization/
  scripts/
    run                 Entry script (chmod +x) or thin wrapper

Complex skills — wrappers in scripts/ delegate to an implementation directory (e.g., src/, bin/):

my-code-skill/
  scripts/
    check                 Thin wrapper → delegates to src/ or bin/
  src/                    Optional — TypeScript source for skill-kit builds
    ...
  bin/                    Optional — compiled output

The wrapper decouples the skill's contract from its implementation. You can refactor src/ freely without updating SKILL.md. SKILL.md never references src/ paths — only scripts/<name>.

Wrapper example

A wrapper is a thin executable that delegates to the real implementation:

#!/usr/bin/env bash
exec node "$(dirname "$0")/../src/check.js" "$@"

Make wrappers executable: chmod +x scripts/check

For a complete TypeScript project setup (tsconfig, src/ layout, dependencies, testing), see references/typescript-scripts.md.

Script design rules

Scripts are invoked by agents in non-interactive shells. Design them so the agent can read stdout/stderr and decide what to do next.

Hard requirements:

• Non-interactive: no TTY prompts, password dialogs, or confirmation menus. All input via flags, env vars, or stdin.
• --help / -h: print usage to stderr, exit 0. This is the primary way an agent learns the script's interface.
• JSON to stdout: this is what the agent consumes. Never mix data and diagnostics on the same stream.
• Non-zero exit on failure with a descriptive error message to stderr. Say what went wrong, what was expected, and what to try.

Best practices:

• Idempotent where possible — agents may retry
• --dry-run for destructive operations
• --long-name flags (no single-letter flags except -h)
• Predictable output size: many agent harnesses truncate beyond 10-30K chars. Default to summaries; support --limit/--offset for pagination.
• Safe defaults: destructive operations require explicit --confirm or --force

For output patterns, exit code conventions, and --help templates, see references/conventions.md.

Cross-Skill References

Use explicit phrasing in SKILL.md body to reference related skills:

For personalization, use the contentful-personalization skill. Its onboard
flow covers readiness and SDK install; the doctor flow covers troubleshooting.
For "which API should I use", use the contentful-guide skill.

This is a documentation convention for the agent — no runtime enforcement.

Independence Rule

• No cross-skill imports — each skill is independently packageable
• The skills/ directory is the distribution boundary
• Shared code becomes a separate npm package
• Each skill directory must be fully self-contained

Creating a New Skill

Checklist

1. Choose the right location:

   • Customer-facing skill → skills/<skill-name>/ (flat, one directory per skill)
   • Internal contributor skill → .agents/skills/<skill-name>/

2. Create the directory with the skill name as directory name

3. Write SKILL.md:

   • Add frontmatter with name (matching directory) and description
   • Write the body with clear instructions, examples, edge cases
   • Keep under 500 lines — move heavy content to references/

4. Write package.json:

   • Distributed: @contentful/skill-<domain>-<name>, version, files array
   • Internal: just name and version

5. Add supporting files as needed:

   • references/ for on-demand documentation
   • scripts/ for executable code
   • assets/ for templates and static resources

6. Verify discovery: npx skills add . --list --full-depth

7. Update README.md if it's a distributed skill

Reviewing an Existing Skill

Checklist

• name field matches parent directory name exactly
• description is 1-1024 chars, specific about triggers and scope
• description includes negative scope ("Not for X")
• SKILL.md body is under 500 lines
• Heavy content is in references/, not inline
• package.json exists with name and version
• For distributed skills: package name follows @contentful/skill-<domain>-<name>
• Scripts are non-interactive with --help support
• No cross-skill imports — skill is self-contained
• Reference file paths are relative from skill root

Improving a Description

If a skill isn't triggering when it should (or triggers when it shouldn't):

1. Check that the description includes the keywords users actually say
2. Add indirect triggers (synonyms, related phrases)
3. Add negative scope to prevent false activations
4. Make the description slightly "pushy" — better to over-trigger
5. Test by asking the agent varied prompts and checking if the skill activates

For automated description optimization with evals, see Anthropic's skill-creator.