agent-skills-authoring

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

Agent Skills Authoring for Freelancerino

Use this skill when creating or updating skills in .github/skills/.

Spec essentials

• Directory per skill: .github/skills/<skill-name>/
• 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:
  • .github/skills/nextjs-cost-performance/SKILL.md
• If the skill is about DB access patterns, link to:
  • .github/skills/drizzle-tenant-queries/SKILL.md
• If the skill is about security/caching risks, link to:
  • .github/skills/security-strict/SKILL.md

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 skills-ref validate .github/skills/<skill> if available.

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