Agent Skills: Discovery, Invocation, Routing

Write, install, discover, invoke and route SKILL.md packages. Validators, catalogs, router and installer projects.

Skill lifecycle#

Command	What it does
`npx skills add rohitg00/ai-engineering-from-scratch --skill skill-contract-reviewer --full-depth`	Installs the nested bundle with references, script and asset
`/skill-contract-reviewer <request>`	Explicit invocation in a host with `/skill-name` syntax
`/skills`	Picks a skill by name in the Codex interface
`python3 <SKILL_ROOT>/scripts/check_skill.py <TARGET_ROOT>/my-first-skill`	Runs the bundled validator. Show argv, cwd and exit code
`npx skills remove skill-contract-reviewer`	Removes the bundle. Use the same host and scope
`python3 scripts/install_skills.py /tmp/aiefs-skills --phase 13 --type skill`	Copies Phase 13 bundles and writes `manifest.json`
`python3 -m unittest discover -s code/tests -v`	Runs a lesson test suite

Task	Code
Create a learner workspace	`python3 scripts/project_test.py skill-router --init learning-artifacts/skill-router`
Grade one stage	`python3 scripts/project_test.py skill-router --stage 1 --path learning-artifacts/skill-router`
Route the sample request	`node learning-artifacts/skill-router/cli.ts projects/skill-router/examples/skills projects/skill-router/examples/request.json`
Dry run an install	`node learning-artifacts/skill-installer/cli.ts inspect projects/skill-installer/examples/orchard-release.json codex`
Install for real	`cli.ts install bundle.json agent root expected-source-digest`
Build the validator	`rustc --edition=2021 learning-artifacts/skill-validator/cli.rs -o learning-artifacts/skill-validator/validator`
Validate and load in 2000 characters	`validator projects/skill-validator/examples/orchard-release 2000 --activate references/restore.md`
Check a reference solution	`python3 scripts/project_test.py skill-validator --all --solution --strict`

Skill or hook?: A hook when every event must run. A skill for model judgment.
Skill or MCP tool?: A tool for a typed external capability. A skill for procedure.
Does an explicit name bypass policy?: No. It still passes every gate.
Does the router run the skill?: No. It emits plans and explanations only.
Does a successful install prove activation?: No. The agent must discover it.

report = validate_skill_text(text, directory_name, allowed_runtime_extensions=())

select_primitives(task)code, skill, hook, subagent, tool

candidates = (*discover_scope(Scope("project", project_root)),

*discover_scope(Scope("user", user_root)))immediate children only

catalog = build_catalog(candidates, precedence=("project", "user"),

budget=CatalogBudget(max_entries=10, max_catalog_chars=2_000))

body = load_skill_body(selected, candidates)level 2

reference = load_reference(selected, "references/format.md")level 3

validate_reference(skill_directory, reference)blocks traversal and escape

route_request(skills, request, adapter)eligibility before ranking

build_invocation_matrix(policy)human by model view

const skills = await loadCatalog(root);SKILL.md plus routing.json

rank(skills, query, files);keyword 2, path 3

plan(skills, selected, allowed);dependencies first

route(skills, query, files, allowed, margin = 1);ready, no-match, ambiguous, blocked

safePath(name);rejects .., absolute, C:, backslash

const files = translate(bundle, agent);new quoted header, same body

const expected = digest(bundle.files);SHA-256 of sorted pairs

await install(root, bundle, agent, expectedDigest);staged rename with backup

Factor	Shared	Human-only	Model-only	Disabled
Human can invoke	Yes	Yes	No	No
Model can invoke	Yes	No	Yes	No
One host field	Default	`disable-model-invocation: true`	`user-invocable: false`	Not defined
Example	Test planning	Publish preparation	Internal style guide	Deprecated package

Setting	Default	Note
`name` length	64	Lowercase words joined by hyphens
`description` length	1024	Says what and when
`compatibility` length	500	Optional core field
`max_description_chars`	240	`CatalogBudget` per entry
`max_catalog_chars`	8_000	`CatalogBudget` total
`max_chars`	12_000	Body and reference loads
`model_threshold`	0.2	Implicit selection floor
Router `margin`	1	Smaller score gap is ambiguous

Symptom	Cause	Fix
`no-match`	No keyword or path scored	Add `keywords` or `paths` in routing.json
`ambiguous`	Top two scores differ by less than `margin`	Make the trigger boundaries distinct
`blocked` with `permission denied`	Skill or a dependency needs more permissions	Allow it or pick another route
`unsupported YAML syntax`	Tag, alias, multiline or flow value	Use a plain or double-quoted scalar
`integrity mismatch`	Bundle digest differs from the expected digest	Run `inspect`, compare `source_digest`
`modified installation`	A tracked file changed since install	Move the edit into the source bundle
Skill unavailable after install	Host did not rescan its catalog	Start a new session or rescan, then retry
Model never picks the skill	Vague description or budget cut it	Check the discovery log and catalog size