agent-skills-authoring

name	agent-skills-authoring
description	Use this skill when you are creating or updating Agent Skills in your project (structure, YAML frontmatter, naming, and progressive disclosure).

Agent Skills Authoring

Use this skill when creating or updating Agent Skills in your project.

Spec essentials

• Directory per skill: wherever your project stores skills (commonly a dedicated skills directory)
• SKILL.md required with YAML frontmatter:
  • name: lowercase, a-z0-9-hyphen, 1-64 chars, no leading/trailing/consecutive hyphens; must match directory name
  • description: 1-1024 chars; describe what + when to use
  • Optional: license, compatibility, metadata (map), allowed-tools (space-delimited)
• Body: instructions, steps, examples. Keep under ~500 lines; move deep refs to references/.

Progressive disclosure

1. Metadata (name/description) always loaded.
2. Body loads when skill matches.
3. Resources load on demand (scripts, references, assets). Keep references one level deep.

Recommended sections

• Purpose and when to use
• Required steps/checklist
• Patterns/examples
• Edge cases
• Testing/validation
• References to repo files

Cost & performance guidance for skills

When authoring or updating a skill, keep cost/perf advice centralized and non-duplicative:

• If the skill is about Next.js behavior (routing, Server Actions, caching, streaming), prefer linking to:
  • nextjs-cost-performance skill
• If the skill is about DB access patterns, link to:
  • drizzle-tenant-queries skill
• If the skill is about security/caching risks, link to:
  • security-strict skill

Avoid copying large performance checklists into every skill. Instead:

• Add a short “Cost & performance notes” section with 3–6 bullets.
• Keep it tenant-safe (workspace-scoped keys/tags).
• Prefer “how to verify” steps (lint/typecheck/test/build) over speculative advice.

Validation

• Use your skills validation tool (if available) against your skills directory.

Security

• If adding scripts, note dependencies and risks. Consider allowlists/sandboxing.

References

• Agent Skills spec: https://agentskills.io/specification
• Integration guide: https://agentskills.io/integrate-skills
• VS Code skills doc: https://code.visualstudio.com/docs/copilot/customization/agent-skills