Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
220 lines (146 loc) · 6.65 KB

CONTRIBUTING.md

File metadata and controls

220 lines (146 loc) · 6.65 KB

Contributing to aweskill

Thank you for being here.

aweskill is built around a simple idea: local tooling should reduce mess, not create new mess. We care about useful features, but we care just as much about preserving a model that stays small, clear, and reliable over time.

This guide is not only about opening a PR. It is also about how we want to evolve aweskill: with explicit tradeoffs, readable code, and respect for the user's filesystem.

Project Direction

aweskill is not trying to become a giant platform.

The project is intentionally centered on a small set of responsibilities:

  • keep one canonical skill store
  • define reusable bundles
  • project skills into multiple agent runtimes
  • provide boring, safe maintenance operations around that workflow

When contributing, please preserve that focus. New features should make the main workflow clearer, safer, or easier to use. They should not turn the tool into a general package manager, remote registry, or configuration platform unless there is a very strong reason.

For the stable command model, projection semantics, and other product-level design constraints, see DESIGN.md.

Development Setup

Keep setup simple and reproducible:

# Clone the repository
git clone https://github.com/mugpeng/aweskill.git
cd aweskill

# Install dependencies
npm install

# Run tests
npm test

# Build the CLI
npm run build

# Local CLI usage during development
npm link
aweskill --help

Windows Development Notes

aweskill supports Windows as a native platform.

When developing or reviewing Windows-related changes:

  • use Node.js 20 or later
  • prefer PowerShell for local command examples
  • remember that agent projections may be created as junctions on Windows
  • if link creation is unavailable, managed copy fallback is acceptable behavior
  • backup and restore should not depend on external Unix tools such as tar

Branches

The repository uses two long-lived branches:

  • main — stable line; what users and downstream tooling should treat as the current release.
  • dev — integration branch where day-to-day development happens.

Workflow: do most development on dev. When a feature is implemented and ready to ship, merge dev into main. Prefer opening PRs against dev unless you are told otherwise.

Code Style

We want the codebase to stay calm and legible.

When contributing, aim for code that feels:

  • Simple: prefer the smallest change that solves the real problem
  • Clear: optimize for the next reader, not for cleverness
  • Honest: keep the filesystem model explicit and avoid hidden state
  • Focused: preserve boundaries between bundle, agent, store, and doctor, and keep top-level convenience commands minimal
  • Durable: choose behavior that is easy to test and reason about

In practice:

  • Runtime language: TypeScript on Node.js 20+
  • CLI framework: commander
  • Tests: vitest
  • Bundles are plain YAML
  • Prefer small, well-bounded functions over large command handlers
  • Prefer improving existing command behavior over adding new top-level concepts

Bundle File Format

Bundles are plain YAML stored under ~/.aweskill/bundles/<name>.yaml:

name: frontend
skills:
  - pr-review
  - frontend-design

Keep the format intentionally small. If a proposal adds state that cannot be understood by opening the YAML file directly, that proposal should face a high bar.

Contribution Guidelines

Keep the mental model coherent

aweskill has a deliberately small command model. Refer to DESIGN.md before changing command placement or adding new CLI surface.

If a contribution adds or changes CLI behavior, first ask which of those areas it truly belongs to. Avoid introducing overlapping commands or synonyms that increase the command surface without adding real capability.

Protect user state

This tool operates on local directories that users care about.

That means contributions should be conservative about:

  • deleting files
  • replacing unmanaged directories
  • introducing hidden activation state
  • automatically rewriting user-owned content without clear boundaries

If a feature changes files, the user should be able to understand what changed and why.

Prefer explicit over magical

aweskill works because its model is inspectable:

  • the canonical store is on disk
  • bundles are plain YAML
  • projected skills are visible in agent directories

Please avoid features that hide core state behind unnecessary abstraction.

Product Semantics

Detailed product semantics now live in DESIGN.md, including:

  • command model and top-level convenience commands
  • projection model
  • import / backup / restore semantics
  • find / install / update behavior
  • hygiene and display rules
  • built-in skill structure

Projection examples

# Global projection for one agent
aweskill agent add skill biopython --global --agent codex

# Project-scoped projection for one agent
aweskill agent add skill pr-review --project /path/to/repo --agent cursor

# Bundle expansion writes individual managed projections
aweskill agent add bundle backend --global --agent codex
aweskill agent remove bundle backend --global --agent codex

# Convert linked projections into copied directories
aweskill agent recover --global --agent codex

Documentation

Documentation changes are welcome and important.

If you change:

  • command names
  • command semantics
  • bundle format
  • projection behavior
  • supported agents
  • find/install/update behavior or provider support

please update the relevant docs in the same change:

  • README.md
  • README.zh-CN.md
  • docs/DESIGN.md
  • tests that define the CLI surface

Testing

Before opening a PR, run:

npm test
npm run build

If you changed command behavior, add or update command-level tests in tests/commands.test.ts.

If you changed low-level behavior, prefer focused tests near the affected modules rather than only relying on broad end-to-end coverage.

Related Projects

aweskill references and learns from several adjacent tools:

These projects helped clarify different parts of the design space:

  • desktop-first multi-tool management
  • CLI-first skill installation and synchronization
  • open skill ecosystem conventions
  • cross-agent local developer workflow tooling

Questions

If you are unsure whether a change fits the project, open an issue first or start with a small documentation or test PR.

Focused contributions are preferred over broad rewrites.