usethis-python · nathanjmcdougall · Mar 25, 2026 · Mar 25, 2026 · Mar 25, 2026 · Mar 25, 2026
diff --git a/...nts/skills/github-actions-update/SKILL.md → ...ls/usethis-github-actions-update/SKILL.md b/...nts/skills/github-actions-update/SKILL.md → ...ls/usethis-github-actions-update/SKILL.md
@@ -1,10 +1,10 @@
 ---
-name: github-actions-update
+name: usethis-github-actions-update
 description: Update GitHub Actions workflows
 compatibility: GitHub Actions, YAML
 license: MIT
 metadata:
-  version: "1.0"
+  version: "2.0"
 ---
 
 # GitHub Actions Workflows

diff --git a/.agents/skills/usethis-skills-create/SKILL.md b/.agents/skills/usethis-skills-create/SKILL.md
@@ -4,7 +4,7 @@ description: Create new agent skills (SKILL.md files) following best practices f
 compatibility: usethis, agent skills, markdown
 license: MIT
 metadata:
-  version: "1.1"
+  version: "1.3"
 ---
 
 # Creating Agent Skills
@@ -16,12 +16,15 @@ When creating a new skill:
 1. Choose a descriptive name and create the directory `.agents/skills/<skill-name>/`.
 2. Create a `SKILL.md` file with the required YAML frontmatter.
 3. Write the skill content following the content guidelines below.
-4. Review the skill against the quality checklist at the end.
+4. Add a row for the new skill to the usethis-specific skills table in `AGENTS.md` (under `### Skills registry` → `#### usethis-specific skills`).
+5. Review the skill against the quality checklist at the end.
 
 ## Naming the skill
 
 Use kebab-case (lowercase with hyphens). The name should clearly communicate what the skill does at a glance.
 
+**All skill names must start with the `usethis-` prefix.** This is enforced by the `check-skills-documented` hook.
+
 Prefer specific, descriptive names over vague ones:
 
 - **Good:** `usethis-qa-static-checks`, `usethis-prek-hook-bespoke-create`
@@ -149,3 +152,4 @@ Before finalizing a new skill, verify:
 - [ ] Terminology is consistent throughout
 - [ ] Content is concise — no unnecessary explanations
 - [ ] SKILL.md body is under 500 lines
+- [ ] Skill is added to the usethis-specific skills table in `AGENTS.md`
diff --git a/.agents/skills/usethis-skills-external-add/SKILL.md b/.agents/skills/usethis-skills-external-add/SKILL.md
@@ -0,0 +1,49 @@
+---
+name: usethis-skills-external-add
+description: Add an external (community) skill to the project from a third-party source, including installing it and documenting it in AGENTS.md
+compatibility: usethis, agent skills, npx, markdown
+license: MIT
+metadata:
+  version: "1.0"
+---
+
+# Adding External Skills
+
+External skills are sourced from third-party repositories rather than written locally. They live in `skills-lock.json` and must be documented in the external skills registry in `AGENTS.md`.
+
+## Procedure
+
+1. Install the skills using `npx skills add <source> --skill '*' --agent github-copilot --yes` (e.g. `npx skills add CodSpeedHQ/codspeed --skill '*' --agent github-copilot --yes`).
+2. Note the skill name(s) added to `skills-lock.json`.
+3. Add each new skill to the external skills registry in `AGENTS.md`.
+4. Verify the hook passes: `python hooks/check-skills-documented.py`.
+
+## Installing the skill
+
+To **add a new** external skill, run from the repository root:
+
+```commandline
+npx skills add <github-org>/<repo> --skill '*' --agent github-copilot --yes
+```
+
+This adds the skill entry to `skills-lock.json`. Multiple skills may be added from a single source.
+
+To **reinstall** already-tracked external skills that are not present locally (e.g. after a fresh clone):
+
+```commandline
+npx skills experimental_install
+```
+
+## Documenting in AGENTS.md
+
+After installing, add a row to the external skills table in the "External skills" section of `AGENTS.md`:
+
+```markdown
+| `<skill-name>` | `<github-org>/<repo>` | Brief description of what the skill does |
+```
+
+Keep descriptions concise — one sentence covering what the skill does and when to use it.
+
+## Verification
+
+The `hooks/check-skills-documented.py` hook checks that every skill in `skills-lock.json` that does not start with `usethis-` is listed in `AGENTS.md`. Run it to confirm the documentation is complete before committing.
diff --git a/.github/workflows/copilot-setup-steps.yml b/.github/workflows/copilot-setup-steps.yml
@@ -26,5 +26,11 @@ jobs:
                   enable-cache: true
                   activate-environment: true
 
+            - name: Set up Node.js
+              uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+
+            - name: Install external agent skills
+              run: npx skills experimental_install
+
             - name: Setup dependencies
               run: uv sync
diff --git a/.gitignore b/.gitignore
@@ -162,4 +162,8 @@ cython_debug/
 #.idea/
 
 # Windsurf config
-.windsurfrules
+.windsurfrules
+
+# Agent config
+.agents/skills/*
+!.agents/skills/usethis-*
diff --git a/AGENTS.md b/AGENTS.md
@@ -12,20 +12,15 @@ Follow standard contributing guidelines as documented in CONTRIBUTING.md.
 
 The `.agents/skills` directory contains agent skills.
 
-### Important skills
-
-- Always run static checks using the `usethis-qa-static-checks` skill before finishing a task.
-- If modifying Python code, always use the `usethis-python-code`, `usethis-python-code-modify`, and `usethis-python-module-layout-modify` skills.
-- If modifying the CLI layer (`_ui` package), always use the `usethis-cli-modify` skill.
-
 ### Skills registry
 
-<!-- This list is validated by the hooks/check-skills-documented.py hook. -->
+#### usethis-specific skills
 
 | Skill                                 | Description                                                                                                           |
 | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| `github-actions-update`               | Update GitHub Actions workflows                                                                                       |
-| `usethis-file-remove`                 | Remove files from the project                                                                                         |
+| `usethis-cli-modify`                  | Update GitHub Actions workflows                                                                                       |
+| `usethis-file-remove`                 | Modify the usethis CLI layer (commands, options, help text) and keep documentation in sync                            |
+| `usethis-github-actions-update`       | Update GitHub Actions workflows                                                                                       |
 | `usethis-pre-commit`                  | Guidance on pre-commit hooks — this project uses prek, not pre-commit directly                                        |
 | `usethis-prek-add-hook`               | Add a prek hook for dev                                                                                               |
 | `usethis-prek-hook-bespoke-create`    | Write bespoke prek hooks as Python scripts for custom project-specific checks                                         |
@@ -39,5 +34,22 @@ The `.agents/skills` directory contains agent skills.
 | `usethis-qa-import-linter`            | Use the Import Linter software on the usethis project                                                                 |
 | `usethis-qa-static-checks`            | Perform static code checks                                                                                            |
 | `usethis-skills-create`               | Create new agent skills (SKILL.md files) following best practices for content quality, structure, and discoverability |
+| `usethis-skills-external-add`         | Add an external (community) skill and document it in AGENTS.md                                                        |
 | `usethis-skills-modify`               | Modify agent skills (SKILL.md files)                                                                                  |
 | `usethis-test-with-coverage`          | Write tests that achieve full code coverage and verify coverage locally before pushing                                |
+
+#### External skills
+
+External skills can be installed via `npx skills experimental_install` if they are not present.
+
+| Skill                    | Source                | Description                                                             |
+| ------------------------ | --------------------- | ----------------------------------------------------------------------- |
+| `codspeed-optimize`      | `CodSpeedHQ/codspeed` | Optimize code for performance using CodSpeed benchmarks and flamegraphs |
+| `codspeed-setup-harness` | `CodSpeedHQ/codspeed` | Set up performance benchmarks and the CodSpeed harness for a project    |
+
+### Important Instructions about Skills usage
+
+- ALWAYS use possibly relevant agent skills when they are available. Eagerly use skills, if in doubt, assume a skill is relevant.
+- ALWAYS consider the `usethis-qa-static-checks` to be relevant: if you think your task
+  is complete, always run this skill to check for any issues before finishing.
+- ALWAYS mention which skills you've used after completing any task, in PR descriptions, and comments.
diff --git a/hooks/check-skills-documented.py b/hooks/check-skills-documented.py
@@ -1,12 +1,21 @@
-"""Check that all skills in .agents/skills/ are mentioned in AGENTS.md."""
+"""Check that all skills are documented in AGENTS.md.
+
+Two checks are performed:
+1. Skills in .agents/skills/ that start with 'usethis-' must appear in AGENTS.md.
+2. External skills in skills-lock.json (those not starting with 'usethis-') must
+   appear in AGENTS.md.
+"""
 
 from __future__ import annotations
 
+import json
 import sys
 from pathlib import Path
 
 AGENTS_MD = Path("AGENTS.md")
 SKILLS_DIR = Path(".agents/skills")
+SKILLS_LOCK = Path("skills-lock.json")
+USETHIS_PREFIX = "usethis-"
 
 
 def main() -> int:
@@ -18,23 +27,60 @@ def main() -> int:
         print(f"ERROR: {SKILLS_DIR} directory not found.", file=sys.stderr)
         return 1
 
-    agents_md_content = AGENTS_MD.read_text()
+    if not SKILLS_LOCK.is_file():
+        print(f"ERROR: {SKILLS_LOCK} not found.", file=sys.stderr)
+        return 1
+
+    agents_md_content = AGENTS_MD.read_text(encoding="utf-8")
+    failed = False
 
-    missing = [
+    # Check 1: usethis- skills in the skills directory must be documented.
+    usethis_skills = [
         d.name
         for d in sorted(SKILLS_DIR.iterdir())
-        if d.is_dir() and d.name not in agents_md_content
+        if d.is_dir() and d.name.startswith(USETHIS_PREFIX)
     ]
-
-    if missing:
+    undocumented_local = [
+        name for name in usethis_skills if name not in agents_md_content
+    ]
+    if undocumented_local:
         print(
-            "ERROR: The following skills are not mentioned in AGENTS.md:",
+            f"ERROR: The following skills in {SKILLS_DIR} are not documented in {AGENTS_MD}:",
             file=sys.stderr,
         )
-        for skill in missing:
+        for skill in undocumented_local:
             print(f"  - {skill}", file=sys.stderr)
         print(file=sys.stderr)
         print("Please add them to the skills registry in AGENTS.md.", file=sys.stderr)
+        failed = True
+
+    # Check 2: external skills in skills-lock.json must be documented.
+    data = json.loads(SKILLS_LOCK.read_text(encoding="utf-8"))
+    external_skills = [
+        name
+        for name in sorted(data.get("skills", {}).keys())
+        if not name.startswith(USETHIS_PREFIX)
+    ]
+    undocumented_external = [
+        name for name in external_skills if name not in agents_md_content
+    ]
+    if undocumented_external:
+        if failed:
+            print(file=sys.stderr)
+        print(
+            f"ERROR: The following external skills in {SKILLS_LOCK} are not documented in {AGENTS_MD}:",
+            file=sys.stderr,
+        )
+        for skill in undocumented_external:
+            print(f"  - {skill}", file=sys.stderr)
+        print(file=sys.stderr)
+        print(
+            "Please add them to the external skills registry in AGENTS.md.",
+            file=sys.stderr,
+        )
+        failed = True
+
+    if failed:
         return 1
 
     print("All skills are documented in AGENTS.md.")

diff --git a/skills-lock.json b/skills-lock.json
@@ -0,0 +1,15 @@
+{
+  "version": 1,
+  "skills": {
+    "codspeed-optimize": {
+      "source": "CodSpeedHQ/codspeed",
+      "sourceType": "github",
+      "computedHash": "7645f43a7a8ca9705a9a8e7367ac1f4ad9d8822ba94230e2b38381c05957d5c5"
+    },
+    "codspeed-setup-harness": {
+      "source": "CodSpeedHQ/codspeed",
+      "sourceType": "github",
+      "computedHash": "bd861b140b75372438d0dbbf5b697e563a80d567bc8bb2b3f2880cdfe41ef27f"
+    }
+  }
+}