Skip to content

Commit ceded75

Browse files
Copilotnathanjmcdougall
Copilot
and
nathanjmcdougall
authored
Add hierarchical naming convention guidance to usethis-skills-create (#1543)
* Initial plan * Add hierarchical naming convention guidance to usethis-skills-create skill Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com> Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/1707b65b-698c-442d-b921-91122ac5df38 --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com>
1 parent f1eaa76 commit ceded75

File tree

1 file changed

+23
-2
lines changed
  • .agents/skills/usethis-skills-create

1 file changed

+23
-2
lines changed

‎.agents/skills/usethis-skills-create/SKILL.md‎

Lines changed: 23 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ description: Create new agent skills (SKILL.md files) following best practices f
44
compatibility: usethis, agent skills, markdown
55
license: MIT
66
metadata:
7-
version: "1.0"
7+
version: "1.1"
88
---
99

1010
# Creating Agent Skills
@@ -24,9 +24,29 @@ Use kebab-case (lowercase with hyphens). The name should clearly communicate wha
2424

2525
Prefer specific, descriptive names over vague ones:
2626

27-
- **Good:** `usethis-qa-static-checks`, `usethis-prek-add-hook`
27+
- **Good:** `usethis-qa-static-checks`, `usethis-prek-hook-bespoke-create`
2828
- **Bad:** `helper`, `utils`, `tools`
2929

30+
### Hierarchical naming
31+
32+
Organize names from general to specific, using a hierarchical structure: `<project>-<domain>-<topic>-<subtopic>-<action>`. This keeps related skills grouped together and makes names predictable.
33+
34+
- Start with the project prefix (e.g. `usethis-`).
35+
- Follow with the domain or category (e.g. `python-`, `qa-`, `prek-`).
36+
- Then the topic (e.g. `code`, `hook`, `skills`).
37+
- Optionally narrow with a subtopic (e.g. `bespoke`).
38+
- End with a specific action if the skill is narrow in scope (e.g. `create`, `modify`).
39+
40+
For example, skills about bespoke prek hooks would be named:
41+
42+
- `usethis-prek-hook-bespoke` — general guidance on bespoke hooks (topic-level skill)
43+
- `usethis-prek-hook-bespoke-create` — creating a new bespoke hook
44+
- `usethis-prek-hook-bespoke-modify` — modifying an existing bespoke hook
45+
46+
**Bad:** `usethis-prek-bespoke-hook` — this breaks the general-to-specific order by placing the subtopic (`bespoke`) before the topic (`hook`).
47+
48+
When in doubt, think about how the name would sort alphabetically alongside related skills. Related skills should cluster together.
49+
3050
## YAML frontmatter format
3151

3252
All `SKILL.md` files must include the following YAML frontmatter:
@@ -119,6 +139,7 @@ If content grows beyond this, split details into separate reference files in the
119139
Before finalizing a new skill, verify:
120140

121141
- [ ] Name is descriptive and uses kebab-case
142+
- [ ] Name follows general-to-specific hierarchical order
122143
- [ ] YAML frontmatter has all required fields (`name`, `description`, `compatibility`, `license`, `metadata.version`)
123144
- [ ] Version is a quoted string in `"MAJOR.MINOR"` format (e.g. `"1.0"`)
124145
- [ ] Description includes what the skill does and when to use it

0 commit comments

Comments
 (0)