Skip to content

Commit 1eec8eb

Browse files
Copilotnathanjmcdougall
Copilot
and
nathanjmcdougall
committed
Address review: bullet format, sync markers, simpler description
- Change SKILL.md description to "Maintain AGENTS.md and agent skill configuration" (remove one-source-of-truth mention) - Convert skills directory from table to bullet-point format in both the export hook and generated docs/skills-directory.txt - Wrap usethis-specific skills in AGENTS.md with sync markers for docs/skills-directory.txt Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/771b656a-119e-447c-9562-00cb146df84d Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com>
1 parent cbce013 commit 1eec8eb

4 files changed

Lines changed: 53 additions & 61 deletions

File tree

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
name: usethis-agents
3-
description: Maintain AGENTS.md and agent skill configuration following the one-source-of-truth principle
3+
description: Maintain AGENTS.md and agent skill configuration
44
compatibility: usethis, agent skills, markdown
55
license: MIT
66
metadata:

‎AGENTS.md‎

Lines changed: 26 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -207,30 +207,32 @@ The `.agents/skills` directory contains agent skills.
207207

208208
#### usethis-specific skills
209209

210-
| Skill | Description |
211-
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
212-
| `usethis-agents` | Maintain AGENTS.md and agent skill configuration following the one-source-of-truth principle |
213-
| `usethis-cli-modify` | Modify the usethis CLI layer (commands, options, help text) and keep documentation in sync |
214-
| `usethis-file-remove` | Remove files from the project (e.g. obsolete configs or generated artifacts) in a safe, consistent way |
215-
| `usethis-github-actions-update` | Update GitHub Actions workflows |
216-
| `usethis-github-issue-create` | Create GitHub issues via the gh CLI to record lessons, track follow-up work, or file bugs discovered during development |
217-
| `usethis-pre-commit` | Guidance on pre-commit hooks — this project uses prek, not pre-commit directly |
218-
| `usethis-prek-add-hook` | Add a prek hook for dev |
219-
| `usethis-prek-hook-bespoke-create` | Write bespoke prek hooks as Python scripts for custom project-specific checks |
220-
| `usethis-python-code` | Guidelines for Python code design decisions such as when to share vs. duplicate code |
221-
| `usethis-python-code-modify` | Modify Python code (e.g. refactor, add new code, or delete code) |
222-
| `usethis-python-enum` | Style and testing conventions for working with Python enums |
223-
| `usethis-python-functions` | Guidelines for Python function design, including return types and signature simplicity |
224-
| `usethis-python-module-layout-modify` | Modify the Python module layout (create, move, rename, or delete modules) |
225-
| `usethis-python-ruff` | Guidelines for complying with Ruff linter rules instead of suppressing them |
226-
| `usethis-python-test-affected-find` | Identify tests that are potentially affected by code changes, to catch regressions before CI |
227-
| `usethis-qa-import-linter` | Use the Import Linter software on the usethis project |
228-
| `usethis-qa-static-checks` | Perform static code checks |
229-
| `usethis-skills-create` | Create new agent skills (SKILL.md files) following best practices for content quality, structure, and discoverability |
230-
| `usethis-skills-external-add` | Add an external (community) skill and document it in AGENTS.md |
231-
| `usethis-skills-external-install` | Install/reinstall already-tracked external skills from skills-lock.json (e.g. after a fresh clone) |
232-
| `usethis-skills-modify` | Modify agent skills (SKILL.md files) |
233-
| `usethis-python-test-full-coverage` | Write tests that achieve full code coverage and verify coverage locally before pushing |
210+
<!-- sync:docs/skills-directory.txt -->
211+
212+
- `usethis-agents`: Maintain AGENTS.md and agent skill configuration
213+
- `usethis-cli-modify`: Modify the usethis CLI layer (commands, options, help text) and keep documentation in sync
214+
- `usethis-file-remove`: Remove files from the project
215+
- `usethis-github-actions-update`: Update GitHub Actions workflows
216+
- `usethis-github-issue-create`: Create GitHub issues via the gh CLI to record lessons, track follow-up work, or file bugs discovered during development
217+
- `usethis-pre-commit`: Guidance on pre-commit hooks — this project uses prek, not pre-commit directly
218+
- `usethis-prek-add-hook`: Add a prek hook for dev
219+
- `usethis-prek-hook-bespoke-create`: Write bespoke prek hooks as Python scripts for custom project-specific checks
220+
- `usethis-python-code`: Guidelines for Python code design decisions such as when to share vs. duplicate code
221+
- `usethis-python-code-modify`: Modify Python code (e.g. refactor, add new code, or delete code)
222+
- `usethis-python-enum`: Style and testing conventions for working with Python enums
223+
- `usethis-python-functions`: Guidelines for Python function design, including return types and signature simplicity
224+
- `usethis-python-module-layout-modify`: Modify the Python module layout (create, move, rename, or delete modules)
225+
- `usethis-python-ruff`: Guidelines for complying with Ruff linter rules instead of suppressing them
226+
- `usethis-python-test-affected-find`: Identify tests that are potentially affected by code changes, to catch regressions before CI
227+
- `usethis-python-test-full-coverage`: Write tests that achieve full code coverage and verify coverage locally before pushing
228+
- `usethis-qa-import-linter`: Use the Import Linter software on the usethis project
229+
- `usethis-qa-static-checks`: Perform static code checks
230+
- `usethis-skills-create`: Create new agent skills (SKILL.md files) following best practices for content quality, structure, and discoverability
231+
- `usethis-skills-external-add`: Add an external (community) skill to the project from a third-party source, including installing it and documenting it in AGENTS.md
232+
- `usethis-skills-external-install`: Reinstall already-tracked external skills from skills-lock.json (e.g. after a fresh clone)
233+
- `usethis-skills-modify`: Modify agent skills (SKILL.md files)
234+
235+
<!-- /sync:docs/skills-directory.txt -->
234236

235237
#### External skills
236238

‎docs/skills-directory.txt‎

Lines changed: 22 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,22 @@
1-
| Skill | Description |
2-
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
3-
| `usethis-agents` | Maintain AGENTS.md and agent skill configuration following the one-source-of-truth principle |
4-
| `usethis-cli-modify` | Modify the usethis CLI layer (commands, options, help text) and keep documentation in sync |
5-
| `usethis-file-remove` | Remove files from the project |
6-
| `usethis-github-actions-update` | Update GitHub Actions workflows |
7-
| `usethis-github-issue-create` | Create GitHub issues via the gh CLI to record lessons, track follow-up work, or file bugs discovered during development |
8-
| `usethis-pre-commit` | Guidance on pre-commit hooks — this project uses prek, not pre-commit directly |
9-
| `usethis-prek-add-hook` | Add a prek hook for dev |
10-
| `usethis-prek-hook-bespoke-create` | Write bespoke prek hooks as Python scripts for custom project-specific checks |
11-
| `usethis-python-code` | Guidelines for Python code design decisions such as when to share vs. duplicate code |
12-
| `usethis-python-code-modify` | Modify Python code (e.g. refactor, add new code, or delete code) |
13-
| `usethis-python-enum` | Style and testing conventions for working with Python enums |
14-
| `usethis-python-functions` | Guidelines for Python function design, including return types and signature simplicity |
15-
| `usethis-python-module-layout-modify` | Modify the Python module layout (create, move, rename, or delete modules) |
16-
| `usethis-python-ruff` | Guidelines for complying with Ruff linter rules instead of suppressing them |
17-
| `usethis-python-test-affected-find` | Identify tests that are potentially affected by code changes, to catch regressions before CI |
18-
| `usethis-python-test-full-coverage` | Write tests that achieve full code coverage and verify coverage locally before pushing |
19-
| `usethis-qa-import-linter` | Use the Import Linter software on the usethis project |
20-
| `usethis-qa-static-checks` | Perform static code checks |
21-
| `usethis-skills-create` | Create new agent skills (SKILL.md files) following best practices for content quality, structure, and discoverability |
22-
| `usethis-skills-external-add` | Add an external (community) skill to the project from a third-party source, including installing it and documenting it in AGENTS.md |
23-
| `usethis-skills-external-install` | Reinstall already-tracked external skills from skills-lock.json (e.g. after a fresh clone) |
24-
| `usethis-skills-modify` | Modify agent skills (SKILL.md files) |
1+
- `usethis-agents`: Maintain AGENTS.md and agent skill configuration
2+
- `usethis-cli-modify`: Modify the usethis CLI layer (commands, options, help text) and keep documentation in sync
3+
- `usethis-file-remove`: Remove files from the project
4+
- `usethis-github-actions-update`: Update GitHub Actions workflows
5+
- `usethis-github-issue-create`: Create GitHub issues via the gh CLI to record lessons, track follow-up work, or file bugs discovered during development
6+
- `usethis-pre-commit`: Guidance on pre-commit hooks — this project uses prek, not pre-commit directly
7+
- `usethis-prek-add-hook`: Add a prek hook for dev
8+
- `usethis-prek-hook-bespoke-create`: Write bespoke prek hooks as Python scripts for custom project-specific checks
9+
- `usethis-python-code`: Guidelines for Python code design decisions such as when to share vs. duplicate code
10+
- `usethis-python-code-modify`: Modify Python code (e.g. refactor, add new code, or delete code)
11+
- `usethis-python-enum`: Style and testing conventions for working with Python enums
12+
- `usethis-python-functions`: Guidelines for Python function design, including return types and signature simplicity
13+
- `usethis-python-module-layout-modify`: Modify the Python module layout (create, move, rename, or delete modules)
14+
- `usethis-python-ruff`: Guidelines for complying with Ruff linter rules instead of suppressing them
15+
- `usethis-python-test-affected-find`: Identify tests that are potentially affected by code changes, to catch regressions before CI
16+
- `usethis-python-test-full-coverage`: Write tests that achieve full code coverage and verify coverage locally before pushing
17+
- `usethis-qa-import-linter`: Use the Import Linter software on the usethis project
18+
- `usethis-qa-static-checks`: Perform static code checks
19+
- `usethis-skills-create`: Create new agent skills (SKILL.md files) following best practices for content quality, structure, and discoverability
20+
- `usethis-skills-external-add`: Add an external (community) skill to the project from a third-party source, including installing it and documenting it in AGENTS.md
21+
- `usethis-skills-external-install`: Reinstall already-tracked external skills from skills-lock.json (e.g. after a fresh clone)
22+
- `usethis-skills-modify`: Modify agent skills (SKILL.md files)

‎hooks/export-skills-directory.py‎

Lines changed: 4 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
33
Scans agent skill directories for SKILL.md files, extracts the name and
44
description from each file's YAML frontmatter, and writes a formatted
5-
Markdown table to an output file.
5+
Markdown bullet list to an output file.
66
"""
77

88
from __future__ import annotations
@@ -31,7 +31,7 @@ def _parse_frontmatter(path: Path) -> dict[str, str]:
3131

3232

3333
def main() -> int:
34-
"""Export a skills directory table from SKILL.md frontmatter."""
34+
"""Export a skills directory bullet list from SKILL.md frontmatter."""
3535
parser = argparse.ArgumentParser(
3636
description="Export a skills directory from SKILL.md frontmatter.",
3737
)
@@ -43,7 +43,7 @@ def main() -> int:
4343
parser.add_argument(
4444
"--output-file",
4545
required=True,
46-
help="Path to the output file to write the directory table to.",
46+
help="Path to the output file to write the directory to.",
4747
)
4848
parser.add_argument(
4949
"--prefix",
@@ -84,17 +84,9 @@ def main() -> int:
8484
print("ERROR: No skills found.", file=sys.stderr)
8585
return 1
8686

87-
name_width = max(len(f"`{name}`") for name, _ in rows)
88-
desc_width = max(len(desc) for _, desc in rows)
89-
name_width = max(name_width, len("Skill"))
90-
desc_width = max(desc_width, len("Description"))
91-
9287
lines: list[str] = []
93-
lines.append(f"| {'Skill':<{name_width}} | {'Description':<{desc_width}} |")
94-
lines.append(f"| {'-' * name_width} | {'-' * desc_width} |")
9588
for name, desc in rows:
96-
formatted_name = f"`{name}`"
97-
lines.append(f"| {formatted_name:<{name_width}} | {desc:<{desc_width}} |")
89+
lines.append(f"- `{name}`: {desc}")
9890

9991
content = "\n".join(lines) + "\n"
10092

0 commit comments

Comments
 (0)