ast
Markdown AST operations for Jerry documents. Provides structured parse, query, modify, validate, and render operations on Jerry markdown files via the jerry ast CLI.
Best use case
ast is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Markdown AST operations for Jerry documents. Provides structured parse, query, modify, validate, and render operations on Jerry markdown files via the jerry ast CLI.
Teams using ast should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/ast/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How ast Compares
| Feature / Agent | ast | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Markdown AST operations for Jerry documents. Provides structured parse, query, modify, validate, and render operations on Jerry markdown files via the jerry ast CLI.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# AST Skill
> **Version:** 1.1.0
> **Framework:** Jerry Framework v0.9.0
> **Layer:** CLI adapter (single entry point to domain layer)
---
## Document Sections
| Section | Purpose |
|---------|---------|
| [Overview](#overview) | What this skill does and why |
| [When to Use This Skill](#when-to-use-this-skill) | Triggers and use cases |
| [Operations Reference](#operations-reference) | All available CLI commands |
| [Quick Reference](#quick-reference) | Copy-paste examples for common tasks |
| [Routing Disambiguation](#routing-disambiguation) | When this skill is the wrong choice |
| [Constitutional Compliance](#constitutional-compliance) | Principle mapping with consequences |
| [Architecture Notes](#architecture-notes) | Layer compliance and design |
---
## Overview
The AST skill provides structured markdown operations for Claude agents working
within the Jerry Framework. All operations are exposed via the `jerry ast` CLI
namespace, which is the single adapter between agents and the
`src.domain.markdown_ast` domain layer.
### Core Capabilities
- **Parse:** Tokenize a markdown file and return AST structure as JSON.
- **Frontmatter:** Extract `> **Key:** Value` fields as a JSON object.
- **Modify:** Change a frontmatter field value and write back to disk.
- **Validate:** Check nav table compliance (H-23/H-24) and entity schema validation.
- **Render:** Normalize markdown via mdformat.
- **Reinject:** Extract all L2-REINJECT directives as a JSON list.
- **Query:** Query AST nodes by type.
---
## When to Use This Skill
Invoke `/ast` when you need to:
- Read frontmatter fields from a Jerry entity file (story, task, enabler, bug).
- Modify a single frontmatter field without disturbing the rest of the file.
- Validate that a markdown file complies with H-23 (nav table required) and H-24 (anchor links).
- Extract L2-REINJECT directives to inspect or audit the re-injection payload.
- Normalize markdown formatting before writing or diffing files.
NEVER invoke this skill when:
- Reading raw file content without structural parsing -- Consequence: AST parsing overhead applied to simple file reads wastes CLI invocation cost; JSON output format adds unnecessary complexity for content retrieval; use Read tool directly
- Writing arbitrary content to files -- Consequence: AST modify is scoped to frontmatter field updates only; arbitrary content writes fail or produce incorrect results; use Write/Edit tools directly
See [Routing Disambiguation](#routing-disambiguation) for full exclusion conditions with consequences.
---
## Operations Reference
All operations are invoked via `jerry ast <command>`. In agent context, use the
`--directory` prefix:
```bash
uv run --directory ${CLAUDE_PLUGIN_ROOT} jerry ast <command> [args]
```
### jerry ast parse
```bash
jerry ast parse <file>
```
Parse a markdown file and output the full AST as JSON (tokens + tree).
**Exit codes:** 0 success, 2 file error.
---
### jerry ast frontmatter
```bash
jerry ast frontmatter <file>
```
Extract all blockquote frontmatter fields as a JSON object.
**Output:** `{"Type": "story", "Status": "pending", ...}` or `{}` if no frontmatter.
**Exit codes:** 0 success, 2 file error.
---
### jerry ast modify
```bash
jerry ast modify <file> --key <KEY> --value <VALUE>
```
Modify one frontmatter field and write the updated content back to disk.
**Output:** `{"file": "...", "key": "...", "value": "...", "status": "modified"}`
**Exit codes:** 0 success, 1 key not found, 2 file error.
---
### jerry ast validate
```bash
jerry ast validate <file> [--schema <type>] [--nav]
```
Validate file structure against H-23/H-24 nav table rules and optionally
against an entity schema.
**Without `--schema`:** Returns JSON with nav table validation results.
**With `--schema <type>`:** Validates against entity schema (epic, feature,
story, enabler, task, bug). Returns JSON with both nav table and schema results.
**With `--nav`:** Includes detailed nav table entries in the output
(section_name, anchor, description, line_number).
**Output JSON keys:**
| Key | Type | Description |
|-----|------|-------------|
| `is_valid` | bool | True only when nav and schema are both valid |
| `nav_table_valid` | bool | True if nav table exists and covers all ## headings |
| `missing_nav_entries` | list | Heading texts absent from nav table |
| `orphaned_nav_entries` | list | Nav entries with no matching heading |
| `schema_valid` | bool | True when schema passes or no schema provided |
| `schema_violations` | list | Violation dicts (with --schema only) |
| `nav_entries` | list | Detailed entries (with --nav only) |
**Exit codes:** 0 success, 1 validation failure, 2 file/schema error.
---
### jerry ast render
```bash
jerry ast render <file>
```
Parse a file and output normalized (mdformat) markdown to stdout.
**Exit codes:** 0 success, 2 file error.
---
### jerry ast reinject
```bash
jerry ast reinject <file>
```
Extract all L2-REINJECT directives from a markdown file as a JSON list.
**Output:** List of dicts with rank, tokens, content, line_number.
**Exit codes:** 0 success, 2 file error.
---
### jerry ast query
```bash
jerry ast query <file> <selector>
```
Query AST nodes by type (e.g., heading, blockquote, paragraph).
**Output:** `{"selector": "...", "count": N, "nodes": [...]}`
**Exit codes:** 0 success, 2 file error.
---
## Quick Reference
### Read frontmatter from a story file
```bash
uv run jerry ast frontmatter projects/PROJ-005-markdown-ast/work/EPIC-001-markdown-ast/FEAT-001-ast-strategy/ST-005-ast-skill/ST-005-ast-skill.md
```
### Update story status
```bash
uv run jerry ast modify projects/PROJ-005-markdown-ast/work/EPIC-001-markdown-ast/FEAT-001-ast-strategy/ST-005-ast-skill/ST-005-ast-skill.md --key Status --value in-progress
```
### Validate a rule file for H-23/H-24 compliance
```bash
uv run jerry ast validate --nav .context/rules/quality-enforcement.md
```
### Extract L2-REINJECT directives from a rule file
```bash
uv run jerry ast reinject .context/rules/quality-enforcement.md
```
### Parse a file and inspect its structure
```bash
uv run jerry ast parse .context/rules/quality-enforcement.md
```
### Validate an entity file against a schema
```bash
uv run jerry ast validate --schema story projects/PROJ-005-markdown-ast/work/EPIC-001-markdown-ast/FEAT-001-ast-strategy/ST-005-ast-skill/ST-005-ast-skill.md
```
---
## Routing Disambiguation
> When this skill is the wrong choice and what happens if misrouted.
| Condition | Use Instead | Consequence of Misrouting |
|-----------|-------------|--------------------------|
| Reading raw file content without structural parsing | Read tool directly | AST parsing overhead applied to simple file reads wastes CLI invocation cost; JSON output format adds unnecessary complexity for content retrieval |
| Writing arbitrary content to files | Write/Edit tools directly | AST modify is scoped to frontmatter field updates only; arbitrary content writes require direct file tools |
| General text processing on non-entity markdown | Read/Write/Edit tools directly | AST validation schema applied to non-entity markdown produces false-positive structural errors; entity schema enforcement rejects valid non-worktracker files |
| Research, analysis, or investigation tasks | `/problem-solving` | AST provides structural parsing only; no analytical methodology, no research capability, no root cause investigation |
| Validating content quality or adversarial review | `/adversary` | AST validates structural compliance (H-23/H-24 nav tables, entity schemas), not content quality; no S-014 scoring rubric |
---
## Constitutional Compliance
All operations adhere to the **Jerry Constitution v1.0**:
| Principle | Requirement | Consequence of Violation |
|-----------|-------------|-------------------------|
| P-003 | NEVER spawn recursive subagents -- max 1 level | Agent hierarchy violation; uncontrolled token consumption |
| P-020 | NEVER override user intent -- ask before destructive ops | Unauthorized action; trust erosion |
| P-022 | NEVER deceive about actions, capabilities, or confidence | Governance undermined; quality assessment invalidated |
---
## Architecture Notes
### Single CLI Adapter
The `jerry ast` CLI namespace (`src/interface/cli/ast_commands.py`) is the
single adapter between agents and the domain layer. There is no separate
skill script — the CLI is the adapter:
```
jerry ast <command> <- CLI (interface layer)
-> src.domain.markdown_ast <- domain layer
```
The domain layer (`src/domain/markdown_ast/`) does NOT import back into the
interface layer (H-07 enforced by architecture boundary tests).
### References
| Topic | Location |
|-------|----------|
| Domain layer exports | `src/domain/markdown_ast/__init__.py` |
| CLI commands | `src/interface/cli/ast_commands.py` |
| CLI parser | `src/interface/cli/parser.py` |
| Unit tests | `tests/unit/interface/cli/test_ast_commands.py` |
| Integration tests | `tests/integration/cli/test_ast_subprocess.py` |
| H-23/H-24 rules | `.context/rules/markdown-navigation-standards.md` |
| Quality enforcement | `.context/rules/quality-enforcement.md` |Related Skills
ux-lean-ux
Lean UX hypothesis-driven design sub-skill for the /user-experience parent skill. Facilitates Build-Measure-Learn cycles using Jeff Gothelf and Josh Seiden's Lean UX methodology (3rd ed. 2021). Produces hypothesis backlogs, assumption maps, MVP experiment designs, and validated learning logs. Invoke when teams need hypothesis-driven iteration, assumption mapping, experiment design, or validated learning documentation. Invoked by ux-orchestrator during Wave 2 lifecycle-stage routing or when user intent is "testing hypotheses" during the "During design" stage. Triggers: lean UX, hypothesis, assumption mapping, build-measure-learn, MVP experiment, validated learning, experiment design, hypothesis backlog.
ux-kano-model
Kano model feature classification and prioritization sub-skill for the /user-experience parent skill. Classifies product features into Must-be (M), Performance (O), Attractive (A), Indifferent (I), and Reverse (R) categories using the functional/dysfunctional questionnaire pair methodology (Kano et al., 1984). Computes Customer Satisfaction (CS) coefficients (Better/Worse) for priority matrix visualization. Produces feature classification reports, priority matrices, and survey design templates. Sample size awareness: 5-8 respondents yields directional classification only (MEDIUM confidence); 20+ respondents required for statistical classification (Berger et al., 1993). Invoked by ux-orchestrator during Wave 4 lifecycle-stage routing or when user intent is "Need to prioritize features" at any lifecycle stage. Triggers: Kano, must-be, attractive, one-dimensional, performance feature, satisfaction, feature classification, delighter, feature prioritization, CS coefficient.
ux-jtbd
Jobs-to-Be-Done research and analysis sub-skill for the /user-experience parent skill. Conducts JTBD job statement synthesis, switch interview analysis (Moesta/Spiek four forces), outcome-driven innovation (Ulwick ODI), and job mapping for tiny teams (1-5 people). Invoked by ux-orchestrator when users need to understand user motivations, map jobs to be done, identify switch triggers, or produce job maps with outcome expectations. Sub-skill of /user-experience; routed via ux-orchestrator lifecycle-stage triage. Triggers: JTBD, jobs to be done, switch interview, job mapping, user motivation, outcome, hiring criteria, user jobs, switch forces.
ux-inclusive-design
Inclusive design and WCAG 2.2 accessibility evaluation sub-skill for the /user-experience parent skill. Performs WCAG 2.2 compliance audits across Perceivable, Operable, Understandable, and Robust principles (conformance levels A, AA, AAA) and applies Microsoft Inclusive Design methodology including Persona Spectrum analysis (permanent, temporary, situational disabilities). Produces accessibility audit reports and persona spectrum analyses. Invoke when teams need accessibility compliance evaluation, WCAG conformance auditing, screen reader compatibility assessment, color contrast analysis, cognitive load evaluation, or inclusive design review. Invoked by ux-orchestrator during Wave 3 lifecycle-stage routing or when user intent is "Check accessibility" at any lifecycle stage. Triggers: accessibility, WCAG, ARIA, screen reader, contrast, cognitive load, inclusive, a11y, inclusive design, WCAG 2.2, persona spectrum.
ux-heuristic-eval
Nielsen heuristic evaluation sub-skill for the /user-experience parent skill. Evaluates interfaces against Nielsen's 10 usability heuristics, produces severity-rated findings on a 0-4 scale (Cosmetic to Catastrophic), and generates remediation recommendations with effort estimates. Invoke when teams need structured usability evaluation, interface review, heuristic audit, or severity-rated UX findings. Invoked by ux-orchestrator during Wave 1 lifecycle-stage routing or CRISIS mode triage. Triggers: heuristic evaluation, usability audit, Nielsen heuristics, interface review, severity rating, usability inspection, UX evaluation.
ux-heart-metrics
HEART Metrics framework sub-skill for the /user-experience parent skill. Applies Google's HEART framework (Happiness, Engagement, Adoption, Retention, Task Success) using the Goals-Signals-Metrics (GSM) process to define measurable UX metrics for products and features. Invoked by ux-orchestrator when users need to measure UX health, define UX metrics, establish measurement baselines, or produce dashboard-ready metric specifications. Sub-skill of /user-experience; routed via ux-orchestrator lifecycle-stage triage. Triggers: HEART, metrics, happiness, engagement, adoption, retention, task success, GSM, measurement, UX metrics, dashboard, goals signals metrics.
ux-design-sprint
AJ&Smart Design Sprint 2.0 facilitation sub-skill for the /user-experience parent skill. Facilitates a structured four-day rapid prototyping and validation process compressed from the Google Ventures five-day Design Sprint (Knapp, Zeratsky & Kowitz, 2016; Courtney, 2019). Produces sprint artifacts including challenge maps, solution sketches, storyboards, realistic prototypes, and structured user interview findings with synthesis confidence gates. Invoke when teams need to rapidly validate a product concept, solve a critical design challenge through structured prototyping, test ideas with real users before committing to development, or explore solution directions when they do not know what to build. Triggers: design sprint, GV sprint, rapid prototyping, sprint week, map sketch decide test, 4-day sprint, design sprint 2.0, AJ Smart sprint, validate prototype, test with users, sprint facilitation.
ux-behavior-design
Fogg Behavior Model B=MAP bottleneck diagnosis sub-skill for the /user-experience parent skill. Diagnoses why users fail to take desired actions by analyzing the three B=MAP factors (Motivation, Ability, Prompt) and identifying which factor falls below the action threshold. Produces bottleneck diagnoses, factor-level assessments, and intervention recommendations with synthesis confidence gates. Invoke when teams need to understand why users are not completing a specific action, diagnose behavioral bottlenecks, design behavior change interventions, or analyze post-launch user inaction patterns. Invoked by ux-orchestrator during Wave 4 lifecycle-stage routing or when user intent is "Users not completing action" during the "After launch" stage. Triggers: behavior design, B=MAP, Fogg model, behavior bottleneck, motivation analysis, ability analysis, prompt design, why users don't, user inaction, behavior diagnosis, tiny habits, action threshold.
ux-atomic-design
Atomic Design component taxonomy sub-skill for the /user-experience parent skill. Implements Brad Frost's 5-level component hierarchy (Atoms, Molecules, Organisms, Templates, Pages) for design system architecture. Produces component inventories, design token audits, composition rules, and Storybook coverage reports. Invoke when teams need component taxonomy construction, design system architecture, Storybook integration, design token consistency analysis, or component reuse auditing. Invoked by ux-orchestrator during Wave 3 lifecycle-stage routing or when user intent is "Building component system" during the "During design" stage. Triggers: atomic design, component taxonomy, design tokens, Storybook, atoms molecules organisms, design system, component inventory, component library.
ux-ai-first-design
AI-first interaction design sub-skill (CONDITIONAL) for the /user-experience parent skill. Provides trust-calibrated AI interaction design guidance using Yang et al.'s trust-risk and error-risk classification framework. Produces interaction pattern recommendations, trust calibration assessments, feedback loop designs, and progressive disclosure strategies for AI-powered features. CONDITIONAL: requires WSM >= 7.80 AND enabler research (FEAT-020) complete; otherwise routes to /ux-heuristic-eval with PAIR protocol. Invoke when teams need to design AI-powered interactions, calibrate user trust in AI outputs, classify AI error risks, design human-AI handoff patterns, or audit existing AI interfaces for trust and safety. Triggers: AI-first design, AI interaction, trust calibration, AI UX, conversational UX, AI interface, LLM interface, agentic UX, human-AI interaction, AI transparency, AI error handling, AI onboarding, progressive AI disclosure, trust-risk, error-risk.
user-experience
Parent orchestrator for AI-augmented UX methodology targeting tiny teams (1-5 people). Routes to 10 sub-skills by product lifecycle stage through criteria-gated waves. Invoke when team needs structured UX evaluation, user research, design systems, UX metrics, behavior diagnosis, feature prioritization, design sprints, or AI interaction design. Each sub-skill implements a proven UX framework with synthesis hypothesis confidence gates and MCP design tool integration. Triggers: UX, user experience, usability, heuristic evaluation, JTBD, lean UX, HEART metrics, atomic design, inclusive design, behavior design, Kano model, design sprint, AI-first design, UX audit, accessibility, design system, user research.
use-case
Guided use case authoring and decomposition using Cockburn's 12-step writing process and Jacobson UC 2.0 progressive narrative levels. Creates structured use case artifacts with YAML frontmatter validated against use-case-realization-v1.schema.json. Decomposes use cases into implementation-ready slices with INVEST criteria verification and produces realization interaction sequences for downstream /test-spec and /contract-design consumption. Invoke when writing, creating, authoring, elaborating, slicing, decomposing, or realizing use cases.