How to Validate and Commit Profile Changes Using `distilly_commit`: A Complete Guide

Use distillycommit validate to check profile JSON/YAML against Distilly's schema before running distillycommit commit to merge changes and create a Git commit.

The distilly_commit command-line utility is the primary interface for managing Person Profile updates in the Distilly skill framework. Located in the titanwings/distilly repository, this tool ensures that every modification to a profile—whether adding a celebrity biography or refining relationship metadata—conforms to strict schema requirements before being persisted to version control.

Understanding the distilly_commit Architecture

The distillycommit CLI is implemented across three key components. The entry point lives in bin/distilly.mjs, which parses subcommands and routes them to the Python backend. Validation logic resides in [tools/skill_schema.py](https://github.com/titanwings/distilly/blob/dot-skill/tools/skill_schema.py), while the actual merging and Git operations are handled by [tools/skill_writer.py](https://github.com/titanwings/distilly/blob/dot-skill/tools/skill_writer.py).

When you invoke a commit command, the tool executes a two-phase workflow:

1. Schema Validation – The profile is checked against family-specific constraints (colleague, relationship, or celebrity types) to ensure required fields and data types are correct.
2. Atomic Commit – After validation passes, skill_writer.py merges the delta into the existing skill tree and executes a Git commit with a descriptive message.

Validating Profile Changes Before Commit

Validation is the mandatory first step in the distillycommit workflow. The validate subcommand runs the profile through Distilly's schema validator, catching structural errors before they reach the repository.

Run validation using:

distillycommit validate path/to/profile.json

The validator, defined in tools/skill_schema.py, checks for:

• Required fields – Ensures mandatory keys like name, type, and attributes are present.
• Data type constraints – Validates that dates, strings, and nested objects match the expected schema.
• Family-specific rules – Enforces logic specific to colleague, relationship, or celebrity profile families.

If validation fails, the command exits with a detailed error list including line numbers:

$ distillycommit validate ./profiles/celeb_karpathy.json
❌ Validation failed: Missing required field "interview_section" at line 42
❌ Validation failed: Invalid data type for "birth_date" at line 15

Committing Validated Profile Changes

Once validation succeeds, use the commit subcommand to persist changes. This command accepts a file path and an optional commit message, performing the full write-and-commit sequence atomically.

distillycommit commit path/to/profile.json \
    --message "Update celeb-profile: Andrej Karpathy – added interview-section"

Under the hood, skill_writer.py handles the operation by:

• Merging the profile delta into the existing skill directory while preserving previous conclusions.
• Staging the modified files in Git.
• Creating a commit with the provided message (or a default descriptive string).

You can verify the commit was created successfully:

git log --oneline -1

# Output: a1b2c3d Update celeb-profile: Andrej Karpathy – added interview-section

Interactive Editing with Built-in Validation

For manual edits, use the edit subcommand to open $EDITOR (falling back to vi) and automatically validate upon save:

distillycommit edit path/to/profile.json \
    --message "Refine relationship profile – added emotional-trigger notes"

This workflow:

1. Launches your default editor with the profile file.
2. Upon saving and closing, automatically runs the validation suite from skill_schema.py.
3. Only proceeds to write and commit if validation passes; otherwise, it reports errors and aborts without creating a commit.

Advanced Usage Patterns

Batch Validation

Validate multiple profiles before committing any changes:

for profile in ./profiles/*.json; do
    distillycommit validate "$profile" || exit 1
done

Custom Commit Messages

If you omit the --message flag, distillycommit generates a default message based on the profile type and timestamp. For production workflows, always specify explicit messages for audit trails.

Integration with CI/CD

Add validation to your continuous integration pipeline to prevent malformed profiles from entering the main branch:

# .github/workflows/distilly-ci.yml

- name: Validate all profiles
  run: |
    find ./skills -name "*.json" -exec distillycommit validate {} \;

Summary

• distillycommit validate checks profile JSON/YAML against the schema in tools/skill_schema.py, reporting line-specific errors before any files are modified.
• distillycommit commit atomically validates, merges the delta via skill_writer.py, stages changes, and creates a Git commit.
• distillycommit edit provides an interactive workflow that validates upon save, ensuring no invalid profiles reach version control.
• The entry point in bin/distilly.mjs routes all subcommands to the Python backend, maintaining consistency across the CLI.

Frequently Asked Questions

What happens if validation fails during a commit command?

If validation fails, distillycommit reports the specific schema errors (including line numbers) and exits without modifying the skill directory or creating a Git commit. This atomic behavior ensures the repository remains in a consistent state.

Can I commit changes without validation?

No. The commit subcommand automatically invokes the validation logic from tools/skill_schema.py before calling skill_writer.py. There is no --skip-validation flag, as enforcing schema compliance is a core design principle of the Distilly framework.

Where does distillycommit create the Git commit?

The commit is created in the local repository where the Distilly skill directory resides. The command stages only the files modified by skill_writer.py and commits them locally. You must run git push separately to transfer the commit to a remote repository.

How do I update multiple profiles at once?

Currently, distillycommit operates on individual files. To batch process multiple profiles, use a shell loop to validate all files first, then commit each one individually, or write a wrapper script that iterates over your profiles directory.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}