You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -30,6 +30,21 @@ When you need to add reference material about code to agent configuration:
30
30
31
31
`AGENTS.md` is the top-level agent configuration file. It uses sync blocks to embed auto-generated content and is validated by prek hooks.
32
32
33
+
### What belongs in AGENTS.md vs. agent skills
34
+
35
+
`AGENTS.md` is reserved for general-purpose reference material and high-level instructions about how to use agent skills. It is **not** the place for technical guidance on specific topics. If you want to add guidance about a particular practice, convention, or technique (e.g. how to create files, how to structure code, how to write tests), create or update an agent skill instead.
36
+
37
+
Appropriate content for `AGENTS.md`:
38
+
39
+
- Auto-generated reference material (module tree, function reference, skills registry) via sync blocks.
40
+
- High-level instructions about when and how to use agent skills (the "Generally Important Instructions" section).
41
+
42
+
Content that should go in an agent skill instead:
43
+
44
+
- Technical guidance or conventions about specific topics (e.g. file placement, code style, testing patterns).
45
+
- How-to instructions for specific tasks or workflows.
46
+
- Domain-specific best practices or project-specific rules.
47
+
33
48
### Sync blocks
34
49
35
50
Content between `<!-- sync:path/to/file -->` and `<!-- /sync:path/to/file -->` markers is auto-fixed by the `fix-doc-sync` hook. To update synced content:
@@ -42,6 +57,12 @@ Content between `<!-- sync:path/to/file -->` and `<!-- /sync:path/to/file -->` m
42
57
43
58
The skills table in `AGENTS.md` must include every skill directory under `.agents/skills/`. The `check-skills-documented` hook enforces this. When creating a new skill, add it to the table (see the `usethis-skills-create` skill for the full procedure).
44
59
60
+
## Modifying agent skills
61
+
62
+
When modifying any `SKILL.md` file, ALWAYS use the `usethis-skills-modify` skill. Do not edit skill files without it — the skill enforces version bumping, scope checking, and content quality guidelines that are essential for maintaining skill integrity. Skipping it leads to missing version bumps and scope drift.
63
+
64
+
Similarly, when creating a new skill, ALWAYS use the `usethis-skills-create` skill.
65
+
45
66
## Run static checks after modifying agent configuration
46
67
47
68
After finishing your modifications, run the static checks (e.g. `usethis-qa-static-checks`) to check for any issues before merging. This is especially important for agent configuration changes because several QA static checks involve markdown linting and formatting, which directly apply to `AGENTS.md` and skill files.
description: Guidance on where to place new files in the repository
4
+
compatibility: usethis, git
5
+
license: MIT
6
+
metadata:
7
+
version: "1.0"
8
+
---
9
+
10
+
# Creating New Files
11
+
12
+
## Repository root
13
+
14
+
The repository root is publicly facing and should be kept clean. Only standard community files belong there (e.g. `README.md`, `LICENSE`, `pyproject.toml`, `CONTRIBUTING.md`).
15
+
16
+
Before creating a new file at the root level, consider a more appropriate subdirectory:
Copy file name to clipboardExpand all lines: .agents/skills/usethis-skills-create/SKILL.md
+58-13Lines changed: 58 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,36 +4,73 @@ description: Create new agent skills (SKILL.md files) following best practices f
4
4
compatibility: usethis, agent skills, markdown
5
5
license: MIT
6
6
metadata:
7
-
version: "1.6"
7
+
version: "1.8"
8
8
---
9
9
10
10
# Creating Agent Skills
11
11
12
12
## When to create a new skill vs. modify an existing one
13
13
14
+
Prefer modifying an existing skill when:
15
+
16
+
- The new content directly serves the same purpose described in the skill's name and description.
17
+
- The existing skill is the natural home for the information.
18
+
- A more general skill already exists that covers the broader topic — add to it rather than creating a narrow sub-skill.
19
+
14
20
Prefer creating a new skill when:
15
21
16
22
- You have guidance that doesn't fit the scope of any existing skill (see the `usethis-skills-modify` skill for how to judge scope).
17
23
- An existing skill is "somewhat" related but the new content serves a different core purpose.
18
24
- Adding the content to an existing skill would make its name or description misleading.
19
25
20
-
Prefer modifying an existing skill when:
21
-
22
-
- The new content directly serves the same purpose described in the skill's name and description.
23
-
- The existing skill is the natural home for the information.
24
-
25
-
When in doubt, create a new skill — a focused skill with a clear scope is more discoverable and maintainable than an overloaded one.
26
+
When in doubt, add to an existing general skill rather than creating a new narrow one. See "Choosing the right scope" below for how to decide.
26
27
27
28
## Procedure
28
29
29
30
When creating a new skill:
30
31
31
-
1. Choose a descriptive name and create the directory `.agents/skills/<skill-name>/`.
32
-
2. Create a `SKILL.md` file with the required YAML frontmatter.
33
-
3. Write the skill content following the content guidelines below.
34
-
4. Add a row for the new skill to the usethis-specific skills table in `AGENTS.md` (under `### Skills registry` → `#### usethis-specific skills`).
35
-
5. Add cross-references to the new skill in related skills (see "Cross-referencing related skills" below).
36
-
6. Review the skill against the quality checklist at the end.
32
+
1.**Choose the right scope** — use the hierarchy brainstorming technique (see "Choosing the right scope" below) to confirm a new skill is warranted and pitched at the right level of generality.
33
+
2. Choose a descriptive name and create the directory `.agents/skills/<skill-name>/`.
34
+
3. Create a `SKILL.md` file with the required YAML frontmatter.
35
+
4. Write the skill content following the content guidelines below.
36
+
5. Add a row for the new skill to the usethis-specific skills table in `AGENTS.md` (under `### Skills registry` → `#### usethis-specific skills`).
37
+
6. Add cross-references to the new skill in related skills (see "Cross-referencing related skills" below).
38
+
7. Review the skill against the quality checklist at the end.
39
+
40
+
## Choosing the right scope
41
+
42
+
When you identify a need for new guidance that doesn't fit an existing skill, resist the temptation to jump straight to a narrowly focused skill. Instead, prefer creating a **more general** skill that the narrow topic would naturally fall under.
43
+
44
+
### The hierarchy brainstorming technique
45
+
46
+
Before creating a skill, brainstorm the ideal skill hierarchy by working from ultra-specific to fully general. For example, if you want to add guidance about where to place newly created files:
This hierarchy reveals **skill gaps** — intermediate levels that don't yet exist. In this example, both `usethis-file-create` and `usethis-file` are gaps. The principle is:
53
+
54
+
-**If a more general skill already exists** at any level in the hierarchy, add the guidance to it. Don't create a narrower sub-skill unless the general skill is already very large (>500 lines).
55
+
-**If no general skill exists**, create one at the most general level that makes sense — not the most specific. The most general level that makes sense is the broadest scope where the guidance remains cohesive. In the example above, creating `usethis-file-create` (or even `usethis-file`) is better than jumping straight to `usethis-file-create-placement`.
56
+
57
+
### Why general skills are preferred
58
+
59
+
- A general skill has **room to grow** — future guidance on related topics has a natural home.
60
+
- Narrow "stub skills" with limited scope often stay small and add clutter without much value.
61
+
- Agents discover skills by name and description. A general name like `usethis-file-create` is more discoverable than `usethis-file-create-placement` because agents searching for file creation guidance will find it.
62
+
63
+
### When to split into sub-skills
64
+
65
+
Only split a general skill into narrower sub-skills when the skill is getting large (>500 lines) and the content naturally separates into distinct concerns. This should be a deliberate decision, not the default — and it's usually only needed when explicitly instructed.
66
+
67
+
### Example
68
+
69
+
An agent needs to document guidance about where to place newly created files. No `usethis-file-create` or `usethis-file` skill exists.
70
+
71
+
-**Bad:** Create `usethis-file-placement` — this is too narrow, has limited room to grow, and the name doesn't clearly indicate it's specifically about file creation guidance.
72
+
-**Good:** Create `usethis-file-create` — this is the most general level that doesn't already exist and naturally encompasses placement guidance along with other file creation concerns.
73
+
-**Also good:** Create `usethis-file` — even more general, covering file operations broadly, with a cross-reference to the existing `usethis-file-remove` skill.
37
74
38
75
## Naming the skill
39
76
@@ -88,6 +125,11 @@ The `description` field is critical for skill discovery. Include both **what** t
-**Bad:**`"I help you modify skills"` or `"Use this to modify skills"`
90
127
128
+
**Don't be prescriptive.** The description should say what the skill covers, not command the agent to use it. Avoid "ALWAYS use when..." or "Use this skill to..." phrasing — prefer neutral descriptions like "How to..." or a plain statement of the topic.
129
+
130
+
-**Good:**`"How to modify any SKILL.md file — enforces version bumping, scope checking, and content quality guidelines"`
131
+
-**Bad:**`"ALWAYS use when modifying any SKILL.md file — enforces version bumping, scope checking, and content quality guidelines"`
132
+
91
133
Keep the description general. Ask: "What might be added to this skill in the future?" Don't focus on one specific section or aspect of the skill — instead, describe the general topic.
92
134
93
135
-**Good:**`"Maintain AGENTS.md and agent skill configuration"` — covers the broad topic
@@ -175,11 +217,14 @@ Keep cross-references lightweight: a short mention with the skill name is enough
175
217
176
218
Before finalizing a new skill, verify:
177
219
220
+
-[ ] Scope validated using the hierarchy brainstorming technique — no intermediate skill gap was skipped
221
+
-[ ] Skill is not too narrow — a more general skill doesn't already exist that this could be added to
178
222
-[ ] Name is descriptive and uses kebab-case
179
223
-[ ] Name follows general-to-specific hierarchical order
180
224
-[ ] YAML frontmatter has all required fields (`name`, `description`, `compatibility`, `license`, `metadata.version`)
181
225
-[ ] Version is a quoted string in `"MAJOR.MINOR"` format (e.g. `"1.0"`)
182
226
-[ ] Description includes what the skill does and when to use it
227
+
-[ ] Description is not prescriptive — says what the skill covers, not "ALWAYS use when..."
183
228
-[ ] Description is general — covers the broad topic, not just one specific aspect
184
229
-[ ] Content describes procedures, not codebase state
185
230
-[ ] Content is general enough to remain valid as the codebase evolves
Copy file name to clipboardExpand all lines: .agents/skills/usethis-skills-modify/SKILL.md
+3-2Lines changed: 3 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,10 +1,10 @@
1
1
---
2
2
name: usethis-skills-modify
3
-
description: Modify agent skills (SKILL.md files)
3
+
description: "Enforce version bumping, scope checking, and content quality guidelines when modifying SKILL.md files"
4
4
compatibility: usethis, agent skills, markdown
5
5
license: MIT
6
6
metadata:
7
-
version: "1.2"
7
+
version: "1.5"
8
8
---
9
9
10
10
# Modifying Agent Skills
@@ -65,6 +65,7 @@ Incrementing the version on every change helps ensure that merge conflicts are d
65
65
66
66
When modifying skill content, maintain these principles:
67
67
68
+
-**Don't make descriptions prescriptive.** If you update the `description` field in the YAML frontmatter, don't use commanding language like "ALWAYS use when..." — describe what the skill covers in neutral terms. See the `usethis-skills-create` skill for detailed description-writing guidelines.
68
69
-**Describe procedures, not state.** Skills should explain how to approach situations, not describe the current state of the codebase. State descriptions become outdated; procedures remain valid. See the `usethis-skills-create` skill for detailed guidance.
69
70
-**Keep content general.** Write instructions that remain valid as the codebase evolves. Avoid embedding specific file paths, class names, or constants unless strictly necessary.
70
71
-**Be concise.** Only include information the agent doesn't already know. If a paragraph doesn't justify its token cost, remove it.
0 commit comments