| 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 namedescription: 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
- Metadata (name/description) always loaded.
- Body loads when skill matches.
- 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
