updates to skeleton API, notes to guide dev