Agent Skills (skills)
Why it exists
A skill is context for an agent, not configuration for a program. A SKILL.md explains a subsystem's procedure, boundaries and commands; when the agent opens the corresponding directory and reads it, it knows how to work without the user repeating the briefing every time.
Once discovered, a skill enters the context, so it has a cost. Which scope it sits in decides who sees it and how many tokens they pay for it. The principle is therefore not "install whatever will install" but install it at the layer that should see it.
Responsibilities
linxira-skills owns:
- The
linxira-skillsexecutable:init,status,update,uninstall. - Profiles and payload: materialising the selected profile as a three-level routing tree under
.agents/skills/, plus.linxira/manifest.jsonand theAGENTS.mdmarker block. - Each profile's skill list, sources and licence records (
THIRD_PARTY_NOTICES.md,docs/SOURCES.md).
It does not own:
- How a runtime discovers skills; that is Zeta's provider priority and its switches.
- Installing the system skill directory; that is the distribution package's PKGBUILD.
- Materialising workspace skills; each component does that for itself (currently Crash Watch).
- Producing agent sessions or executing skill content.
Implemented scopes
| Scope | Path | Installed by | Visible to |
|---|---|---|---|
| System | /usr/share/linxira/agent/skills/<name>/SKILL.md |
distribution package (PKGBUILD) | the whole system; package-owned, read-only, upgraded with the package |
| Workspace | <ws>/.agents/skills/<name>/SKILL.md |
materialised by a component when it creates the workspace | only inside that workspace (the agent's --cwd); .agents/skills/ is gitignored |
| Project | <repo>/.agents/skills/ |
linxira-skills init |
only that repository; also generates .linxira/manifest.json and the AGENTS.md marker block |
linxira-skills has no user-scope install path. ~/.agents/skills/ is a user-level directory that Zeta's agents provider scans, but only when enableAgentsUser is switched on there; linxira-skills writes nothing to it, and packages must not either. A skill reused across projects can today only be placed there by the user, who carries the context cost.
What actually exists today is deliberately little:
- The system scope has a single skill:
linxira-config, installed by thelinxira-config-hubPKGBUILD. Its companion manifest/usr/share/linxira/agent/capabilities.jsonrecords what it can do and which commands need root. - The workspace scope also has a single one:
diagnose-crash, materialised by Crash Watch. - The project scope holds whichever profile the user installs; the system pre-installs nothing there.
Layout is one layer, not a tree
Zeta's provider discovery only looks at <skills-root>/<name>/SKILL.md — one layer. A nested <skills-root>/<group>/<name>/SKILL.md is not loaded by default. linxira-skills therefore keeps its three-level routing tree under .agents/skills/ and uses the generated AGENTS.md marker block plus relative INDEX.md links to walk an agent from router to index to leaf, instead of relying on recursive scanning.
Who may write where
| Writer | May write | Must not write |
|---|---|---|
| Distribution package (PKGBUILD) | the system skill directory and capabilities.json |
~/.zeta/agent/skills, ~/.agents/skills, any user directory |
| Components (e.g. Crash Watch) | only its own single skill, into its own workspace | other subsystems' skills, the system skill directory |
linxira-skills CLI |
the project scope of the target Git repository (.agents/skills/, .linxira/manifest.json, the AGENTS.md marker block) |
the system skill directory, ~/.agents/skills, ~/.zeta/agent/skills |
| The user | any scope, though the project scope should be installed through the CLI so it stays traceable and uninstallable | — |
Packages must not write the user scope
~/.agents/skills belongs to the user, not to a package. A package writing there makes one skill appear in every one of the user's projects — a skill the user never chose and cannot cleanly remove with linxira-skills uninstall. ~/.zeta/agent/skills is the same story: it is Zeta's own user data, and packages must not write to it.
Why the project scope is the default
A user-level skill is visible to every project: once its switch is on, the agent loads it in any repository, even when the task does not need it. That is context cost, and it is also where name collisions come from — when the same skill name exists in several sources only the highest-priority copy wins, which is not intuitive to debug.
The project scope avoids both: the skill travels with the repository that needs it and disappears when you switch projects, and uninstall can clean up the managed directories. The home directory is also not a repository, so it should not be filled with an AGENTS.md marker block or .gitignore entries — one reason the CLI only works inside a Git repository.
Discovery order
At startup Zeta loads skills in provider priority order, first come, first served for a given name:
- native
.zetaskills (user and project level, priority 100); zeta-plugins(90), thenclaude(80), then the priority-70 group:claude-plugins,agents,codex;opencode(55) andgithub(30);- finally Zeta's auto-learned (managed) skills (5), which always yield to an authored skill of the same name.
The outcome: a native .zeta version beats a same-named .agents version, and .agents/ is exactly where linxira-skills and the components materialise skills. The system skill directory is not on the default scan path; it is referenced explicitly through the skill field of capabilities.json, so an agent that reads the manifest can find it.
The agents provider has its own user-level and project-level switches (enableAgentsUser, enableAgentsProject); disabling Claude, Codex or other providers does not turn it off.
Commands
# project scope (the only supported scope): run inside the target Git repository
npx @linxiraos/linxira-skills init
npx @linxiraos/linxira-skills init --profile core
npx @linxiraos/linxira-skills init --layout namespaced # default; routers land in .agents/skills/linxira-<root>/
npx @linxiraos/linxira-skills init --layout flat # routers land in .agents/skills/<root>/
# inspect, update, uninstall: follow the profile and layout recorded in the manifest
npx @linxiraos/linxira-skills status
npx @linxiraos/linxira-skills update [--force]
npx @linxiraos/linxira-skills uninstall [--force]
init, update and uninstall all support --dry-run. update only touches manifest-owned entries that are unmodified and asks for --force before replacing user edits. status / update / uninstall read the .linxira/manifest.json written at install time, so changing --layout leaves no old directory to clean up by hand.
Profiles:
core(default): 10 first-party software, integrity, Linux, transfer and compute skills.bioinformatics-core:coreplus 10 first-party bioinformatics and bulk RNA-seq skills.biology-research-core: the previous level plus 19 biological discovery, experimental design, wet-lab governance and academic-delivery skills.science-research-core: extends that with chemistry, physics, crop/plant, ecology, animal physiology, biochemistry and medical/translational study design.research-communication-core:coreplus 44 manuscript, citation, formatting, figure, document, LaTeX, presentation and Chinese research-document skills (including vendored Apache-2.0 / MIT adaptations; seeTHIRD_PARTY_NOTICES.md).
Not yet published to npm
The installation architecture document states that the package has not been published to npm. The npx forms above assume a published package; until then only a locally built package can be used, and @linxiraos/linxira-skills must not be assumed downloadable.
Separation rule
System-management skills (such as linxira-config) stay in the system directory and are not copied into workspaces.
A workspace materialises only the single skill its own subsystem needs. Since crash-watch 0.1.4, Crash Watch no longer copies linxira-config into the debug workspace: two copies of one skill drift apart over time, and the system skill is upgraded with its package while a workspace copy is not. To tell an agent about system-configuration capability, read the system skill instead of keeping a stale copy in every workspace.
Privileges
linxira-skillsneeds no root and calls nosudo; it writes only managed files inside the target Git repository.- System skills are installed by the package manager as root, as part of the ordinary system upgrade path.
- Components materialise workspace skills with the user's own permissions and never elevate.
Known limitations
initmust run inside a Git repository (or one of its subdirectories); any other directory fails with an error.- Running
initagain in an initialised repository fails and asks forupdateoruninstallinstead. linxira-skillshas no user-scope install path; whether~/.agents/skillsloads depends on Zeta'senableAgentsUserswitch, so placing skills there by hand does not guarantee they take effect.- The system skill directory is not on Zeta's default scan path and is only reachable through the
skillfield ofcapabilities.json. - Skill discovery sees one directory layer; nested directories rely on the router and
AGENTS.mdguidance rather than automatic scanning. - The CLI does not run
git add, modify source submodules, fetch upstream, or make network requests. - Only the five listed profiles exist; third-party material that has not passed review is not part of the installable payload.
Further design
- Installer and layout:
docs/INSTALLATION_ARCHITECTURE.mdanddocs/SKILL_LOADING_POLICY.mdin thelinxira-skillsrepository. - Workspace materialisation:
src/linxira_crash_watch/workspace.pyin thelinxira-crash-watchrepository. - System skill and manifest: the
agent/directory in thelinxira-config-hubrepository.