openskills

OpenSkills – Technical Briefing Repo: https://github.com/moses-y/openskills Clone: git clone https://github.com/moses-y/openskills

1. Overview

OpenSkills is an npm‑distributed CLI that normalises Anthropic’s SKILL.md format for any AI coding agent. The package ships a single entry point (src/cli.ts) and a set of sub‑commands (install, list, update, sync, …) that operate on a local skill directory (default .claude/skills). The repository contains 94 files, 27 TypeScript source files, a full test suite (10 tests), CI (GitHub Actions), and an Apache‑2.0 licence.

2. How It Is Wired

Execution start – src/cli.ts parses the command line and dispatches to the matching command module under src/commands/.

Typical install flow (npx openskills install <source>):

1. cli.ts → install.ts – parses flags, resolves the source string.
2. install.ts validates the source with helpers: * isLocalPath, isGitUrl, expandPath, isPathInside (all defined in the same file).
3. Depending on the source type, one of: installFromLocal → installSingleLocalSkill → hasValidFrontmatter (via yaml.ts). installFromRepo → extractYamlField (via yaml.ts) → writeSkillMetadata (via skill-metadata.ts).
4. Metadata functions (readSkillMetadata, writeSkillMetadata) store provenance in src/utils/skill-metadata.ts.
5. printPostInstallHints is called twice to surface next‑step advice.

Update flow (openskills update):

• src/commands/update.ts → updateSkills → updateSkillFromDir → writeSkillMetadata.
• Re‑uses isPathInside from install.ts and hasValidFrontmatter from yaml.ts.

Sync flow (openskills sync):

• src/commands/sync.ts → syncAgentsMd → parseCurrentSkills / generateSkillsXml (in utils/agents-md.ts).
• The generated XML is written into AGENTS.md for any agent that reads that file.

Core utilities

The import graph shows 27 internal modules, 37 import edges, and no circular dependencies. The most “unstable” module is src/cli.ts (instability 1) because it imports many others but is not imported itself.

3. Test & Documentation

• Tests – 10 Vitest files covering commands, utils, and an end‑to‑end integration test (tests/integration/e2e.test.ts).
• Docs – README.md, AGENTS.md, CONTRIBUTING.md, and a changelog.

All tests pass locally (npm test runs vitest). No missing test files for core utilities were observed.

4. Code Health & Issues

Static‑analysis findings

Maintainability finding

• Duplicated code blocks – 8 identical 6‑line snippets appear in src/commands/install.ts, src/commands/update.ts, src/commands/list.ts, and related test files. Extracting these into shared helpers would reduce repetition and simplify future changes.

No critical or high‑severity defects were detected; the repository includes a lockfile, licence, and CI.

5. Recommendations

• Refactor duplicated logic into a new utility (e.g., src/utils/skill-install-helpers.ts) and adjust the three command modules to import it.
• Add least‑privilege token permissions and persist-credentials: false to the checkout step to reduce CI attack surface.
• Configure Dependabot (.github/dependabot.yml) for npm and GitHub‑Actions, and add a dependency‑review action to the CI workflow.
• Set explicit job timeouts (timeout-minutes: 30) to avoid overlapping runs on scheduled pipelines.

6. Bottom Line

OpenSkills delivers a focused, well‑tested CLI that cleanly maps Anthropic skill files onto a universal AGENTS.md format. The codebase is modular, free of circular imports, and backed by CI. Primary technical debt lies in duplicated command snippets and missing CI hardening (token scope, dependency scanning). Teams needing a language‑agnostic skill loader can adopt it now, applying the modest refactors above to improve maintainability and security.