@prata.ma/anvil-ai

Shared AI harness utilities for governed workspaces.

Overview

@prata.ma/anvil-ai owns the reusable parsing and environment helpers that Anvil uses for AI-harness content. It provides library functions for discovering skills, parsing command and agent markdown files, normalizing remote or local skill sources, resolving agent-specific skill directories, and handling a few git- and search-related support flows.

Within the workspace, this package acts as a utility layer rather than a top-level governance facade. Consumers should depend on @prata.ma/anvil-ai when they need the documented parser and helper contracts instead of reaching directly into package-local scripts or rebuilding source parsing logic.

Installation

Install from npm or consume it through a workspace dependency while developing inside this monorepo.

npm

pnpm add @prata.ma/anvil-ai

Workspace

{
  "dependencies": {
    "@prata.ma/anvil-ai": "workspace:*"
  }
}

Usage

@prata.ma/anvil-ai is used as a library package. The common paths are skill discovery, command parsing, and source normalization.

Library

import {
  detectInstalledAgents,
  discoverSkills,
  parseCommandFile,
  parseSource,
} from '@prata.ma/anvil-ai'

const parsed = parseSource('catalog:forge')
const skills = await discoverSkills(process.cwd(), undefined, { fullDepth: true })
const command = await parseCommandFile('.ai/commands/plan-create.md')
const agents = await detectInstalledAgents(process.cwd())

Patterns

Typical library flows include:

• parse a source string such as catalog:forge, owner/repo, or ./local-skill
• discover SKILL.md files under repo-local skill directories
• parse command and agent markdown frontmatter into normalized definitions
• resolve agent-specific project and global skill directories before install or sync work

API

@prata.ma/anvil-ai exposes a library surface for AI-harness parsing, discovery, environment support helpers, and shared lockfile contract types used by sync-owned Anvil snapshots.

Exports

• @prata.ma/anvil-ai - root export surface for the package
• agent helpers from src/agents.ts, including agents, detectInstalledAgents, getUniversalAgents, and isUniversalAgent
• agent parsing helpers from src/agent-parser.ts, including parseAgentFile and parseAgentFileDetailed
• command parsing helpers from src/command-parser.ts, including parseCommandFile, discoverCommandFiles, discoverSkillCommandFiles, and commandIdToKebab
• git helpers from src/git.ts, including cloneRepo, cleanupTempDir, getGitRoot, getGitRemoteUrl, and normalizeGitRemoteUrl
• skill discovery helpers from src/skill-parser.ts, including discoverSkills, parseSkillMd, filterSkills, and getSkillDisplayName
• source parsing helpers from src/source-parser.ts, including parseSource, parseOwnerRepo, getOwnerRepo, and sanitizeSubpath
• search helpers from src/search.ts, including searchSkillsAPI
• shared package types from src/types.ts, including authored agent definitions and sync-facing lock entry plus summary types

Configuration

• detectInstalledAgents() respects CLAUDE_CONFIG_DIR and CODEX_HOME when resolving global skill directories.
• searchSkillsAPI() reads SKILLS_API_URL and falls back to https://skills.sh.
• skill discovery prioritizes skills/, .agents/skills/, .claude/skills/, .cursor/skills/, .opencode/skills/, and .codex/skills/ before deeper recursive search.
• source parsing supports catalog, local, GitHub, GitLab, generic git, and well-known URL forms.
• Lock-related shared types stay reusable for project/global sync snapshots without pulling sync implementation details into this package.

Development

Use the package-local scripts while working in @packages/anvil-ai, and keep reusable parsing behavior in importable modules under src/ rather than in package-local wrappers.

Commands

pnpm --filter @prata.ma/anvil-ai release:check
pnpm --filter @prata.ma/anvil-ai build
pnpm --filter @prata.ma/anvil-ai lint
pnpm --filter @prata.ma/anvil-ai test
pnpm --filter @prata.ma/anvil-ai test:type

Testing

The current Vitest coverage focuses on source parsing, command frontmatter parsing, one-file agent parsing, and skill discovery behavior.

Conventions

• Keep parser behavior grounded in observable file and source formats rather than tool-specific heuristics.
• Preserve the safe-path and traversal checks around discovered subpaths and temp-directory cleanup.
• Treat src/index.ts as the supported library boundary; avoid creating undocumented deep-import expectations.

Status

This package is active and supports the shared AI-harness utility layer in the workspace.

Maturity

@prata.ma/anvil-ai is active and publish-prepared.

Scope

The package currently supports parser and helper contracts for skills, commands, sources, agent directory resolution, and a few git/search support flows. Governance sync orchestration and user-facing Anvil commands belong elsewhere.

Notes

• @prata.ma/anvil-ai now participates in the repo's Changesets, npm publish, and GitHub Release automation.
• The supported surface is the library API exported from @prata.ma/anvil-ai; there is no documented package-level CLI contract in package.json today.
• Changes to parser behavior can ripple into governed commands, governed agents, skill discovery, and sync flows across the repo, so they should be reviewed carefully.