feat(skill): teach command namespaces

.github/workflows/publish-skill.yml

@@ -100,7 +100,7 @@ jobs:
 
             ```bash
             # Install this skill
-            fastskill add https://github.com/${{ github.repository }}.git
+            fastskill skill add https://github.com/${{ github.repository }}.git
             ```
 
             ## Contents

.github/workflows/skill-evals.yml

@@ -4,9 +4,15 @@ on:
   push:
     branches: [main]
     paths:
+      - 'README.md'
+      - 'CONTRIBUTING.md'
+      - 'CLAUDE.md'
+      - 'fastskill/SKILL.md'
       - 'fastskill/skill-project.toml'
       - 'fastskill/references/eval.md'
       - 'evals/**'
+      - 'scripts/**'
+      - 'specs/**'
       - '.github/workflows/skill-evals.yml'
   # No `paths:` filter here on purpose. `validate` and `score-fixtures` are
   # required status checks, and a required check that is skipped by a path
@@ -45,6 +51,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - name: Validate canonical command namespaces
+        run: |
+          python3 -m unittest scripts/test_command_namespaces.py
+          python3 scripts/check-command-namespaces.py
       - name: Install FastSkill CLI
         run: |
           curl -fsSL https://raw.githubusercontent.com/gofastskill/fastskill/main/scripts/install.sh | bash

CLAUDE.md

@@ -1,6 +1,6 @@
 # CLAUDE.md
 
-This repository contains the FastSkill skill for AI Agent Skills, installed and used via the FastSkill CLI (`fastskill add https://github.com/gofastskill/skill.git`).
+This repository contains the FastSkill skill for AI Agent Skills, installed and used via the FastSkill CLI (`fastskill skill add https://github.com/gofastskill/skill.git`).
 
 ## Pull request automation
 

CONTRIBUTING.md

@@ -24,9 +24,15 @@ from the `fastskill/` directory so path resolution finds that manifest and `../e
 ## Development
 
 1. Edit files in the `fastskill/` subdirectory (and `evals/` when extending the suite)
-2. Open a pull request from a branch off the latest `origin/main` (see `CLAUDE.md`) —
+2. Run `python3 -m unittest scripts/test_command_namespaces.py` and
+   `python3 scripts/check-command-namespaces.py` from the repository root
+3. Open a pull request from a branch off the latest `origin/main` (see `CLAUDE.md`) —
    changes land via PR with required status checks, not by pushing to `main` directly
-3. On merge, the CI/CD workflow automatically packages and publishes a new release
+4. On merge, the CI/CD workflow automatically packages and publishes a new release
+
+The syntax check is deterministic and does not need a FastSkill binary. Before releasing,
+repeat the eval validation and fixture scoring below with the candidate FastSkill binary on
+`PATH`; the installed public release may still expose the previous breaking command tree.
 
 ## Evaluations
 
@@ -91,7 +97,8 @@ a check that contradicts the column is rejected rather than silently resolved. S
 
 `.github/workflows/skill-evals.yml` gates changes to the skill/eval files:
 
-- **validate** and **score-fixtures** run on every push/PR — deterministic, no agent, no tokens.
+- **namespace syntax**, **validate**, and **score-fixtures** run on every push/PR — deterministic,
+  no agent, no tokens.
 - **live-eval** is opt-in via *Run workflow* (`workflow_dispatch`), runs the v1 suite against a
   real agent, and needs `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` secrets.
 

README.md

@@ -1,15 +1,22 @@
 # FastSkill Skill Repository
 
-This repository contains the FastSkill skill for AI Agent Skills. Use the FastSkill CLI to install and use it.
+This repository contains the FastSkill skill for AI Agent Skills. Install it with the
+FastSkill CLI to give agents current guidance for skill projects, packages, bundles,
+repositories, evaluations, and operations.
 
 ## Installation
 
 From your project root:
 
 ```bash
-fastskill add https://github.com/gofastskill/skill.git
+fastskill project init
+fastskill skill add https://github.com/gofastskill/skill.git
 ```
 
+Read the installed skill with `fastskill skill read fastskill`. The skill documents the
+canonical command namespaces introduced by the breaking CLI migration; use a matching
+FastSkill release.
+
 See [CONTRIBUTING.md](CONTRIBUTING.md) for development and release details.
 
 ## License

evals/README.md

@@ -36,6 +36,8 @@ evals/
 from `fastskill/` and the fixture check runs from the repo root.
 
 ```bash
+python3 scripts/check-command-namespaces.py                    # canonical CLI syntax, no binary
+
 cd fastskill
 fastskill eval validate                                   # schema + config, no agent
 cd ..
@@ -47,6 +49,9 @@ fastskill eval run --agent claude --output-dir ../eval-runs
 fastskill eval report --run-dir ../eval-runs/<timestamp>/claude
 ```
 
+Run the FastSkill commands with the candidate binary on `PATH` when validating a breaking
+CLI release. The namespace syntax check remains useful before that binary exists.
+
 `eval score` is read-only. Every number it reports is a function of the run's artifacts,
 and scoring the committed fixtures leaves the tree clean. The backfill of `command_count`
 and the token counts now happens in `eval run`, at write time, where the writer owns the

evals/fixtures/pass/eval-skill/aggregated.json

@@ -4,9 +4,9 @@
     {
       "trial_id": 1,
       "status": "passed",
-      "command_count": 2,
+      "command_count": 1,
       "input_tokens": 6,
-      "output_tokens": 1778,
+      "output_tokens": 35,
       "check_results": [
         {
           "check_name": "skill_invoked",
@@ -28,4 +28,4 @@
   "pass_count": 1,
   "total_trials": 1,
   "pass_rate": 1.0
-}
+}

evals/fixtures/pass/eval-skill/trial-1/result.json

@@ -1,9 +1,9 @@
 {
   "trial_id": 1,
   "status": "passed",
-  "command_count": 2,
+  "command_count": 1,
   "input_tokens": 6,
-  "output_tokens": 1778,
+  "output_tokens": 35,
   "check_results": [
     {
       "check_name": "skill_invoked",
@@ -19,4 +19,4 @@
     }
   ],
   "error_message": null
-}
+}