add-skill

Add Skill

Coordinate adding a new external skill to the agent-skills repository. Covers scaffolding, publish workflow registration, and symlink creation.

When to Use

Use this skill when:

• Adding a new SDK/framework integration skill to skills/
• Adding a new CLI tool wrapper skill to skills/
• Any time a skills/<skill-name>/ directory needs to be created and registered

Decision Point

Ask first:

Is this an integration skill (agent generates code + tests calling real APIs) or a tool skill (agent runs a CLI command)?

• Integration → Invoke create-seed-skill, then continue with Steps 2–4
• Tool → Scaffold manually starting at Step 1

---

Integration Skill Workflow

Integration skills wrap SDKs or frameworks where the agent generates runnable code and integration tests.

Examples: ydc-ai-sdk-integration, teams-anthropic-integration, ydc-openai-agent-sdk-integration

Step 1 (integration) — Invoke create-seed-skill

Activate the create-seed-skill skill. It handles:

• Collecting skill info (name, packages, language — TypeScript, Python, or both, paths A/B, env vars, test query)
• Generating skills/<skill-name>/SKILL.md and assets/
• Creating tests/<skill-name>/ directories with .gitkeep files (one per language if both)
• Appending one prompts.jsonl entry per language to data/prompts/prompts.jsonl

Complete the create-seed-skill workflow fully before proceeding to Step 2.

---

Tool Skill Workflow

Tool skills are CLI wrappers where the agent runs commands rather than writing code.

Examples: youdotcom-cli

Step 1 — Scaffold the skill directory

Create the skill directory and SKILL.md at skills/<skill-name>/SKILL.md.

Required frontmatter:

---
name: <skill-name>
description: |
  One-line summary. When to activate.
license: <ISC|MIT|Apache-2.0>
compatibility: <runtime requirements, e.g. "Requires Bun 1.3+">
metadata:
  author: youdotcom-oss
  version: "1.0.0"
  category: <tool|integration|scaffolding>
  keywords: <comma-separated>
---

Validate immediately:

bunx @plaited/development-skills validate-skill skills/<skill-name>

---

Step 2 — Register in publish.yml

Two edits to .github/workflows/publish.yml:

2a — Add input

Under on.workflow_dispatch.inputs, add:

<skill-name>:
  description: "<skill-name>"
  required: false
  type: choice
  default: skip
  options:
    - skip
    - patch
    - minor
    - major

2b — Add job

Append at the end of the jobs: section. The new job must needs the current last job to preserve push serialization:

publish-<skill-name>:
  needs: <current-last-job>
  if: ${{ always() && inputs['<skill-name>'] != 'skip' }}
  uses: ./.github/workflows/_publish.yml
  with:
    skill_name: "<skill-name>"
    bump_type: ${{ inputs['<skill-name>'] }}
  secrets:
    PUBLISH_TOKEN: ${{ secrets.PUBLISH_TOKEN }}

Find the current last job at runtime — do not rely on a hardcoded list. Run this to get the job ID to use as needs:

grep '^  publish-' .github/workflows/publish.yml | tail -1

The output will be a line like publish-youdotcom-cli: — use the job ID (without the trailing colon) as <current-last-job>.

The always() in if: is required — without it a skipped predecessor causes the dependent job to be skipped too, even if this skill was selected.

---

Step 3 — Create symlink

External skills symlink from .claude/skills/ into skills/:

ln -s ../../skills/<skill-name> .claude/skills/<skill-name>

Note: internal skills (in .agents/skills/) use a different target: ../../.agents/skills/<skill-name> — but this skill only handles external skills.

---

Step 4 — Final validation

bunx @plaited/development-skills validate-skill skills/<skill-name>

Confirm the output reports valid: true before committing.

---

Related Skills

• create-seed-skill — Full scaffolding workflow for integration-type skills (SKILL.md + assets + prompts.jsonl)
• validate-skill — Validate any skill's structure against the AgentSkills spec