home / skills / dtinth / agent-skills / agent-skills

agent-skills skill

safe

This skill helps you manage project specific skills in the .claude/skills directory, enabling creation and improvement of SKILL.md.

npx playbooks add skill dtinth/agent-skills --skill agent-skills

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.0 KB

---
name: agent-skills
description: Manage project-specific skills in the .claude/skills directory. Use this skill to understand skill structure, create new skills, or improve existing skills based on work session learnings.
---

# Agent Skills

- Agent skills in this project are stored in `.claude/skills/` directory
- Each skill is a folder with a `SKILL.md` file inside it
- The skill folder name must match the `name` field in the SKILL.md frontmatter
- The frontmatter requires `name` (lowercase alphanumeric with hyphens only, no start/end hyphens, no consecutive hyphens) and `description` (describes what the skill does and when to use it)
- The Markdown body after the frontmatter contains the skill instructions with no format restrictions
- Skills can have optional subdirectories: `scripts/` for executable code, `references/` for documentation, `assets/` for templates and resources
- Keep the main SKILL.md body under 500 lines for efficiency; move detailed reference material to separate files in `references/`
- When referencing other files in a skill, use relative paths from the skill root (e.g., `references/REFERENCE.md` or `scripts/extract.py`)
- File references should be one level deep from SKILL.md to avoid deeply nested reference chains
- All skill improvements should be made by editing the SKILL.md file in place, since skills are Git-tracked files in the codebase
- When improving a skill based on work session learnings, edit the SKILL.md file to reflect new insights
- After updating a skill file, the next agent session will load the improved skill automatically
- Progressive disclosure keeps skills efficient: metadata loads at startup (~100 tokens), full instructions load on activation (<5000 tokens recommended), resources load on demand
- Test your skill improvements by thinking through: Does the description clearly indicate when to use it? Are the instructions clear and self-contained? Can the agent follow them without additional context?
- Document why you're making a skill improvement in the Git commit message if the change needs explanation

Overview

This skill manages project-specific agent skills stored under the .claude/skills directory. It helps you inspect skill structure, create new skills, and iterate on existing skill definitions based on session learnings. The goal is efficient, discoverable skills that load progressively and stay easy to maintain.

How this skill works

The skill inspects each skill folder and its definition file to verify naming, metadata, and supporting resources. It validates required frontmatter fields, recommends where to place scripts, references, and assets, and guides edits to update skills after a work session. It also enforces concise main instructions and one-level file references for predictable loading behavior.

When to use it

When adding a new project-specific skill to the workspace
When improving an existing skill after a work session
When validating skill folder structure and naming conventions
When organizing detailed references or executable scripts
When preparing skills for reliable progressive loading

Best practices

Use a single definition file per skill and keep the main instruction body concise (under ~500 lines).
Name skill folders and the definition name consistently using lowercase alphanumeric and hyphens; avoid leading, trailing, or consecutive hyphens.
Place executable code in a scripts/ subdirectory, long documentation in references/, and templates in assets/ to keep the main file focused.
Reference other files with simple relative paths one level deep from the skill root to prevent deep nesting.
Document the reason for any improvement in the commit message so future sessions and collaborators understand the intent.

Example use cases

Create a new skill for parsing invoices and put parsing scripts in scripts/, sample templates in assets/, and full specs in references/.
After a sprint, update a skill’s instructions to reflect new heuristics discovered during testing so the next session uses improved guidance.
Run a quick validation pass to ensure every skill folder follows naming rules and includes required metadata before sharing the project.
Refactor a voluminous main instruction into a short summary and move long examples into references/ to speed activation.

FAQ

How do I test that an updated skill will be used in the next session?

Edit the skill definition file in place; the next agent session will load the improved instructions automatically.

What counts as a good main instruction length?

Keep the main instruction concise—aim for under 500 lines; move deep reference material to the references/ subdirectory.