zensical-skill

zensical-skill is a focused Agent Skill for inspecting, lightly editing, reviewing, and validating Zensical sites and their source Markdown. It helps an agent preserve a repository's conventions while working with target-guided article revisions, Zensical components, navigation, media assets, and presentation customization.

This is a usable, actively developed skill for its documented, evidence-backed maintenance scope—not a complete Zensical automation suite.

It can evolve into a broader methodology or automation capability only under the capability-admission rule.

When a user explores an addition, the skill should turn that documentation check into a short, relevant set of Zensical options with fit, trade-offs, and validation needs—not a generic feature catalog or an unapproved change.

Quick start

Copy the complete zensical/ directory; its references are part of the runtime payload. The following project-scoped paths have file-availability smoke evidence, but they do not imply long-running host reload behavior.

Host	Project-scoped location	Setup
Codex	.agents/skills/zensical/	mkdir -p .agents/skills && cp -R zensical .agents/skills/
OpenCode	.opencode/skills/zensical/	mkdir -p .opencode/skills && cp -R zensical .opencode/skills/
Hermes	configured skills.external_dirs directory	Add the repository's zensical/ directory to external_dirs; do not copy it into a live global skill directory unless that is intended.

Install the zensical payload for Codex:

npx skills add CodeSigils/zensical-skill \
  --skill zensical --agent codex --yes

Review the payload before installing it.

The CLI uses symlinks by default. Use --copy only where independent files are required; a copied installation needs its own refresh after the source changes.

For live development, agents that support external skill directories can point directly at the repository's zensical/ directory. The security policy and release checklist are maintainer records, not guarantees that every target site is safe.

Refreshing an installed copy

The Agent Skills format has no update channel of its own. The Skills CLI can compare eligible recorded installs with their source without modifying them:

npx skills check

check exits with status 1 when an update is available. Refresh only after reviewing that result:

npx skills update zensical     # or: npx skills upgrade zensical

The CLI changes independently of this skill, so consult its current documentation before relying on a command or flag. check and update use a recorded content hash to detect source changes. A manual cp -R installation has no recorded source, so copy the current payload again when it needs a refresh.

Maintainers refresh the active copies they control after changing the payload and say which files changed. Other users can run skills check when their installation has recorded source metadata.

Current scope

The skill currently routes these tasks:

• inspect an existing Zensical repository and identify its conventions;
• make an explicitly authorized light Markdown edit or place a new article in the best-fitting existing category;
• for an explicitly requested new article or substantial draft, use a compact, target-guidance-first handoff to settle reader question, supportable claim, evidence boundary, and proportional shape before the prose grows;
• review publication-facing structure: navigation, links, front matter, headings, admonitions, tabs, and images or embeds, including proportionate HTML-media semantics, performance, and new-tab link policy;
• provide an optional, target-guidance-first content review when explicitly requested, without imposing a house style or article formula;
• review responsive CSS, theme overrides, and landing-page conventions;
• review accessibility concerns across content, media, components, and themes;
• use a browser for a representative rendered-page check when it is available and the requested presentation scope warrants it;
• sanitize user-supplied usernames, hostnames, local paths, network addresses, account identifiers, and private URLs in publishable examples unless the maintainer explicitly approves their disclosure;
• run a bounded tracked-file hygiene preflight before authorized commits, publishing, or deployment;
• review generated sitemaps and canonical URLs during an explicit release-output review, without claiming indexing or deployment success;
• enable and verify RSS and JSON feeds on a target running a Zensical version that provides them natively, including the discovery link a feed needs to be findable and the Git history its item dates come from;
• upgrade a site to a newer Zensical version with the migration checklist: release notes first, pin and lock, extension-table reconciliation, and a rendered-output diff, with the release channel rechecked in the source registry;
• validate a build and, where feasible, affected rendered output; and
• identify a focused, validated pending diff as ready to commit and offer that next step, without treating review or validation as Git authorization; and
• report deployment boundaries and configuration/documentation drift.

How to use it

Load zensical for a concrete task in an existing Zensical repository. The runtime router selects focused references progressively.

Request	Routed workflow
“Orient me in this Zensical site”	Site inspection
“Make this small Markdown, tab, or link edit”	Authorized light edit and content components
“Check article structure, navigation, or embed”	Media and component review
“Review this article draft”	Optional target-guidance-first content review
“Check accessibility or responsive presentation”	Accessibility and customization review
“Add an RSS or JSON feed to my site”	Feed setup and discovery-link check
“Upgrade Zensical to a newer version”	Migration checklist and evidence refresh
“Build and validate this change”	Build and rendered-output validation
“Why did this Zensical build fail?”	Narrow failure diagnosis

What it does not handle

The skill can offer optional, target-guidance-first article suggestions, but it does not define a house voice, mandatory article formula, SEO strategy, or full theme-authoring workflow. It also does not autonomously publish or deploy, claim comprehensive WCAG certification, or cover every Zensical feature. Those remain target-specific editorial, presentation, or release capabilities.

Skill Payload — What Ships to the User

Only the zensical/ directory is the portable Agent Skill payload. It contains the router, on-demand references, client metadata, and two bounded checks: a tracked-file hygiene preflight and a conventional deployment-instruction contract check.

zensical/
├── SKILL.md                         # scope, routing, and safety boundaries
├── agents/openai.yaml               # optional Codex display metadata
├── references/
│   ├── accessibility.md             # semantic and rendered a11y checks
│   ├── article-review.md             # optional portable content review
│   ├── content-components.md        # admonitions, tabs, links, navigation
│   ├── customization.md             # CSS, themes, templates, landing pages
│   ├── light-edit.md                # authorized minimal Markdown edits
│   ├── media.md                     # media, embeds, assets, base paths
│   ├── migration.md                 # version upgrades and rendered-output diffs
│   ├── rss.md                       # native RSS and JSON feeds
│   ├── site-inspection.md           # repository orientation and preflight
│   ├── source-registry.md           # version-sensitive primary sources
│   └── validation.md                # build and rendered-output checks
└── scripts/
    ├── check_instruction_contract.py # deployment-instruction drift check
    └── check_site_hygiene.sh         # no-secret-output tracked-file preflight

What users receive:

• agentskills.io name and description frontmatter for zensical;
• repository-agnostic Zensical maintenance and review instructions;
• references loaded progressively for the requested workflow;
• a bounded, read-only-by-default hygiene preflight for authorized publication work.

What does not ship in the payload:

• site-specific editorial conventions;
• blog-specific content types, tone, or terminology;
• test fixtures, the locked scenario environment, or generated site output;
• maintainer planning, research, release, and session documentation; or
• host-specific copies and project configuration.

Copy the complete zensical/ directory to preserve reference discovery. Everything outside it is repository-only development or acceptance evidence.

Repository map

zensical/
├── SKILL.md                 # portable runtime payload
├── agents/openai.yaml       # Codex metadata
├── scripts/                 # bounded runtime checks
└── references/              # loaded only when a workflow needs detail
docs/
├── vision.md                        # purpose, boundaries, and quality criteria
├── roadmap.md                       # evidence-gated implementation plan
├── research/
│   ├── current-state.md             # what the project currently knows, with check dates
│   ├── index.md                     # append-only dated field record
│   ├── editorial-voice.md           # human editorial voice and AI-tell research
│   ├── skill-structure-conventions.md # agentskills/skills.sh packaging contract
│   └── skill-sync-and-cross-agent-distribution.md # install, refresh, and versioning research
├── scenarios.md                     # bounded real-site acceptance procedures
├── release-checklist.md             # release gate and recorded evidence
├── reports/                         # dated governance audits and implementation records
└── README.md                        # maintainer reading matrix
tests/fixtures/                      # site-only deterministic scenario inputs
tests/scenario-env/                  # locked Zensical test environment
scripts/
├── check_commit_messages.py         # commit subject and what:/why: policy
├── check_readme_inventory.py        # README file trees against the repository
└── run_scenarios.sh                 # isolated fixture runner
AGENTS.md                            # maintainer change contract
ruff.toml                            # narrow lint scope for the local checks
LICENSE                              # MIT license
SECURITY.md                          # reporting and payload boundaries

The runtime payload is under zensical/. The docs/ directory is maintainer context and is not loaded as part of the skill.

Current state

The dated current-state record is the authoritative evidence ledger for these status claims.

Surface	Status	Evidence boundary
Codex	Project-scoped smoke passed	SKILL.md and required references resolve under .agents/skills/zensical/
OpenCode	Project-scoped smoke passed	SKILL.md and required references resolve under .opencode/skills/zensical/
Hermes	Project-scoped smoke passed	Payload and required references resolve through the documented external-directory layout
Skills CLI install	Historical: passed at d7ef1e0	Version 1.5.25 copied all 13 payload files into disposable .agents/skills/zensical/ on 2026-09-10; the payload has since grown to 15 files
Skills.sh search	Indexed on 2026-09-10	Public API searches returned codesigils/zensical-skill/zensical
Public release	Not claimed	Marketplace indexing is not a release, support, or compatibility guarantee

• The payload passes the local Agent Skill structural validator and the pinned official skills-ref validator at agentskills commit 69ef37e9424c0a7ea9dd2293b559e43ec8176379.
• The repository is licensed under MIT and has a security reporting policy.
• The initial workflows are acceptance-tested against the Code Sigils Zensical blog; its editorial conventions are not part of the portable payload.
• The initial fixtures run through a lockfile-pinned Zensical 0.1.1 scenario environment (pin in tests/scenario-env/pyproject.toml).
• The scenario suite covers tab rendering, reproducible accessibility findings, code-line-anchor repair, non-root deployment links, and sitemap/canonical assertions; it is not a complete site or WCAG conformance suite.
• The runner distinguishes dependency/network blocks from fixture failures and accepts an installed matching binary through ZENSICAL_BIN.
• The runtime payload includes a no-secret-output hygiene preflight for common tracked credential and private-key indicators; it is not a full secret scan.
• Direct Skills CLI installation, project-scoped host-loader smoke checks for Codex, OpenCode, and Hermes, and Skills.sh search indexing have been verified; public release remains unclaimed.

These are development facts, not guarantees about every Zensical repository. Version-sensitive behavior must be checked against the current documentation and the target site's configuration.

Security model

The skill works only in the repository and scope the user authorizes. Its tracked-file hygiene preflight reports candidate paths and finding types, never secret values; it is not a full secret scan. Builds, documentation lookups, and external-link checks can require network access. Commits, publishing, deployment, credential rotation, and history rewriting require separate, explicit authorization. See SECURITY.md for disclosure and payload boundaries.

Development workflow

1. Read AGENTS.md and the relevant documents in docs/README.md.
2. Make a narrow change to the runtime payload or its supporting evidence.
3. Run the Codex skill-creator validator, the Agent Skills validator, and inspect the diff for duplicated or drifting guidance.
4. Record changed sources, uncertainty, and the validation performed.

Do not install, execute, publish, or deploy third-party material as part of discovery or review without explicit authorization.

Validate

Run the focused checks from the repository root:

python3 "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-creator/scripts/quick_validate.py" zensical
uvx --from git+https://github.com/agentskills/agentskills.git@69ef37e9424c0a7ea9dd2293b559e43ec8176379#subdirectory=skills-ref skills-ref validate zensical
bash scripts/run_scenarios.sh
bash zensical/scripts/check_site_hygiene.sh .
python3 zensical/scripts/check_instruction_contract.py /path/to/site
python3 scripts/check_readme_inventory.py --self-test
python3 scripts/check_readme_inventory.py
git diff --check

The validator checks payload structure, the scenario runner checks the pinned Zensical fixtures, and the hygiene preflight checks tracked files for common sensitive-material candidates. The instruction-contract check compares a conventional documented deployment section with its workflow. None proves deployment success, player behavior, remote-link availability, or full accessibility conformance.

Three CI jobs run on every push and pull request against main (.github/workflows/validate.yml): the commit-policy check, the scenario suite, and a third job running five local checks (check_instruction_contract.py --self-test, check_site_hygiene.sh, check_readme_inventory.py --self-test, check_readme_inventory.py, which fails when the README's file trees stop matching the repository, and uvx ruff@0.15.16 check . against the narrow rule set in ruff.toml; that workflow is the authoritative command definition). The commit-policy check exempts commits attributed to Dependabot's bot identity and reports them as skipped, because bot bodies cannot carry what: and why: fields; those diffs are reviewed directly instead. The exemption follows the commit's author, so it applies the same way on a push, a pull request, and a local range review. Dependabot watches the pinned workflow actions. The gate runs checks, not a deployment.

Primary references

• Zensical documentation
• Admonitions
• Content tabs
• Agent Skills specification
• Zola skill architectural reference

The source registry in zensical/references/source-registry.md records what each source supports and when it was checked.

Repeated semantic values are review signals for possible duplication or drift, not automatic extraction targets. Centralize a value only when its copies should change together and the trade-off improves clarity.

Commit policy is checked with python3 scripts/check_commit_messages.py; each commit must explain what: and why: in its body. Release-facing history lives in those commit bodies; there is no changelog file, because a running list duplicated the commit log, drifted from it, and never changed a decision.

Public release, support, and compatibility guarantees are not claimed yet. Skills.sh indexing is discoverability evidence, not a release. The verification steps are documented in docs/release-checklist.md.

Generic-site expansion

Code Sigils is the current product-facing acceptance environment, not a template that other sites must follow. The next expansion is to prove the existing-site workflow on two or three materially different Zensical repositories. Candidate slices are generic content-model/authoring work, bounded MiniJinja theme overrides, explicit release review, and a multi-deployment language-selector workflow. Each must satisfy the capability-admission rule before it becomes part of the portable payload.

Do not promise Zola-equivalent multilingual content routing: Zensical currently supports one canonical language per generated project and can link alternate-language deployments. Feeds are an admitted bounded capability, because Zensical has provided them natively since 0.0.65; check the target's version before writing feed configuration. Generated sitemap behavior can be reviewed when site_url is configured; it is an admitted bounded release-output review, not deployment proof. See the roadmap and source registry for the capability boundaries.

Roadmap

See docs/roadmap.md. The existing-site review, light- edit, and native-feed workflows are substantially proven against the Code Sigils blog, with a small repeatable scenario suite for the observed failures. The completed three-task field run did not justify another helper or fixture. The next milestone requires either a repeated, testable maintenance gap or an explicit reviewed release candidate; new scripts, fixtures, integrations, and CI should earn their place through observed need.

Status and feedback

This repository is maintained as a small, evidence-driven experiment. Please report unclear routing, stale source assumptions, or a workflow that changes the requested scope. A useful issue includes the target repository shape, the authorized operation, the observed output, and the source/version involved.