Agent skill

aspens Project Conventions

Orientation to the aspens codebase for agents working on the CLI itself: its Node.js stack, commands, module layout and debug settings.

MITAuto-check passedDevelopment

Install aspens Project Conventions

skills CLI

$ npx skills add aspenkit/aspens --skill base -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI

$ gh skill install aspenkit/aspens base --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy

$ git clone --depth 1 https://github.com/aspenkit/aspens.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/base .claude/skills/base && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Paste into Claude Code

Install the "base" agent skill from https://github.com/aspenkit/aspens/tree/main/.agents/skills/base into .claude/skills/base/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "base", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

$skill-installer

$skill-installer install https://github.com/aspenkit/aspens/tree/main/.agents/skills/base

Type this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.

skills CLI

$ npx skills add aspenkit/aspens --skill base -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install aspenkit/aspens base --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/aspenkit/aspens.git skills-src && mkdir -p .agents/skills && cp -r skills-src/.agents/skills/base .agents/skills/base && rm -rf skills-src

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "base" agent skill from https://github.com/aspenkit/aspens/tree/main/.agents/skills/base into .agents/skills/base/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "base", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add aspenkit/aspens --skill base -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install aspenkit/aspens base --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/aspenkit/aspens.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/.agents/skills/base .cursor/skills/base && rm -rf skills-src

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "base" agent skill from https://github.com/aspenkit/aspens/tree/main/.agents/skills/base into .cursor/skills/base/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "base", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

gemini skills install

$ gemini skills install https://github.com/aspenkit/aspens.git --path .agents/skills/base

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add aspenkit/aspens --skill base -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install aspenkit/aspens base --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/aspenkit/aspens.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/.agents/skills/base .gemini/skills/base && rm -rf skills-src

Use ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "base" agent skill from https://github.com/aspenkit/aspens/tree/main/.agents/skills/base into .gemini/skills/base/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "base", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install aspenkit/aspens base

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add aspenkit/aspens --skill base -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

$ git clone --depth 1 https://github.com/aspenkit/aspens.git skills-src && mkdir -p .github/skills && cp -r skills-src/.agents/skills/base .github/skills/base && rm -rf skills-src

Use ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "base" agent skill from https://github.com/aspenkit/aspens/tree/main/.agents/skills/base into .github/skills/base/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "base", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add aspenkit/aspens --skill base -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install aspenkit/aspens base --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/aspenkit/aspens.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/.agents/skills/base .opencode/skills/base && rm -rf skills-src

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "base" agent skill from https://github.com/aspenkit/aspens/tree/main/.agents/skills/base into .opencode/skills/base/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "base", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: base
GitHub stars: 102
Token cost: ~1.6k tokens
SKILL.md length: 653 words
Files: 1
Skills in repo: 12
Repo updated: Sep 12, 2026
First seen: Oct 7, 2026
Licence: MIT

At a glance

Orientation to the aspens codebase for agents working on the CLI itself: its Node.js stack, commands, module layout and debug settings.

Making a change to the aspens CLI and needing its command and module map
SKILL.md covers Tech Stack, Commands, Architecture and Critical Conventions, plus 1 more section
Calls npm, codex and node
Finding which lib module handles scanning, graphs, context or skill files

What it does

Aspens is a Node.js (ESM) command-line tool that scans a repository, writes project-specific instructions and skills for Claude Code and Codex CLI, and keeps them current as the code changes. This skill orients an agent inside that repository. The stack is Commander for the CLI, Vitest for tests and es-module-lexer for import analysis, with clack prompts and picocolors for terminal output.

It lists the commands: npm test, aspens scan for deterministic analysis without an LLM, doc init to generate skills, hooks and AGENTS.md for a chosen target, doc impact to report freshness, coverage and drift, doc sync to update skills from git diffs, doc graph to rebuild the import graph cache, and add, customize and save-tokens helpers. The architecture runs from bin/cli.js through command handlers in src/commands to modules in src/lib for scanning, graph building, running the Claude or Codex CLI, assembling context and reading and writing skill files. ASPENS_DEBUG and ASPENS_TIMEOUT control debug dumps and the LLM timeout.

When your agent uses it

Making a change to the aspens CLI and needing its command and module map
Finding which lib module handles scanning, graphs, context or skill files
Debugging an aspens run with the debug dump and timeout settings

Example prompts

“Add a new flag to aspens doc sync and tell me which modules it touches.”
“Where does the import graph get built and persisted in this repo?”
“Run the aspens test suite and explain which part of src/lib a failure points to.”

Requirements

A checkout of the aspens repository
Node.js 20 or later

What it can do on your machine

Read from SKILL.md and the folder at commit 8dde826. It shows what the files ask for, not the result of running them.

Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
Shell commands in SKILL.md call:
- npm
- codex
- node
- claude
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md. Its commands use npm, which can reach the network depending on how they are called.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

aspens Project Conventions loads about 1.6k tokens when it runs. Until then it costs about 17 tokens; SKILL.md has 653 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it: ~17
When it runs · the whole SKILL.md, loaded when a task matches: ~1.6k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from aspenkit/aspens at commit 8dde826, republished under its MIT licence (© aspenkit). 653 words, ~1,602 tokens.

Download SKILL.mdSave it as .claude/skills/base/SKILL.md (or your agent's skills folder).

name: base
description: Core conventions, tech stack, and project structure for aspens
triggers.alwaysActivate: true

You are working in aspens — a CLI that keeps coding-agent context accurate as your codebase changes. Scans repos, generates project-specific instructions and skills for Claude Code and Codex CLI, and keeps them fresh.

Tech Stack

Commands

npm test — Run vitest suite
npm start / node bin/cli.js — Run CLI
aspens scan [path] — Deterministic repo analysis (no LLM)
aspens doc init [path] — Generate skills + hooks + AGENTS.md (--target claude|codex|all, --recommended for full recommended setup)
aspens doc impact [path] — Show freshness, coverage, and drift of generated context (--apply for auto-repair, --backend/--model/--timeout/--verbose for LLM interpretation)
aspens doc sync [path] — Incremental skill updates from git diffs
aspens doc graph [path] — Rebuild import graph cache (.claude/graph.json)
aspens add <type> [name] — Install templates (agents, commands, hooks)
aspens customize agents — Inject project context into installed agents
aspens save-tokens [path] — Install token-saving session settings (--recommended for no-prompt install, --remove to uninstall)
Debug: ASPENS_DEBUG=1 dumps raw stream events to $TMPDIR/aspens-debug-{stream,codex-stream}.json
Env knob: ASPENS_TIMEOUT (seconds) overrides default LLM timeout when --timeout not passed

Architecture

CLI entry (bin/cli.js) → command handlers (src/commands/) → lib modules (src/lib/)

src/lib/scanner.js — Deterministic repo scanner (languages, frameworks, domains, structure)
src/lib/graph-builder.js — Static import analysis via es-module-lexer (hub files, clusters, priority)
src/lib/graph-persistence.js — Graph serialization, subgraph extraction, code-map + index generation
src/lib/runner.js — Claude/Codex CLI wrapper (runClaude for stream-json, runCodex for Codex JSONL); also hosts loadPrompt (partial substitution) and parseFileOutput/validateSkillFiles
src/lib/context-builder.js — Assembles repo files into prompt-friendly context
src/lib/skill-writer.js — Writes skill files and directory-scoped files, generates skill-rules.json, merges settings
src/lib/skill-reader.js — Parses skill files, frontmatter, triggers: blocks, legacy activation patterns, keywords
src/lib/diff-classifier.js — Maps changed files to affected skills for doc-sync
src/lib/diff-helpers.js — Targeted file diffs and prioritized diff truncation for doc-sync
src/lib/git-helpers.js — Git repo detection, git root resolution, diff retrieval, log formatting
src/lib/git-hook.js — Post-commit git hook installation/removal for auto doc-sync (monorepo-aware)
src/lib/impact.js — Context health analysis: domain coverage, hub surfacing, drift detection, hook health, save-tokens health, usefulness summary, value comparison, opportunities
src/lib/save-tokens.js — Save-tokens config defaults, settings builders, gitignore/readme generators
src/lib/timeout.js — Timeout resolution (--timeout flag > ASPENS_TIMEOUT env > default)
src/lib/errors.js — CliError class (structured errors caught by CLI top-level handler)
src/lib/target.js — Target definitions (claude/codex), config persistence (.aspens.json) with saveTokens feature config; getAllowedPaths for multi-target sanitization
src/lib/target-transform.js — Transforms Claude-format output to other target formats
src/lib/backend.js — Backend detection and resolution (which CLI generates content)
src/lib/path-resolver.js / src/lib/source-exts.js — Source-file extension and path resolution helpers shared by scanner/graph
src/lib/parsers/ — Language-specific import parsers (TypeScript, Python)
src/lib/frameworks/ — Framework-specific detectors (e.g. Next.js)
src/prompts/ — Prompt templates with {{partial}} and {{variable}} substitution
src/templates/ — Bundled agents, commands, hooks, and settings for aspens add / doc init / save-tokens

Show full SKILL.md (243 more words)Show less

Critical Conventions

Pure ESM — "type": "module" throughout; use import/export, never require()
es-module-lexer WASM — must await init before calling parse() in graph-builder
Claude CLI execution — runClaude() spawns claude -p with stream-json; always use --verbose flag with stream-json
Codex CLI execution — runCodex() spawns codex exec --json --sandbox read-only --ask-for-approval never --ephemeral; returns { text, usage } matching runClaude interface
Stdin with backpressure — runClaude/runCodex pipe prompts via stdin and respect drain when write() returns false; never rewrite to use args (shell length limits)
Path sanitization — parseFileOutput() restricts writes to .claude/ and AGENTS.md by default; accepts allowedPaths override for multi-target via getAllowedPaths(targets)
Read-only LLM tools — customize-style commands pass allowedTools: ['Read', 'Glob', 'Grep']; never broaden without review
Prompt partials — {{name}} in prompt files resolves to src/prompts/partials/name.md first, then falls back to template variables
Target/Backend distinction — Target = output format/location; Backend = which LLM CLI generates content. Config persisted in .aspens.json. Customize is Claude-only (CliError if targets: ['codex'])
Scanner is deterministic — no LLM calls; pure filesystem analysis
CliError pattern — command handlers throw CliError instead of calling process.exit(); caught at top level in bin/cli.js
Monorepo support — getGitRoot() resolves the actual git root; hooks, sync, and impact scope to the subdirectory project path
Verify before claiming — Never state something is configured/running/done without confirming in-session

Structure

bin/ — CLI entry point (commander setup, CliError handler)
src/commands/ — Command handlers (scan, doc-init, doc-impact, doc-sync, doc-graph, add, customize, save-tokens)
src/lib/ — Core library modules
src/prompts/ — Prompt templates + partials
src/templates/ — Installable agents, commands, hooks, settings
tests/ — Vitest test files

Last Updated: 2026-05-11

Files

Just SKILL.md in .agents/skills/base of aspenkit/aspens.

Open the folder on GitHubat commit 8dde826

Compare with similar skills

aspens Project Conventions next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

aspens Project Conventions compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
aspens Project Conventions this skillaspenkit/aspens	102	—	~1.6k	Automated safety check: Pass	MIT	25 days ago
Octocode Code Researchbgauryy/octocode	946	—	~1.5k	Automated safety check: Pass	MIT	4 days ago
How Does This Work Explainercursor/plugins	10k	6 repos	~771	Automated safety check: Pass	None	today
SPARC Methodologyruvnet/agentic-flow	816	6 repos	~6.3k	Automated safety check: Pass	None	21 days ago
Electron Multi-Process ArchitectureiOfficeAI/AionUi	33k	1 repos	~1.8k	Automated safety check: Pass	Apache-2.0	28 days ago
Code Reviewyaklang/yakit	7.8k	—	~1.4k	Automated safety check: Notes	AGPL-3.0	7 days ago

Similar skills

Octocode Code Research
bgauryy/octocode
Researches code with evidence: traces callers, imports and cross-repo links, diagnoses failures and reports findings with exact file and line references and a confidence label.
946 GitHub stars~1.5k tokensUpdated 4 days ago
DevelopmentAuto-check passed
How Does This Work Explainer
cursor/plugins
Official
Answers how-does-this-work and where-should-this-live questions by exploring the codebase with read-only subagents and writing an onboarding-depth explanation.
10k GitHub starsUsed in 6 repos~771 tokens
DevelopmentAuto-check passed
SPARC Methodology
ruvnet/agentic-flow
Structures complex feature work into five planning-first phases (specification, pseudocode, architecture, refinement and completion) driven through claude-flow commands.
816 GitHub starsUsed in 6 repos~6.3k tokens
DevelopmentAuto-check passed
Electron Multi-Process Architecture
iOfficeAI/AionUi
Tells the agent where new code belongs in an Electron multi-process project and which APIs each process may use, with rules for new bridges, services, agents and workers.
33k GitHub starsUsed in 1 repo~1.8k tokens
DevelopmentAuto-check passed
Code Review
yaklang/yakit
对 Yakit 仓库的代码改动做规范化 code review：按代码逻辑、TS 定义、UI 引用与 Props、CSS 样式、依赖版本、配置项六个维度审查，检查测试用例缺失，强制执行 tsc 类型检查与 vitest 测试验证，输出「结果汇总 / 明细解释 / 合并结论」三块报告，经用户确认后写入文件。当用户要求 review、审查、评审代码改动，或在提交、合并、提 PR…
7.8k GitHub stars~1.4k tokensUpdated 7 days ago
DevelopmentAuto-check: notes
Deepwiki Rs
sopaco/deepwiki-rs
AI-powered Rust documentation generation engine for comprehensive codebase analysis, C4 architecture diagrams, and automated technical documentation.
3.1k GitHub stars~748 tokensUpdated 23 days ago
DevelopmentAuto-check passed

Questions about aspens Project Conventions

What does aspens Project Conventions do?

Orientation to the aspens codebase for agents working on the CLI itself: its Node.js stack, commands, module layout and debug settings. js (ESM) command-line tool that scans a repository, writes project-specific instructions and skills for Claude Code and Codex CLI, and keeps them current as the code changes. This skill orients an agent inside that repository.

When should I use aspens Project Conventions?

aspens Project Conventions fits situations like: making a change to the aspens CLI and needing its command and module map; finding which lib module handles scanning, graphs, context or skill files; debugging an aspens run with the debug dump and timeout settings.

How do I install aspens Project Conventions in Claude Code?

Run `npx skills add aspenkit/aspens --skill base -a claude-code`. Or copy the skill folder (.agents/skills/base in aspenkit/aspens) into .claude/skills/base in your project. Claude Code loads it when a task matches its description.

How do I install aspens Project Conventions in Codex?

Run `npx skills add aspenkit/aspens --skill base -a codex`. Or copy the skill folder (.agents/skills/base in aspenkit/aspens) into .agents/skills/base in your project. Codex loads it when a task matches its description.

Can I use aspens Project Conventions in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add aspenkit/aspens --skill base -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/base, .gemini/skills/base, .github/skills/base and .opencode/skills/base in your project.

What does aspens Project Conventions need to run?

Going by SKILL.md and its folder, aspens Project Conventions needs the command-line tools its instructions call (npm, codex, node and claude). Our summary lists: A checkout of the aspens repository; Node.js 20 or later.

Does aspens Project Conventions access the network?

SKILL.md contains no URLs. Its commands use npm, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is aspens Project Conventions safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does aspens Project Conventions use?

aspens Project Conventions is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does aspens Project Conventions use?

About 1.6k tokens (SKILL.md is roughly 6.4k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to aspens Project Conventions?

Skills that share tags, products or a category with aspens Project Conventions: Octocode Code Research (bgauryy/octocode, 946 stars), How Does This Work Explainer (cursor/plugins, 10k stars), SPARC Methodology (ruvnet/agentic-flow, 816 stars) and Electron Multi-Process Architecture (iOfficeAI/AionUi, 33k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains aspens Project Conventions?

aspenkit (a GitHub organization) maintains it in aspenkit/aspens, which has 102 GitHub stars. The repository holds 12 skills in this directory. The repository was last updated on September 12, 2026.

Source: aspenkit/aspens on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.

aspens Project Conventions

Install aspens Project Conventions

Facts

At a glance

What it does

When your agent uses it

Example prompts

Requirements

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

Tech Stack

Commands

Architecture

Critical Conventions

Structure

Files

Compare with similar skills

Similar skills

Octocode Code Research

How Does This Work Explainer

SPARC Methodology

Electron Multi-Process Architecture

Code Review

Deepwiki Rs

More from aspenkit/aspens

Aspens Agent Template Customizer

Aspens CLI Shell

Aspens Multi-Target Output

Doc Impact

Doc Sync

Import Graph

Questions about aspens Project Conventions

Install aspens Project Conventions

Facts

At a glance

What it does

When your agent uses it

Example prompts

Requirements

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

Tech Stack

Commands

Architecture

Critical Conventions

Structure

Files

Compare with similar skills

Similar skills

More from aspenkit/aspens

Related

Questions about aspens Project Conventions